​
🧩 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

​
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.