Skip to navigation
Getting started

Quick start

By the end of this page you will have created a customer session, found an offer, created a breakdown and submitted the signed escrow transaction for a BUY trade. The examples use the staging environment, and the full flow is in the Buy walkthrough.

Before you start

You need the following from Sinbad onboarding and from your own systems.

You needWhere it comes from
The staging base URLIntroduction. The examples call it $SINBAD_API.
A partner secret (sk_…)Sinbad issues it once. Store it on your server only.
Your integration IDSinbad onboarding.
A customer wallet with a little POLThe wallet pays network fees for every transaction it signs.

1. Create a customer session

Your server creates a session for the customer who is signed in to your product. The first request for a customer must include their full name, a verified email address, a wallet address and a chain ID. Later requests need only integrationId and partnerUserId.

curl -X POST "$SINBAD_API/v1/sessions" \
  -H "Authorization: Bearer $SINBAD_PARTNER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "integration_demo",
    "partnerUserId": "customer_demo",
    "fullName": "Alex Example",
    "dateOfBirth": "1995-04-12",
    "country": "GB",
    "email": "alex@example.com",
    "emailVerified": true,
    "walletAddress": "0x19e7e376e7c213b7e7e7e46cc70a5dd086daff2a",
    "chainId": 80002
  }'

Sinbad returns the session token and its lifetime.

{
  "sessionToken": "eyJhbGciOiJSUzI1NiJ9.example.signature",
  "sessionId": "session_demo",
  "expiresIn": 86400,
  "expiresAt": "2026-10-24T10:00:00.000Z",
  "userId": "user_demo",
  "kycStatus": null,
  "isNewUser": true
}

Pass the sessionToken to your customer app. Every call in the remaining steps uses it as the bearer credential. See Create a session for returning customers and quotas.

Never send the partner secret to a browser or mobile app. Only your server calls POST /v1/sessions.

2. Save a payment account

The customer needs a saved fiat account for the payment method they will use.

  1. Read the catalog with GET /v1/payment-methods/catalog. Each method lists its requiredFields and the field that identifies an account.
  2. Collect those fields from the customer and submit them with POST /v1/me/payment-methods.

Sinbad matches offers only to a saved account that is active and uses the same catalog payment method. See Saved payment accounts.

3. Find an offer

Ask for an offer with POST /v1/offers/best. This example looks for a BUY of 100 USDT, paid by bank transfer.

curl -X POST "$SINBAD_API/v1/offers/best" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "side": "BUY",
    "tokenSymbol": "USDT",
    "fiatCurrencyId": "usd",
    "paymentMethodId": "bank_transfer",
    "amount": { "mode": "USDT", "value": "100" }
  }'

The response lists matching instant offers and, if none matches exactly, alternatives. Each offer includes its pricing and a breakdownInput that you send unchanged in the next step.

4. Create a breakdown

Create the breakdown with POST /v1/trade-breakdowns. Send the offer’s breakdownInput exactly as received, with an Idempotency-Key header that you reuse only for an identical retry.

{
  "side": "BUY",
  "tokenSymbol": "USDT",
  "fiatCurrencyId": "usd",
  "paymentMethodId": "bank_transfer",
  "amount": { "mode": "USDT", "value": "100" },
  "savedPaymentMethodId": "account_demo",
  "offerId": "offer_demo",
  "fingerprint": "preview_fingerprint_from_offer_search"
}

Sinbad responds with 201. The response contains the breakdownId, status: "AWAITING_FUNDING", an expiresAt 300 seconds (5 minutes) after creation, the final numbers in tradeDetails, and the escrowTransaction for the customer’s wallet to sign. Show tradeDetails to the customer before they sign.

A breakdown holds the customer’s open trade for that side until the trade ends, the customer opens a dispute or the breakdown expires. See Offers and breakdowns.

5. Sign, submit and track

  1. Have the customer’s registered wallet sign escrowTransaction. Keep its to, data and value unchanged.

  2. Send the signed transaction with POST /v1/transactions. Include the preparationId and an Idempotency-Key.

    {
      "preparationId": "preparation_escrow",
      "signedTransaction": "0x02f893…"
    }

  3. Poll GET /v1/transactions/{preparationId} until transaction.status is CONFIRMED, or poll the breakdown until status is CONFIRMED and tradeId is set.

A 202 response means Sinbad accepted the transaction and started tracking it. The trade exists, with status CREATED, only after the escrow is confirmed on chain. Sinbad also detects funding directly from the chain, so a submission you miss is still picked up.

Next steps