Skip to navigation
API ReferenceOffers and Breakdowns

Create a trade breakdown

Create a trade breakdown.

Credential: Customer session

Before you call

  • A customer session for the same partner, integration, customer, wallet and chain.
  • An active saved account matching the catalog payment method.
  • A registered customer wallet and supported chain.
  • Set an Idempotency-Key and reuse it for an identical retry.

Creates a priced, time-limited breakdown for the customer to review and sign. Send the selected offer’s breakdownInput unchanged, including its normalized amount, paymentMethodId and savedPaymentMethodId. For a new FIAT search, amount is a USDT quantity: keep it rather than substituting the original fiat input. Selections issued earlier with a FIAT amount keep their original meaning: a spending cap on a BUY, or a receiving floor on a SELL.

If you change the selection, the call returns 409 CONFLICT. A selection that no longer exists can return 404. Sinbad rechecks the current price, fees, inventory and eligibility. Show the returned tradeDetails to the customer before they sign.

One open trade per side. A breakdown holds the customer’s open trade on its side, for your partner and that customer, without creating a funded trade. A request with a new Idempotency-Key replaces the customer’s earlier breakdown on that side if no escrow transaction was submitted for it, and the response includes a fresh escrowTransaction. Sign from the latest response. Repeating the key of a replaced breakdown returns 409 CONFLICT. If the earlier breakdown was submitted, funded or is under review, the request fails with 409 CONFLICT and details.reason: ACTIVE_TRADE_EXISTS. Funding carries the customer’s open trade into the funded trade. A final trade status or a customer-opened dispute releases it. A merchant-opened dispute does not.

Replacing a breakdown does not cancel an escrow transaction that the wallet already sent. That transaction can still fund escrow until its original signing deadline, and it creates its own trade with its original pricing. Keep reporting the hashes of transactions you already sent through POST /v1/transactions. Do not request a replacement while a wallet send is pending or its outcome is unknown, including before you have reported its hash.

The response includes escrowTransaction and the current approvalRequired and approval values. Use to, data, value, chainId and from unchanged. Required approvals must succeed before the escrow transaction, and a wallet that supports batching can run them in order in one batch. Preparing needs no gas balance. With an ordinary signed transaction, the customer’s wallet pays gas in POL. Partners that execute through smart accounts arrange signing, execution and any gas sponsorship themselves.

Submit the signed transaction, or report the included blockchain transaction hash, with the preparationId through POST /v1/transactions. A trade exists only after an escrow transaction is confirmed successfully, and it starts as CREATED. After an uncertain send or an expired signing window, track the breakdown. Do not start another transaction while the outcome is unknown.

Offer searches and breakdown creation share 60 requests per minute for each customer and integration. Requests that pass validation count, including idempotent replays and requests with no key. A 429 response includes Retry-After. A BUY whose merchant no longer has enough liquidity returns 409 INSUFFICIENT_LIQUIDITY. A SELL with too little token balance returns 400 INSUFFICIENT_BALANCE and can leave the customer’s open SELL held: top up, then repeat the identical body and key while the breakdown is live. An identical retry returns the original breakdown and deadline.

Sinbad keeps unused offer selections for 30 days, and consumed selections and breakdown idempotency keys for one day. Request a fresh offer after that. To correct an escrow hash that was reported wrongly, see POST /v1/transactions.

Confirm with Sinbad that this endpoint is enabled in your environment.

Errors

