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

# Sign and track transactions

> Execute prepared transactions with the customer's wallet and follow them until the escrow is confirmed.

Every blockchain step in Sinbad follows the same pattern, whichever wallet the customer uses: Sinbad prepares a transaction, the customer's wallet signs it, you submit it through one API, and you track it until it is confirmed. This page describes the pattern. [Wallets and gas](/wallets-and-gas) has the signing, fee and retry details.

## The four steps

| Step       | What you do                                                                                                                             | Call                                                                                                                                                                                                        |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Prepare | If the allowance is too low, ask Sinbad for the approval transactions and run them in order. One at a time, wait for each to confirm.   | [`POST /v1/trade-breakdowns/{breakdownId}/approval`](https://docs.getsinbad.com/api-reference/transactions/prepare-token-approval)                                                                                                  |
| 2. Sign    | Have the customer's registered wallet sign the prepared transaction, keeping it unchanged. The wallet fills in the nonce, gas and fees. | [`GET /v1/trade-breakdowns/{breakdownId}`](https://docs.getsinbad.com/api-reference/offers-and-breakdowns/get-trade-breakdown), [`POST /v1/trades/{tradeId}/actions/{action}/execution`](https://docs.getsinbad.com/api-reference/trade-actions/prepare-partner-customer-action) |
| 3. Submit  | Send the `preparationId` with either `signedTransaction` (Sinbad sends it) or `transactionHash` (your wallet already sent it).          | [`POST /v1/transactions`](https://docs.getsinbad.com/api-reference/transactions/submit-prepared-transaction)                                                                                                                                                         |
| 4. Track   | Poll until the transaction and then the trade are confirmed, or use webhooks.                                                           | [`GET /v1/transactions/{preparationId}`](https://docs.getsinbad.com/api-reference/transactions/get-prepared-transaction-status), [`GET /v1/trades/{tradeId}`](https://docs.getsinbad.com/api-reference/trades/get-partner-trade)                                                              |

For `transactionHash`, report the hash of the transaction that was included in a block, as a block explorer shows it. Keep the same `Idempotency-Key` when you retry. No separate reporting endpoint exists.

## Track confirmed funding

Poll the breakdown, or consume signed trade webhooks. A breakdown moves from `AWAITING_FUNDING` to `CONFIRMED` after Sinbad verifies the escrow events on chain. The status of a transaction attempt is a separate value.

* `202` means Sinbad accepted the submission, not that the trade is funded.
* After the signing deadline passes, keep tracking until the breakdown shows confirmed funding or an on-chain `EXPIRED`. Confirmation can finish after the deadline.
* `REVIEW_REQUIRED` needs investigation. Contact Sinbad and do not submit again.
* Track the submitted prepared transaction as well as the breakdown.

## Rules that affect every submission

* An `Idempotency-Key` is 8 to 128 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`. It is bound to the prepared transaction and to the transaction you send. Reusing it with a different transaction returns `409 CONFLICT`.
* Before Sinbad sends signed bytes, it simulates the call. If the simulation fails, the response is a generic `503 UPSTREAM_ERROR` with no reason. Retrying the same call does not help. Check the customer's balance, allowance and trade state.
* If the wallet has too little POL for the network fee, the response is `400 INSUFFICIENT_BALANCE` with `details.kind: "NATIVE_GAS"` and the required, current and missing amounts. A stale wallet nonce returns `409 CONFLICT` first.

## Next steps

* [Wallets and gas](/wallets-and-gas) for building transactions, fees and recovery.
* [Trade lifecycle](/trades) for what happens after funding.