> 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. # Offers and breakdowns > Find an offer, create a breakdown and show the customer the exact terms before they sign. An offer is a merchant's executable terms for a trade. A breakdown is Sinbad's priced, time-limited quote for one offer, and it carries the prepared transaction that funds the trade. A breakdown saves the terms but does not create a trade: a trade exists only after funding is confirmed on chain. ## Find matching offers Call [`POST /v1/offers/best`](https://docs.getsinbad.com/api-reference/offers-and-breakdowns/find-best-offer) with the customer's side (`BUY` or `SELL`), the token, the fiat currency, an amount and the catalog payment method. The amount has a `mode` and a `value`: * With `mode: "FIAT"`, `value` is the market value of the token in the selected fiat currency, before merchant margin and fees. Sinbad converts it to USDT at the current market rate, rounded down to six decimals. The final fiat payment includes merchant pricing and fees, so it can differ from the amount entered. * With `mode: "USDT"`, `value` is an exact token quantity. `paymentMethodId` is required. On a SELL, always send `savedPaymentMethodId` to choose the receiving account. If you omit it, Sinbad selects the customer's first active matching account. The response contains one `instant` offer or up to three `alternatives`. Each offer includes `pricing`, display data and a `breakdownInput`. New fiat searches return a canonical USDT amount in `breakdownInput`, so the token quantity stays the same through checkout. A closest-amount suggestion can change that quantity. If no inventory matches, or the amount is outside every listing's limits, the call returns `200` with empty results. If the only match is a listing that uses the customer's own wallet, it fails with `400 VALIDATION_ERROR` and `details.reason: "SELF_TRADE_NOT_ALLOWED"`. ### How offers are chosen * **Trading hours.** Sinbad checks a merchant's hours only when you send `scheduled_at`. Setting `ignoreTradingHours` to `true` bypasses that check for exact and alternative offers. A merchant's online status is checked independently. * **Merchant preference.** Exact offers prefer merchants who are not busy and whose effective margin is at most 2%. If no such merchant exists, Sinbad can fall back to busy merchants or higher margins. Alternatives keep the 2% cap and the workload exclusions. * **Merchant details.** Offers, alternatives and breakdowns include the merchant's `fullName`, `avatarUrl`, `username`, `ratingPercent`, `tradeCount`, `isSuperMerchant` and `experienceYears`. A breakdown snapshots these values when it is created. Trade history keeps its existing name and avatar display. * **Display amounts.** `displayCalculationMode` is `DUMMY` by default, which shows the Card and Sheet values for a fixed 10 USD example. Choose `REAL` to show the actual requested or suggested amount. Keep the returned `breakdownInput` unchanged either way, because pricing, breakdowns and transactions always use the actual amount. ## Create the breakdown Call [`POST /v1/trade-breakdowns`](https://docs.getsinbad.com/api-reference/offers-and-breakdowns/create-trade-breakdown) with the chosen offer's `breakdownInput`, unchanged, and an `Idempotency-Key` header. Sinbad rechecks the current price, fees, availability and eligibility, then returns the exact terms in `tradeDetails` and the prepared `escrowTransaction`. Show `tradeDetails` to the customer before they sign. Repeating the call with the same key and body returns the same breakdown and the same deadline. A different body with the same key returns `409 CONFLICT`. A breakdown has a fixed signing window of 300 seconds (5 minutes) from creation. Reading it does not extend the window. ## Review before signing Read the breakdown again with [`GET /v1/trade-breakdowns/{breakdownId}`](https://docs.getsinbad.com/api-reference/offers-and-breakdowns/get-trade-breakdown) to check its status. If a SELL needs a token approval, call [`POST /v1/trade-breakdowns/{breakdownId}/approval`](https://docs.getsinbad.com/api-reference/transactions/prepare-token-approval) and confirm each approval before the customer signs the escrow transaction. See [Sell walkthrough](/sell-walkthrough). ## One open trade per side Each customer can have one open BUY and one open SELL at a time, scoped to your partner and that customer. Creating a breakdown holds the customer's place on its side without creating a funded trade. Funding then carries that place into the trade. ### Refresh a price by replacing the breakdown To get a fresh price, create another breakdown on the same side with a new `Idempotency-Key`. If no escrow transaction has been reported for the earlier breakdown, Sinbad replaces it and returns a new `escrowTransaction` in the same response. Always sign from the latest response. After a breakdown is replaced: * Reading it, or repeating its original `Idempotency-Key`, returns `409 CONFLICT`. * Repeating the key of the current breakdown, with the same body, returns that breakdown with its original deadline. ### When creating a breakdown fails If the earlier breakdown's escrow transaction was already submitted, funded or put under review (`REVIEW_REQUIRED`), the new request fails with `409 CONFLICT` and `details.reason: "ACTIVE_TRADE_EXISTS"`. Show the customer their existing trade instead of asking again. ### When the customer's place is released Sinbad releases the customer's place on a side when: * the trade reaches a final status (`RELEASED` or `CANCELED`), * the customer opens a dispute, or * the breakdown expires without being funded. A dispute that the merchant opens does not release it. If an escrow transaction was reported for the breakdown, Sinbad releases the place only after it confirms on chain that the breakdown expired. That can happen shortly after the 300-second deadline. > **Warning** > > Replacing a breakdown does not cancel an escrow transaction that the customer's wallet has already sent. That transaction can still fund a trade until its original deadline, and it creates its own trade with its original pricing. Keep reporting the hash of every transaction you sent to [`POST /v1/transactions`](https://docs.getsinbad.com/api-reference/transactions/submit-prepared-transaction). Never request a replacement while a wallet send is pending or its outcome is unknown, including before you have reported its hash. If a replaced breakdown is funded anyway, reading it returns `CONFIRMED` with its original pricing. It has no new `escrowTransaction` or approval transactions to sign. ## Related * [Buy walkthrough](/buy-walkthrough) and [Sell walkthrough](/sell-walkthrough) for the full flows. * [Limits and limitations](/limits-and-limitations#rate-limits) for the shared offer and breakdown rate limit. * [Errors and recovery](/errors) for every error code.