Skip to navigation
Trading

Trade actions

Once a trade exists, the customer moves it forward with one of five actions. All of them share one route, POST /v1/trades/{tradeId}/actions/{action}/execution, and one flow. Each action also has its own page with its prerequisites and complete examples.

The five actions

ActionWhoWhenResult
markPaidCustomer on a BUYAfter sending the fiat, while the trade is CREATED.The trade becomes PAID.
releaseCustomer on a SELLAfter verifying that the fiat arrived, while the trade is PAID.The USDT goes to the merchant and the trade becomes RELEASED.
cancelPrePaidCustomer on a BUYBefore marking payment as sent.The trade ends CANCELED.
openDisputeCustomerDepends on the side and status. See Disputes.The trade becomes DISPUTED.
mutualResolveDisputeCustomerWhile the trade is DISPUTED.The trade ends RELEASED or CANCELED, depending on the customer’s side.

How every action works

  1. Prepare. Call POST /v1/trades/{tradeId}/actions/{action}/execution with the action name. Sinbad checks the trade’s current escrow state and timing, and returns an unsigned prepared transaction. Preparing does not execute anything.
  2. Sign. Have the customer’s registered wallet sign the prepared transaction.
  3. Submit. Call POST /v1/transactions with the preparationId and an Idempotency-Key.
  4. Confirm. Poll GET /v1/transactions/{preparationId}, then read the trade with GET /v1/trades/{tradeId}.

Preparing takes no Idempotency-Key, and every call returns a new prepared transaction. Actions have no signing deadline, but the trade must still be in the right state when you prepare.

Open a dispute

You can send an optional reason when you prepare openDispute: name_does_not_match_payment, payment_not_received or other. The reason is off-chain metadata. It appears in trade.dispute and in trade.updated only after Sinbad matches it to confirmed escrow evidence. Before that, dispute is null. A reason you never report, or an ambiguous one, can stay null. The details remain on the trade after the dispute is resolved. See Disputes.

Resolve a dispute

The customer signs one transaction for mutualResolveDispute, and the other side does nothing.

  • On a customer SELL, the customer locked the USDT and concedes, so the USDT goes to the buyer and the trade ends RELEASED.
  • On a customer BUY, the customer paid the fiat and concedes, so the USDT goes back to the seller who locked it and the trade ends CANCELED.