> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getsinbad.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getsinbad.com/_mcp/server.

# Quick start

> Create a customer session, save a payment account and fund your first trade on staging.

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](/buy-walkthrough).

## Before you start

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

| You need                            | Where it comes from                                                                |
| ----------------------------------- | ---------------------------------------------------------------------------------- |
| The staging base URL                | [Introduction](/introduction#quick-reference). The examples call it `$SINBAD_API`. |
| A partner secret (`sk_…`)           | Sinbad issues it once. Store it on your server only.                               |
| Your integration ID                 | Sinbad onboarding.                                                                 |
| A customer wallet with a little POL | The 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`.

```bash
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.

```json
{
  "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](/sessions) for returning customers and quotas.

> **Warning**
>
> 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`](https://docs.getsinbad.com/api-reference/reference-data/list-payment-method-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`](https://docs.getsinbad.com/api-reference/payment-accounts/create-saved-payment-method).

Sinbad matches offers only to a saved account that is active and uses the same catalog payment method. See [Saved payment accounts](/payment-accounts).

## 3. Find an offer

Ask for an offer with [`POST /v1/offers/best`](https://docs.getsinbad.com/api-reference/offers-and-breakdowns/find-best-offer). This example looks for a BUY of 100 USDT, paid by bank transfer.

```bash
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`](https://docs.getsinbad.com/api-reference/offers-and-breakdowns/create-trade-breakdown). Send the offer's `breakdownInput` exactly as received, with an `Idempotency-Key` header that you reuse only for an identical retry.

```json
{
  "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.

> **Note**
>
> 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](/offers-quotes#one-open-trade-per-side).

## 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`](https://docs.getsinbad.com/api-reference/transactions/submit-prepared-transaction). Include the `preparationId` and an `Idempotency-Key`.

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

3. Poll [`GET /v1/transactions/{preparationId}`](https://docs.getsinbad.com/api-reference/transactions/get-prepared-transaction-status) 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

* Follow the whole trade in the [Buy walkthrough](/buy-walkthrough) or [Sell walkthrough](/sell-walkthrough).
* Learn how signing, network fees and retries work in [Wallets and gas](/wallets-and-gas).
* Receive updates without polling with [Webhooks](/webhooks).