Skip to navigation
API ReferenceTrades

Get trade details

Get trade details.

Credential: Customer session or partner secret

Before you call

  • A customer session, or an owning partner server credential without Origin.

Reads one trade that the caller owns. A trade exists only after its escrow funding is confirmed on chain, and its first status is CREATED. Before that, track the breakdown, and do not wait for a PENDING trade. Funding confirmation and trade updates can reach the API later than the chain, so poll the existing trade instead of repeating an action.

On a funded trade in CREATED, PAID or DISPUTED, paymentInstructions holds a fixed snapshot of the fiat recipient: the merchant’s account on a BUY, and the customer’s receiving account on a SELL. It is null before funding and after settlement. Trade history and webhook payloads omit account data, and displayLabel identifies the receiving account.

availableActions lists candidate actions for the caller’s role and the trade’s status. Preparing an action checks the current chain state and the dispute timing. RELEASED and CANCELED are final. Dispute details stay on the trade after the dispute is resolved. reason is null when Sinbad has no unambiguous, verified reason.

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.

OR
AuthorizationBearer

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

Path parameters

tradeIdstringRequired

Response

Partner trade state.
tradeIdstring
tradeRefstring
statusenum

A funded trade first appears as CREATED. PENDING, FUNDING_FAILED and FUNDING_EXPIRED are reserved compatibility values, not currently emitted.

sideenum
Allowed values:
chainIdinteger
escrowAddressstring
tokenAddressstring
walletAddressstring
pricingobject
idstringOptional
sourceenumOptional
Allowed values:
transferNumberstring or nullOptional
counterpartyobject or nullOptional
availableActionslist of stringsOptional
escrowIdstring or nullOptional
merchantobjectOptional
fiatCurrencyIdstringOptional
paymentMethodIdstringOptional
displayLabelstring or nullOptional

Recipient account label from the funded payment snapshot; null before funding or when unavailable. Retained after settlement.

transactionHashstring or nullOptional
disputeobjectOptional

Confirmed dispute only; null before opening and retained after resolution. Roles are public; no internal identity IDs are exposed.

proofOfPaymentobject or map from strings to anyOptional
paymentInstructionsobject or nullOptional

Selected fiat recipient account in CREATED, PAID, and DISPUTED after confirmed funding. BUY uses the merchant account; SELL uses the customer’s receiving account. Null before funding and after settlement.

senderDetailsobject or nullOptional

Customer view of a SELL trade only. The merchant’s saved payment method the fiat is sent from, snapshotted at checkout, so the customer can verify the incoming payment. Same shape as paymentInstructions; data keys match the saved method. Present only in CREATED, PAID, and DISPUTED after confirmed funding; otherwise null (always null for BUY, merchant views, and trades funded before this field existed).

typestringOptional
createdAtdatetime or nullOptional
fundedAtdatetime or nullOptional
updatedAtdatetime or nullOptional
settlementOutcomestring or nullOptional
tradeDetailsmap from strings to objects or nullOptional
merchantRateDetailsmap from strings to objects or nullOptional
webhookSequenceintegerOptional>=0

Returned on partner-server reads only.

Errors

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