​

🧩 API Integration Guide

Welcome! This guide will walk you through integrating with our API — from authentication and setup to placing orders and receiving updates.

​

📘 Table of Contents

• 🧩 API Integration Guide
  • 📘 Table of Contents
  • 1. 🛡️ Obtain Credentials
    • 🔧 Steps:
  • 2. 🌍 Retrieve Supported Geo Coverage, Assets, and Payment Methods
  • 3. 👤 Onboard a User
    • 📥 Endpoint
    • 📦 Sample Payload
    • ✅ Response
  • 4. 🔎 User Verification (KYC)
    • 🛠️ Endpoint
    • 🚦 Response
  • 5. 💱 Fetch a Quote
    • 🌐 Endpoint
    • 📝 Sample Payload
    • 📊 Response Includes:
  • 6. 🛒 Execute an Order
    • 🌐 Endpoint
    • 📝 Sample Payload
    • ✅ Response:
  • 7. 🔔 Get Status Updates via Webhooks
    • ⚙️ Steps:
    • 📨 Sample Webhook Payload:
  • 8. 🔁 Fetch the Order Status
    • 🌐 Endpoint
    • 📤 Response Includes:
  • ✅ You’re All Set!

​

1. 🛡️ Obtain Credentials

To access the API, you must first obtain your API key and secret. These authenticate your requests and track usage.

​

🔧 Steps:

• Contact the Sardine integration team. They will generate a client_id and client_secret for your use.
• Store both the client_id and client_secret securely.

🔐 Security Tip: Never expose your secret in frontend apps. Use a backend service to interact with the API.

​

2. 🌍 Retrieve Supported Geo Coverage, Assets, and Payment Methods

Use the following endpoints to fetch dynamic metadata for your UI:

• GET /v1/geo-coverage — Supported countries/regions.
• GET /v1/supported-tokens — Available cryptocurrencies and fiat currencies.

Use this info to populate dropdowns and validate inputs client-side.

​

3. 👤 Onboard a User

Before placing an order, the user must be onboarded and registered in the system.

​

📥 Endpoint

POST /v1/customers

​

📦 Sample Payload

{
  "email": "user@example.com",
  "phone": "+1234567890",
  "country": "US"
}

​

✅ Response

Returns a customerId which must be used in all user-specific operations.

​

4. 🔎 User Verification (KYC)

Depending on jurisdiction or transaction volume, KYC verification may be required.

​

🛠️ Endpoint

POST /v1/onramp/customers/{id}/verify

You may be asked to:

• Upload an ID document.
• Submit a selfie.
• Redirect to a hosted KYC flow.

​

🚦 Response

Returns a verification_status:

• pending
• approved
• rejected

​

5. 💱 Fetch a Quote

Before placing an order, fetch a quote to show the user a guaranteed rate and fee breakdown.

​

🌐 Endpoint

POST /v1/quotes

​

📝 Sample Payload

{
  "user_id": "abc123",
  "asset": "BTC",
  "fiat_currency": "USD",
  "amount": "100.00",
  "payment_method": "card"
}

​

📊 Response Includes:

• Exchange rate
• Fees
• Quote expiry
• quote_id (used when placing an order)

​

6. 🛒 Execute an Order

Place an order based on an approved quote.

​

🌐 Endpoint

POST /v1/orders

​

📝 Sample Payload

{
  "user_id": "abc123",
  "quote_id": "quote789",
  "payment_method": "card",
  "destination_wallet": {
    "type": "crypto",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "asset": "BTC"
  }
}

​

✅ Response:

Includes order_id and the initial status.

​

7. 🔔 Get Status Updates via Webhooks

Set up webhooks to get real-time updates on order progress and compliance events.

​

⚙️ Steps:

• Register your webhook URL in the Developer Portal.
• Your endpoint should be HTTPS and respond with 2xx.

​

📨 Sample Webhook Payload:

{
  "event": "order.status.updated",
  "order_id": "order123",
  "status": "completed",
  "timestamp": "2025-04-17T12:34:56Z"
}

✅ Validate webhook signatures and implement retry logic for maximum reliability.

​

8. 🔁 Fetch the Order Status

Poll this endpoint for order updates if webhooks aren’t available or for manual checks.

​

🌐 Endpoint

GET /v1/orders/{order_id}

​

📤 Response Includes:

• Current status: pending, processing, completed, failed
• Timestamps
• Payment and asset transfer details

​

✅ You’re All Set!

Once these steps are implemented, you’ll have full integration from onboarding to real-time tracking. For additional topics like error handling, retries, or sandbox mode, check out the Extended Developer Docs.