Skip to navigation
API ReferenceTrade Actions

Prepare a trade action

Prepare a trade action.

Credential: Customer session

Before you call

  • A customer session for the same partner, integration, customer, wallet and chain.
  • A funded trade, and a role and status that allow the action.
  • Preparing returns an unsigned transaction. Signing and submitting are separate steps.

Prepares an unsigned transaction for the customer who owns the trade. Sign it with the registered wallet, then submit the signed transaction, or report the included blockchain transactionHash, with its preparationId through POST /v1/transactions. Trade action transactions have expiresAt: null, and the trade must still allow the action when it executes.

A BUY customer can markPaid or cancelPrePaid while the trade is CREATED, and can openDispute while it is PAID, after the trade’s dispute window, counted from paidAt. A SELL customer can release or openDispute while the trade is PAID, and can openDispute while it is CREATED, after the dispute window, counted from createdAt. A SELL has no customer cancel action.

If a dispute is opened too early, the call returns 409 CONFLICT with details.reason: TOO_EARLY and details.availableAt, an ISO time. Other invalid role and state combinations return INVALID_STATE with action and the numeric chainStatus. availableActions is advisory, because preparing checks the current state.

For openDispute, an optional reason is name_does_not_match_payment, payment_not_received or other. Sinbad stores it off chain and shows it in trade.dispute only after the matching dispute is confirmed. Report the signed transaction so Sinbad keeps the reason. Missing or ambiguous evidence can leave it null.

While the trade is DISPUTED, mutualResolveDispute is a single transaction signed by the customer. A SELL customer releases the USDT to the buyer (BUYER_RELEASE, trade RELEASED). A BUY customer refunds the seller who locked it (FULL_REFUND, trade CANCELED). The other side does not sign. CONFIRMED describes the transaction receipt, so read the trade again if its status has not caught up.

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.
503UPSTREAM_ERRORRetry with backoff; preserve the same idempotency key for a repeated mutation.

Authentication

AuthorizationBearer

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

Path parameters

tradeIdstringRequired
actionenumRequired
Allowed values:

Request

This endpoint expects an object.
reasonenumOptional

Optional for openDispute; other actions do not use dispute metadata.

Allowed values:

Response

Unsigned transaction for the customer's wallet to sign.
chainIdinteger
fromstringformat: "^0x[a-fA-F0-9]{40}$"
callobject
escrowIdstring
actionenum
Allowed values:
transactionobject

Errors

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