StatusCodeWhat to do
400VALIDATION_ERRORCorrect the fields reported in details before retrying.
401UNAUTHENTICATEDCreate a new customer session or use a valid server credential.
403FORBIDDENCheck credential ownership, integration and the supplied Origin.
404NOT_FOUNDCheck the resource ID. A resource that belongs to someone else also returns 404.
409CONFLICTRead the current state again before you prepare or retry.
429RATE_LIMITEDWait for Retry-After before retrying.
503UPSTREAM_ERRORRetry with backoff; preserve the same idempotency key for a repeated mutation.
400INSUFFICIENT_BALANCEThe SELL token balance is too low. Top up, then repeat the identical request with the same key while the breakdown is live. The customer’s open SELL can already be held.
409INSUFFICIENT_LIQUIDITYThe BUY merchant no longer has enough liquidity. Recover any transaction you already submitted before you ask for a new offer.
409CONFLICTdetails.reason ACTIVE_TRADE_EXISTS means the customer already has a trade, or a breakdown with a submitted escrow transaction, on that side. Show the existing trade, or wait for it to finish. A breakdown with no submitted escrow transaction does not cause this: a new idempotency key replaces it.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

Idempotency-KeystringRequiredformat: "^[A-Za-z0-9_-]{8,128}$"

Request

This endpoint expects an object.
sideenumRequired
Allowed values:
tokenSymbolenumRequired
Allowed values:
fiatCurrencyIdstringRequired
paymentMethodIdstringRequired
Required catalog method owned by the customer through an active saved account.
savedPaymentMethodIdstringRequired
amountobjectRequired

Copy the selected breakdownInput amount unchanged. New searches use USDT, including when discovery input was FIAT. Older issued FIAT selections retain their original final-fiat semantics.

offerIdstringRequired
fingerprintstringRequired
Opaque signed preview fingerprint
displayCalculationModeenumOptionalDefaults to DUMMY

Card/Sheet display only. DUMMY uses a $10 USD example; REAL uses the actual requested or suggested amount. Execution always uses actual pricing. Preserve in issued breakdownInput.

Allowed values:
scheduled_atstringOptional

Optional ISO 8601 date-time, formatted YYYY-MM-DDTHH:mm[:ss[.SSS]][Z|±HH:MM]. Fractional seconds accept at most 3 digits, so truncate 6-digit values such as .190505 to milliseconds. An offset-free value uses timezone, or UTC if timezone is omitted. A value with Z or an explicit offset keeps that offset and ignores timezone. Normalized to UTC in breakdownInput. Filters merchant hours only; does not delay execution. Malformed, invalid or ambiguous local times (such as during a daylight saving change) are rejected with VALIDATION_ERROR.

timezonestringOptional

Optional IANA timezone name such as Asia/Karachi. Used only for an offset-free scheduled_at and ignored when scheduled_at has Z or an offset. Merchant hours use the merchant timezone at the scheduled instant.

minRatingPercentdoubleOptional0-100

Optional minimum merchant rating; unrated merchants do not match.

minTradeCountintegerOptional0-9007199254740991
Optional minimum recorded merchant trade count.
ignoreMerchantOnlinebooleanOptionalDefaults to false
Include offline merchants. Preserve this value when creating a breakdown.
ignoreTradingHoursbooleanOptionalDefaults to false

Skip only supplied scheduled-hours filtering, including for alternatives. Preserve this value when creating a breakdown.

Response

Financial breakdown, prepared escrow call, approval state and current submission status.
merchantobject

Offer values are current observations; breakdown POST, GET and retries return the same creation snapshot.

breakdownIdstring
createdAtdatetime
expiresAtdatetime
Fresh breakdown creation plus 300 seconds.
serverTimedatetime
sideenum
Allowed values:
statusenum
Confirmed escrow outcome, independent of optional transaction tracking.
Allowed values:
tradeIdstring or null
tradeDetailsobject

Send exactly one of: YouPay, or YouReceive.

merchantRateDetailsobject
fiatCurrencyobject
paymentMethodobject
submissionobject or null
escrowTransactionobject or map from strings to anyOptional

Use this escrow call after approvals confirm. Nonce/gas/fees are populated by the signer, not pinned before approval.

approvalRequiredbooleanOptional
Allowance when the breakdown was created. Sinbad rechecks it when you submit.
approvalobject or map from strings to anyOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
503
Service Unavailable Error