Sinbad Partner API

POST /v1/trades/{tradeId}/actions/openDispute/execution
Authorization: Bearer <sessionToken>

Before you call

A customer session for the same partner, integration, customer, wallet and chain.
Customer SELL: PAID, or CREATED after its dispute window.
Customer BUY: PAID after the dispute window measured from paidAt. TOO_EARLY includes availableAt.

The body is optional. Send a reason of name_does_not_match_payment, payment_not_received or other:

{
  "reason": "payment_not_received"
}

Response: unsigned prepared transaction

{
  "chainId": 80002,
  "from": "0x19e7e376e7c213b7e7e7e46cc70a5dd086daff2a",
  "call": {
    "to": "0x3333333333333333333333333333333333333333",
    "data": "0x27d00fb0000000000000000000000000000000000000000000000000000000000000002a",
    "value": "0"
  },
  "escrowId": "42",
  "action": "openDispute",
  "transaction": {
    "preparationId": "preparation_openDispute",
    "purpose": "openDispute",
    "chainId": 80002,
    "from": "0x19e7e376e7c213b7e7e7e46cc70a5dd086daff2a",
    "to": "0x3333333333333333333333333333333333333333",
    "data": "0x27d00fb0000000000000000000000000000000000000000000000000000000000000002a",
    "value": "0",
    "expiresAt": null
  }
}

Errors

409: Action unavailable in the current state

{
  "error": {
    "code": "CONFLICT",
    "numericId": 1004,
    "message": "Action is unavailable for this role or trade state. Refresh the trade.",
    "requestId": "request_demo",
    "details": {
      "action": "openDispute",
      "chainStatus": 3,
      "reason": "INVALID_STATE"
    }
  }
}

409: Dispute window not elapsed

{
  "error": {
    "code": "CONFLICT",
    "numericId": 1004,
    "message": "Dispute is available after 2026-10-23T10:05:00.000Z.",
    "requestId": "request_demo",
    "details": {
      "action": "openDispute",
      "chainStatus": 2,
      "reason": "TOO_EARLY",
      "availableAt": "2026-10-23T10:05:00.000Z"
    }
  }
}

Sign, submit and confirm

Prepare the call shown above. Preparing does not execute the action.
Ask the customer’s registered wallet to sign transaction, keeping its chain, sender, destination, data and value unchanged.
Submit the signed transaction or its hash with the same preparationId and an Idempotency-Key.
Poll the transaction status, then read the trade. The transaction can be confirmed before the trade shows the new status.

Trade actions have no signing deadline (expiresAt is null), but Sinbad checks the trade’s current escrow state and timing when you prepare. If a send is pending or its outcome is unknown, keep tracking it and do not sign another transaction.

The shared route and schema are in the API reference.