Sinbad Partner API

A trade starts when its escrow is funded and confirmed on chain, and it ends with RELEASED or CANCELED. Before funding there is only a breakdown. This page explains each step, and the status table at the end shows who can act in each state.

1. Fund the escrow

Create a breakdown, handle any token approvals and have the customer’s wallet execute the prepared escrow transaction. Then report it through POST /v1/transactions. The breakdown holds the customer’s open trade on that side until the trade ends, the customer opens a dispute or the breakdown expires. See One open trade per side.

2. Wait for confirmation

Submit the transaction hash or the signed transaction, then wait for the breakdown to show CONFIRMED or for the trade to appear as CREATED. No trade exists before funding. Sinbad also detects funding directly from the chain. Use GET /v1/transactions/{preparationId}, GET /v1/trade-breakdowns/{breakdownId} and GET /v1/trades/{tradeId} to follow it.

3. Exchange messages and evidence

Use the same trade ID for chat and payment proof. The merchant continues to use the Sinbad app. See Chat and images and Payment proof.

4. Choose a permitted action

Each action has its own page with the role, state, timing and complete prepare and submit examples: markPaid, release, cancelPrePaid, openDispute and mutualResolveDispute. See also Trade actions.

Trade statuses and actions

Trade status diagram

A trade exists only after funding is confirmed on chain, and its first status is CREATED. Confirmed on-chain events change the status, in block order. You can read the status with GET /v1/trades/{tradeId} and receive it in the trade.created and trade.updated webhooks. Do not wait for PENDING, FUNDING_FAILED or FUNDING_EXPIRED. Sinbad does not produce them, and before funding is confirmed there is only a breakdown.

Status	Meaning	What moves it on
`CREATED`	Funding is confirmed on chain. The trade exists.	BUY customer: `markPaid` or `cancelPrePaid`. SELL customer: waits for the fiat, or opens a dispute after the dispute window.
`PAID`	The fiat payer marked the payment as sent: the customer on a BUY, the merchant on a SELL.	SELL customer: `release` or `openDispute`. BUY customer: `openDispute` after the dispute window.
`DISPUTED`	A dispute is open.	The customer: `mutualResolveDispute`, a resolution signed by the customer only. Or Sinbad support. The trade then ends `RELEASED` or `CANCELED`.
`RELEASED`	Final. The crypto went to the buyer.	Nothing.
`CANCELED`	Final. The crypto went back to the seller who locked it.	Nothing.

availableActions on a trade lists candidate actions. The real check happens when you prepare an action. If you prepare openDispute too early, it fails with 409 CONFLICT and details.reason: "TOO_EARLY". When the customer opens a dispute, their open trade on that side is released. A dispute that the merchant opens does not release it.