Skip to navigation
Trading

Sign and track transactions

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 has the signing, fee and retry details.

The four steps

StepWhat you doCall
1. PrepareIf 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
2. SignHave 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}, POST /v1/trades/{tradeId}/actions/{action}/execution
3. SubmitSend the preparationId with either signedTransaction (Sinbad sends it) or transactionHash (your wallet already sent it).POST /v1/transactions
4. TrackPoll until the transaction and then the trade are confirmed, or use webhooks.GET /v1/transactions/{preparationId}, GET /v1/trades/{tradeId}

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