Coinbax API

Transactions

Payment operations and lifecycle management

View as Markdown

List transactions with filters

GET/api/v2/transactionsOAuth 2.0 client credentials

Query parameters

  • pagenumber

    Page number

  • limitnumber

    Items per page

  • statusenum

    Filter by status

    "pending" · "risk_review" · "pending_user_action" · "escrowed" · "in_review" · "disputed" · "completed" · "refunded" · "failed" · "rescinded"
  • fromAddressstring

    Filter by sender blockchain address

  • toAddressstring

    Filter by receiver blockchain address

  • dateFromstring

    Filter by date from (ISO 8601)

  • dateTostring

    Filter by date to (ISO 8601)

  • customerIdstring

    Filter by customer ID

  • walletAddressstring

    Filter by wallet address (matches fromAddress OR toAddress)

  • directionenum

    Filter by direction of money movement relative to the customer wallet. Rows that could not be classified are excluded from every direction.

    "deposit" · "withdrawal" · "internal" · "receive"

Responses

200List of transactions

Response follows the unified success / data / meta / error envelope.

# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/transactions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions', {
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Create a new transaction

POST/api/v2/transactionsOAuth 2.0 client credentials

Request body

  • fromAddressstringrequired

    Sender blockchain address, in the format the `blockchainNetwork` uses: `0x` + 40 hex characters on an EVM chain, a base58-encoded 32-byte public key on Solana. Omitting `blockchainNetwork` defaults to Base, so the EVM format applies.

  • toAddressstringrequired

    Receiver blockchain address, in the format the `blockchainNetwork` uses — see `fromAddress`.

  • amountnumberrequired

    Transaction amount (minimum 0.01, maximum 1,000,000)

  • currencyenum"USDC" · "USDT" · "ETH" · "MockUSDC" · "USDG"

    Currency type

  • blockchainNetworkenum"ethereum" · "base" · "solana" · "optimism" · "arbitrum" · "base-sepolia" · "ethereum-sepolia" · "optimism-sepolia" · "arbitrum-sepolia" · "solana-devnet" · "solana-testnet"

    Blockchain network. Defaults to the environment's Base network when omitted ('base' on production, 'base-sepolia' on local/staging). Mainnet names sent to local/staging are coerced to their testnet counterpart (e.g. base → base-sepolia); testnet names sent to production are rejected with TESTNET_NOT_ALLOWED_IN_PRODUCTION.

  • orchestrationTypeenum"raw" · "coinbax"

    Orchestration type: raw (direct blockchain) or coinbax (smart contract escrow)

  • templateIdstring (uuid)

    Template ID from coinbax-library. The template will be fetched from the library service.

  • contractTemplateIdstring (uuid)

    Contract template ID (alias for templateId, for backward compatibility)

  • templateobject

    Complete template data embedded in request (optional, prefer using templateId instead)

    • TemplateDto
      • templateIdstringrequired

        Template ID from coinbax-library

      • templateNamestringrequired

        Template name

      • templateVersionstringrequired

        Template version

      • controlsarray of TemplateControlDtorequired

        Array of controls to execute

        array of TemplateControlDto
        • idstringrequired

          Control ID

        • typestringrequired

          Control type (e.g., TimeDelay, TwoFactorAuth, ComplianceCheck)

        • namestringrequired

          Control name

        • executionPhasestringrequired

          Execution phase (PRE_ESCROW, POST_ESCROW, POST_RELEASE)

        • executionOrdernumberrequired

          Execution order within the phase

        • configobjectrequired

          Control configuration

          object

          Control configuration

        • isRequiredboolean

          Whether this control is required for the transaction

        • isActiveboolean

          Whether this control is active

  • metadataobject

    Additional metadata about the transaction

    object

    Additional metadata about the transaction

  • billingConfigobject

    Billing configuration from workspace (passed by coinbax-core)

    • BillingConfigDto
      • feeTypeenumrequired"percentage" · "fixed" · "tiered"

        Type of fee calculation

      • feePercentagenumber

        Fee percentage in basis points (100 = 1%). Required for percentage type.

      • fixedFeeAmountnumber

        Fixed fee amount in smallest currency unit. Required for fixed type.

      • tieredFeesarray of TieredFeeDto

        Array of tiered fee configurations. Required for tiered type.

        array of TieredFeeDto
        • minAmountnumberrequired

          Minimum transaction amount for this tier

        • maxAmountnumberrequired

          Maximum transaction amount for this tier

        • feePercentagenumberrequired

          Fee percentage in basis points (100 = 1%)

      • feeWalletAddressstringrequired

        Coinbax fee collection wallet address

      • currencystringrequired

        Currency for fee collection

      • isActivebooleanrequired

        Whether billing is active for this workspace

  • quoteIdstring (uuid)

    FeeQuote id from a prior /transactions/quote call. Required when the workspace has BILLING_ENABLED=true (Phase 1 cutover).

  • signerTypestring

    Which wallet signs this transaction. Omit it and Coinbax signs with a wallet it operates on your behalf. Send `external_wallet` when the sender signs with their own wallet, which is also the mode SafeSend and other consumer flows use. Gas-sponsored variants exist for senders who hold their own keys but should not pay gas; contact support before using them.

  • customerIdstring

    Customer ID for external wallet transactions (Transmitter users)

  • idempotencyKeystring

    Idempotency key to prevent duplicate transaction creation. If provided, a transaction with the same key will return the existing transaction instead of creating a new one.

Responses

201Transaction created successfully
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Invalid request. `CONTRACT_NOT_DEPLOYED`: a COINBAX transaction on an EVM network whose workspace has no escrow contract deployed there
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
409Duplicate transaction detected within time window
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422quoteId is expired, already consumed, missing a fee recipient, or was not priced for this transaction (amount, asset, network or workspace)
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
429Transaction rate limit exceeded (max 10/minute per sender)
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fromAddress": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "toAddress": "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
  "amount": 100.5,
  "currency": "USDC",
  "blockchainNetwork": "base",
  "orchestrationType": "raw",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "contractTemplateId": "550e8400-e29b-41d4-a716-446655440000",
  "template": {
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "templateName": "2FA Escrow",
    "templateVersion": "1.0.0",
    "controls": [
      {
        "id": "control-123",
        "type": "TwoFactorAuth",
        "name": "Two-Factor Authentication",
        "executionPhase": "PRE_ESCROW",
        "executionOrder": 1,
        "config": {
          "method": "sms",
          "phoneNumber": "+1234567890"
        }
      }
    ]
  },
  "metadata": {
    "orderId": "order_789",
    "productName": "Premium Widget"
  },
  "billingConfig": {
    "feeType": "percentage",
    "feePercentage": 30,
    "feeWalletAddress": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
    "currency": "USDC",
    "isActive": true
  },
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "signerType": "external_wallet",
  "customerId": "cust_abc123",
  "idempotencyKey": "tx_unique_key_12345"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "fromAddress": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
    "toAddress": "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
    "amount": 100.5,
    "currency": "USDC",
    "blockchainNetwork": "base",
    "orchestrationType": "raw",
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "contractTemplateId": "550e8400-e29b-41d4-a716-446655440000",
    "template": {
      "templateId": "550e8400-e29b-41d4-a716-446655440000",
      "templateName": "2FA Escrow",
      "templateVersion": "1.0.0",
      "controls": [
        {
          "id": "control-123",
          "type": "TwoFactorAuth",
          "name": "Two-Factor Authentication",
          "executionPhase": "PRE_ESCROW",
          "executionOrder": 1,
          "config": {
            "method": "sms",
            "phoneNumber": "+1234567890"
          }
        }
      ]
    },
    "metadata": {
      "orderId": "order_789",
      "productName": "Premium Widget"
    },
    "billingConfig": {
      "feeType": "percentage",
      "feePercentage": 30,
      "feeWalletAddress": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
      "currency": "USDC",
      "isActive": true
    },
    "quoteId": "550e8400-e29b-41d4-a716-446655440000",
    "signerType": "external_wallet",
    "customerId": "cust_abc123",
    "idempotencyKey": "tx_unique_key_12345"
  }),
});
const result = await response.json();

List transaction batches

GET/api/v2/transactions/batchesOAuth 2.0 client credentials

Query parameters

  • pagenumber

    Page number

  • limitnumber

    Items per page

  • statusenum

    Filter by batch status

    "pending_user_action" · "submitted" · "completed" · "failed"
  • fromAddressstring

    Filter by sender blockchain address

  • dateFromstring

    Filter by date from (ISO 8601)

  • dateTostring

    Filter by date to (ISO 8601)

  • customerIdstring

    Filter by customer ID

Responses

200Paginated batches

Response follows the unified success / data / meta / error envelope.

# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/transactions/batches' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches', {
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Create a multi-recipient transaction batch

POST/api/v2/transactions/batchesOAuth 2.0 client credentials

v1 called this `batch`; v2 uses the plural collection name.

Request body

  • fromAddressstringrequired

    Sender blockchain address (one signer for the whole batch). Validated against `blockchainNetwork`: 0x-hex on EVM, base58 on Solana.

  • legsarray of CreateBatchLegDtorequired

    Per-recipient legs (1..MAX_BATCH_LEGS).

    array of CreateBatchLegDto
    • toAddressstringrequired

      Receiver blockchain address for this leg. Validated against the batch's `blockchainNetwork`: a 0x-hex address on EVM networks, a base58 address on Solana networks.

    • amountnumberrequired

      Per-leg amount (minimum 0.01, maximum 1,000,000).

    • metadataobject

      Per-leg metadata (e.g., recipient name from the address book). Distinct from batch-level metadata.

      object

      Per-leg metadata (e.g., recipient name from the address book). Distinct from batch-level metadata.

  • currencyenum"USDC" · "USDT" · "ETH" · "MockUSDC" · "USDG"

    Currency type — shared by every leg in the batch.

  • blockchainNetworkstring

    Blockchain network. The set of accepted values mirrors `CreateTransactionDto.blockchainNetwork`, including the env-aware default ('base' on production, 'base-sepolia' on local/staging), non-prod coercion of mainnet names, and production rejection of testnet names.

  • orchestrationTypeenum"raw" · "coinbax"

    Orchestration type for every leg.

  • signerTypestring

    Which wallet signs this transaction. Omit it and Coinbax signs with a wallet it operates on your behalf. Send `external_wallet` when the sender signs with their own wallet, which is also the mode SafeSend and other consumer flows use. Gas-sponsored variants exist for senders who hold their own keys but should not pay gas; contact support before using them. Batches currently require the sender's own wallet.

  • templateIdstring (uuid)

    Template ID from coinbax-library. Stored on the batch in B1; control execution against the template is wired in B2.

  • customerIdstring

    Customer ID for external-wallet flows (Transmitter, SafeSend).

  • idempotencyKeystring

    Idempotency key — if provided, an existing batch with the same key is returned instead of creating a new one.

  • metadataobject

    Batch-level metadata (distinct from per-leg metadata).

    object

    Batch-level metadata (distinct from per-leg metadata).

  • templateobject

    Embedded template (alternative to `templateId`, deprecated for consistency with `CreateTransactionDto`).

    • TemplateDto
      • templateIdstringrequired

        Template ID from coinbax-library

      • templateNamestringrequired

        Template name

      • templateVersionstringrequired

        Template version

      • controlsarray of TemplateControlDtorequired

        Array of controls to execute

        array of TemplateControlDto
        • idstringrequired

          Control ID

        • typestringrequired

          Control type (e.g., TimeDelay, TwoFactorAuth, ComplianceCheck)

        • namestringrequired

          Control name

        • executionPhasestringrequired

          Execution phase (PRE_ESCROW, POST_ESCROW, POST_RELEASE)

        • executionOrdernumberrequired

          Execution order within the phase

        • configobjectrequired

          Control configuration

          object

          Control configuration

        • isRequiredboolean

          Whether this control is required for the transaction

        • isActiveboolean

          Whether this control is active

Responses

201
object
{}
400Invalid batch request
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/batches' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fromAddress": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "legs": [
    {
      "toAddress": "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
      "amount": 100.5,
      "metadata": {
        "recipientLabel": "Alice",
        "orderId": "order_789"
      }
    }
  ],
  "currency": "USDC",
  "blockchainNetwork": "base",
  "orchestrationType": "raw",
  "signerType": "external_wallet",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "cust_abc123",
  "idempotencyKey": "batch_unique_key_12345",
  "metadata": {
    "source": "safesend",
    "uiVersion": "1.2.3"
  },
  "template": {
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "templateName": "2FA Escrow",
    "templateVersion": "1.0.0",
    "controls": [
      {
        "id": "control-123",
        "type": "TimeDelay",
        "name": "Payment Hold Period",
        "executionPhase": "PRE_ESCROW",
        "executionOrder": 1,
        "config": {
          "delayMinutes": 5
        },
        "isRequired": true,
        "isActive": true
      }
    ]
  }
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "fromAddress": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
    "legs": [
      {
        "toAddress": "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
        "amount": 100.5,
        "metadata": {
          "recipientLabel": "Alice",
          "orderId": "order_789"
        }
      }
    ],
    "currency": "USDC",
    "blockchainNetwork": "base",
    "orchestrationType": "raw",
    "signerType": "external_wallet",
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "cust_abc123",
    "idempotencyKey": "batch_unique_key_12345",
    "metadata": {
      "source": "safesend",
      "uiVersion": "1.2.3"
    },
    "template": {
      "templateId": "550e8400-e29b-41d4-a716-446655440000",
      "templateName": "2FA Escrow",
      "templateVersion": "1.0.0",
      "controls": [
        {
          "id": "control-123",
          "type": "TimeDelay",
          "name": "Payment Hold Period",
          "executionPhase": "PRE_ESCROW",
          "executionOrder": 1,
          "config": {
            "delayMinutes": 5
          },
          "isRequired": true,
          "isActive": true
        }
      ]
    }
  }),
});
const result = await response.json();

Get a transaction batch by ID

GET/api/v2/transactions/batches/{id}OAuth 2.0 client credentials

Path parameters

  • idstringrequired

Responses

200
object
{}
404Batch not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/transactions/batches/<id>' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches/<id>', {
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Cancel an unsubmitted batch

POST/api/v2/transactions/batches/{id}/cancelOAuth 2.0 client credentials

Requires `reverse:transactions` in v2. v1 required `write:transactions`, which let a create-only integration cancel a batch — the asymmetry v2 fixes.

Path parameters

  • idstringrequired

Request body

  • reasonstring

    Human-readable reason recorded on the batch metadata. Surfaces in audit logs and the cancel webhook payload. Truncated at 500 chars.

Responses

200
object
{}
400Batch cannot be cancelled
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Batch not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "reverse:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Sender closed the tab before signing batchCreateEscrow"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "Sender closed the tab before signing batchCreateEscrow"
  }),
});
const result = await response.json();

Record the on-chain batchCreateEscrow transaction hash

POST/api/v2/transactions/batches/{id}/escrow-hashOAuth 2.0 client credentials

v1 called this `batch/:id/submit-escrow-hash`.

Path parameters

  • idstringrequired

Request body

  • transactionHashstringrequired

    On-chain transaction hash for the `batchCreateEscrow` call. Shared by every leg in the batch (one signature, one tx).

Responses

200
object
{}
400Invalid batch state or hash
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Batch not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/escrow-hash' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/escrow-hash', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }),
});
const result = await response.json();

Build the escrow transactions for a Solana payout batch

POST/api/v2/transactions/batches/{id}/escrow-transactionsOAuth 2.0 client credentials

For a Solana batch created with signerType `external_wallet` and orchestrationType `coinbax`, returns one `initialize_escrow` transaction per leg for the sender to sign in a single `signAllTransactions` approval. Coinbax pays each escrow fee and rent and co-signs as attestor; the USDC comes from the sender's token account. Nothing is submitted. A leg already on chain is reported in `alreadyFunded` and omitted, so a re-build after partial funding returns only the legs still needing a signature. The sender signs the returned transactions with their wallet before each leg's `lastValidBlockHeight`; submitting the signed set lands them on chain. A blockhash lives about 60 seconds, so a large batch is better signed in chunks: pass `legIndices` to build one chunk, sign it, submit it, then build the next.

Path parameters

  • idstringrequired

Request body

  • legIndicesarray of number

    Build only these legs (0-based `legIndex`, as at create). A client that has a large batch signed in several wallet approvals asks for one chunk at a time, so each chunk is built just before it is signed and lands within its blockhash lifetime. A requested leg already on chain is reported in `alreadyFunded`, not built. Omit to build every leg still awaiting a signature.

    array of number
    number

Responses

200
  • batchIdstring (uuid)required

    The batch id.

  • legsarray of PayoutBatchLegTransactionDtorequired

    Legs awaiting a sender signature, ordered by `legIndex`.

    array of PayoutBatchLegTransactionDto
    • transactionstringrequired

      The escrow-creating Solana transaction, base64-encoded. Coinbax has signed it as the fee and rent sponsor and as the attestor; the sender signs it with their own wallet (the wallet's signTransaction, not signAndSendTransaction) and posts it to the submit endpoint.

    • escrowAddressstringrequired

      The escrow account (a program-derived address) it creates.

    • lastValidBlockHeightnumberrequired

      The last block height at which the transaction can land. Past it, build a new one.

    • legIndexnumberrequired

      The leg index within the batch (0-based), matching the order of `legs[]` at create.

    • transactionIdstring (uuid)required

      The leg's transaction id, for matching the leg to its transaction. The submit step identifies legs by `legIndex`, not by this id.

  • alreadyFundedarray of numberrequired

    Leg indices whose escrow is already on chain; these need no signature. Covers every leg of the batch, including legs outside a requested `legIndices`.

    array of number
    number
{
  "batchId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "legs": [
    {
      "transaction": "string",
      "escrowAddress": "string",
      "lastValidBlockHeight": 100.5,
      "legIndex": 100.5,
      "transactionId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
    }
  ],
  "alreadyFunded": [
    100.5
  ]
}
400Not a Solana external-wallet batch, not in PENDING_USER_ACTION, or a `legIndices` entry that is not a leg of the batch
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Batch not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
409`PRE_ESCROW_PENDING`: a batch control is still pending
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/escrow-transactions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "legIndices": [
    100.5
  ]
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/escrow-transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "legIndices": [
      100.5
    ]
  }),
});
const result = await response.json();

Submit the signed escrow transactions for a Solana payout batch

POST/api/v2/transactions/batches/{id}/escrow-transactions/submitOAuth 2.0 client credentials

Accepts the set built by `batches/{id}/escrow-transactions`, each signed by the sender. Submits each leg independently: a leg that confirms becomes `escrowed`; a leg that fails is reported in `legs[].error`, not thrown. Recovery depends on the error code: `BLOCKHASH_EXPIRED` means rebuild and sign that leg again; `ESCROW_SUBMISSION_IN_PROGRESS` means another request owns the submit, so check the recorded transaction instead of resubmitting; `ESCROW_NOT_YET_VISIBLE` means the escrow is still settling, so retry after a short delay. Submitting a leg already on chain returns it `escrowed`. The batch rolls up to COMPLETED on its own once every leg releases.

Path parameters

  • idstringrequired

Request body

  • legsarray of SubmitPayoutBatchLegDtorequired

    The signed escrow transactions, one per leg being funded.

    array of SubmitPayoutBatchLegDto
    • legIndexnumberrequired

      The leg index this signed transaction funds, from the build response.

    • signedTransactionstringrequired

      The leg's escrow transaction from the build step, signed by the sender's wallet, base64-encoded.

Responses

200
  • batchIdstring (uuid)required
  • escrowedCountnumberrequired

    Legs now escrowed on chain.

  • failedCountnumberrequired

    Legs that failed. Each failed leg's `error.code` says how to recover.

  • legsarray of PayoutBatchLegResultDtorequired
    array of PayoutBatchLegResultDto
    • legIndexnumberrequired
    • statusenumrequired"escrowed" · "failed"

      `escrowed` once the escrow confirms on chain; `failed` otherwise. A failed leg's `error.code` says whether to rebuild it, retry it later, or check its recorded transaction.

    • escrowAddressstring

      The escrow account, when the leg escrowed.

    • transactionHashstring

      The on-chain signature, when the leg escrowed.

    • errorobject

      Present when the leg failed.

      • PayoutBatchLegErrorDto
        • codestringrequired

          Coded reason, e.g. BLOCKHASH_EXPIRED. The submit endpoint describes how to recover from each code.

        • messagestringrequired

          Human-readable detail.

{
  "batchId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "escrowedCount": 100.5,
  "failedCount": 100.5,
  "legs": [
    {
      "legIndex": 100.5,
      "status": "escrowed",
      "escrowAddress": "string",
      "transactionHash": "string",
      "error": {
        "code": "string",
        "message": "string"
      }
    }
  ]
}
400Not a Solana external-wallet batch, not in PENDING_USER_ACTION, or an unknown legIndex
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Batch not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
409`PRE_ESCROW_PENDING`: a batch control is still pending
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/escrow-transactions/submit' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "legs": [
    {
      "legIndex": 100.5,
      "signedTransaction": "string"
    }
  ]
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/escrow-transactions/submit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "legs": [
      {
        "legIndex": 100.5,
        "signedTransaction": "string"
      }
    ]
  }),
});
const result = await response.json();

Verify a 2FA / SMS code for a pending batch control

POST/api/v2/transactions/batches/{id}/verify-2faOAuth 2.0 client credentials

Accepts the verification code the sender received for a batch-level PRE_ESCROW control (TwilioSMS / TwoFactorAuth). The code settles the pending control and the remaining PRE_ESCROW controls resume: the batch clears `awaitingControlVerification` once all resolve, stays awaiting if another verification is next, or fails if a later control rejects it.

Path parameters

  • idstringrequired

Request body

  • codestringrequired

    6-digit verification code sent via SMS

Responses

200
object
{}
400Batch not awaiting verification, no pending control, or an invalid / expired code
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Batch not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422A PRE_ESCROW control ordered after the code rejected the batch
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/verify-2fa' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/batches/<id>/verify-2fa', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "code": "123456"
  }),
});
const result = await response.json();

Create a fee quote for a pending transaction

POST/api/v2/transactions/quoteOAuth 2.0 client credentials

Returns a 120-second-TTL quote with platform fee, workspace fee, gas pass-through (if applicable), and total charged. Pass the returned `quoteId` to `POST /transactions` to lock the rate.

Request body

  • amountUsdstringrequired

    USD principal amount

  • assetstringrequired
  • networkstringrequired

    Canonical network identifier

Responses

200Quote created successfully
  • quoteIdstring (uuid)required
  • expiresAtstring (date-time)required
  • amountUsdstringrequired
  • platformFeeUsdstringrequired
  • workspaceFeeUsdobjectrequired
    object
  • gasPassThroughUsdobjectrequired
    object
  • totalOnTopUsdstringrequired
  • totalChargedUsdstringrequired
  • gasCapExceededbooleanrequired
{
  "quoteId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "expiresAt": "2026-01-15T12:00:00.000Z",
  "amountUsd": "1000.00",
  "platformFeeUsd": "2.500000",
  "workspaceFeeUsd": "5.000000",
  "gasPassThroughUsd": null,
  "totalOnTopUsd": "7.500000",
  "totalChargedUsd": "1007.500000",
  "gasCapExceeded": false
}
404Workspace has no ACTIVE PricingPlan / WorkspaceFeeSchedule. Operator intervention required.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422Gas-cap exceeded and PricingPlan.onGasCapBreach=BLOCK. The caller can retry later if gas drops.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
503Transient: gas oracle / FX / coinbax-core unreachable. Retry.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/quote' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amountUsd": "1000.00",
  "asset": "USDC",
  "network": "base"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/quote', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amountUsd": "1000.00",
    "asset": "USDC",
    "network": "base"
  }),
});
const result = await response.json();

Get transaction statistics

GET/api/v2/transactions/statsOAuth 2.0 client credentials

Optional dateFrom/dateTo scope the byStatus aggregate. The windows block (24h/7d/30d) is always computed over its own fixed spans.

Query parameters

  • dateFromstring

    Scope stats to transactions created at or after this time (ISO 8601)

  • dateTostring

    Scope stats to transactions created at or before this time (ISO 8601)

  • directionenum

    Scope stats to one direction of money movement. Applies to both the byStatus aggregate and the fixed 24h/7d/30d windows.

    "deposit" · "withdrawal" · "internal" · "receive"

Responses

200Transaction statistics

Response follows the unified success / data / meta / error envelope.

# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/transactions/stats' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/stats', {
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Get sanitized template + controls config for a template ID

GET/api/v2/transactions/template-configOAuth 2.0 client credentials

Returns public-safe summaries of each active control on a template. Use it to render pre-confirmation screens (for example, "what protects this payment") and to enforce client-side AmountLimit min/max. Sanitized: only a hand-picked subset of each control config is returned — policy/implementation fields are NOT exposed.

Query parameters

  • templateIdstringrequired

Responses

200Template config retrieved
  • templateIdstringrequired

    Template UUID.

  • templateNamestringrequired

    Template name (e.g. "Transmitter P2P").

  • templateVersionstringrequired

    Template version string from the library (e.g. "1.0.0").

  • controlsarray of TemplateControlSummaryrequired

    Active controls on the template, sanitized to a small set of public-safe fields per type. See TemplateControlSummary.

    array of TemplateControlSummary
    • typestringrequired

      Control type.

    • phasestringrequired

      Execution phase: PRE_ESCROW, POST_ESCROW, PRE_RELEASE, or POST_RELEASE.

    • namestringrequired

      Human-readable control name (from the template, e.g. "Sanctions Screening").

    • isRequiredbooleanrequired

      Whether this control is required (vs. optional — driven by `metadata.optional` on the template control).

    • minAmountnumber

      AmountLimit: minimum allowed amount per send (inclusive).

    • maxAmountnumber

      AmountLimit: maximum allowed amount per send (inclusive).

    • currencystring

      AmountLimit: currency the limits are denominated in (e.g. "USD", "USDC").

    • delayAmountnumber

      TimeDelay: hold-period duration amount.

    • delayUnitenum"seconds" · "minutes" · "hours" · "days"

      TimeDelay: unit for `delayAmount`.

    • allowSenderRescindboolean

      TimeDelay: whether the sender can rescind/cancel during the hold window.

    • userConfigurableboolean

      TimeDelay: whether the user can pick a delay value per transaction (vs. always the template default). When true, the frontend should render `options` as selectable presets. When false or absent, the frontend renders the template default as a read-only display.

    • optionsarray of string

      TimeDelay: allowed preset values (when `userConfigurable` is true) using compact duration notation: `Nm` minutes, `Nh` hours, `Nd` days. Frontend parses and renders these as picker chips. Empty / absent means no template-defined presets — frontend may fall back to its own defaults.

      array of string
      string
    • checksSenderboolean

      OfacSanctions: whether the sender wallet is screened.

    • checksRecipientboolean

      OfacSanctions: whether the recipient wallet is screened.

    • verificationRequiredboolean

      TwilioSMS: whether the SMS-verification step is mandatory (vs. lookup-only).

{
  "templateId": "a1b2c3d4-e5f6-4a5b-8c9d-1234567890ab",
  "templateName": "Transmitter P2P",
  "templateVersion": "1.0.0",
  "controls": [
    {
      "type": "AmountLimit",
      "phase": "PRE_ESCROW",
      "name": "Amount Limit Check",
      "isRequired": true,
      "minAmount": 1,
      "maxAmount": 1000000,
      "currency": "USD",
      "delayAmount": 24,
      "delayUnit": "hours",
      "allowSenderRescind": true,
      "userConfigurable": true,
      "options": [
        "5m",
        "30m",
        "24h",
        "48h",
        "7d"
      ],
      "checksSender": true,
      "checksRecipient": true,
      "verificationRequired": true
    }
  ]
}
404Template not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/transactions/template-config?templateId=<templateId>' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/template-config?templateId=<templateId>', {
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Get transaction by ID

GET/api/v2/transactions/{id}OAuth 2.0 client credentials

Path parameters

  • idstringrequired

Responses

200Transaction details
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/transactions/<id>' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>', {
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Cancel pre-escrow transaction the user never signed for

POST/api/v2/transactions/{id}/cancelOAuth 2.0 client credentials

Marks a transaction in PENDING_USER_ACTION as FAILED with userCancelled=true. No on-chain action — funds were never escrowed. Use this when the user rejects the wallet popup and does not intend to retry; rejects with 400 if the transaction has already advanced to ESCROWED (use /refund or /rescind instead) or is already terminal. Requires `reverse:transactions` in v2.

Path parameters

  • idstringrequired

Request body

  • reasonstring

    Optional human-readable reason for the cancellation. Surfaced in the transaction.failed webhook and stored on `metadata.cancelReason`.

Responses

200Transaction cancelled successfully
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Transaction not in PENDING_USER_ACTION, or already has an on-chain escrow address
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
403Token lacks `reverse:transactions`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "reverse:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "User dismissed pending tx from SafeSend Active tab"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "User dismissed pending tx from SafeSend Active tab"
  }),
});
const result = await response.json();

List control execution results for a transaction

GET/api/v2/transactions/{id}/controlsOAuth 2.0 client credentials

One entry per control the engine ran, in run order, with its phase, outcome, timing and — on a failure — a diagnostic message. Reads the same records as the transaction itself, so the same `read:transactions` scope applies. Results appear as the engine reaches each control, so a transaction still in flight returns the controls resolved so far alongside `pending` entries; an empty list means the template configures no controls. Control **output** is not included. An executor returns whatever it found useful — a balance check returns the account number and balance it read — so there is no sanitised pass-through to publish. Per-control output can be added as a typed field if an integration needs one.

Path parameters

  • idstringrequired

Responses

200Control execution results
  • transactionIdstring (uuid)required

    The transaction these results belong to. Echoed so a stored or forwarded response stays self-describing.

  • controlsarray of TransactionControlDtorequired

    One entry per control execution, in the order the engine runs them (by phase, then by configured execution order). Empty when the transaction's template configures no controls — which is a valid configuration, not an error.

    array of TransactionControlDto
    • controlIdstring (uuid)required

      The control this row executed, as catalogued in the control library. Stable across runs, so it joins against the template configuration returned by `GET /api/v2/transactions/template-config`.

    • controlTypestringrequired

      Which control ran. Deliberately a STRING and not a closed enum: the catalogue grows (and names institution-specific rails), so freezing the list would turn every new control into a breaking spec change, and publishing it in full would advertise integrations a given caller will never see. Treat an unrecognised value as a control you do not model yet, not as an error. Examples: `TimeDelay`, `AmountLimit`, `OfacSanctions`, `TwilioSMS`, `ReceiveAddressAllowlist`.

    • namestring

      The control's display name, as configured in the transaction's template at the time the transaction snapshotted it. Absent when the template gave the control no name. Show this to people; branch on `controlType`.

    • phaseobjectrequired

      Where in the transaction lifecycle this control ran. A control configured in more than one phase produces one row per phase.

      • ControlPhase
        enum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

        Where in the transaction lifecycle this control ran. A control configured in more than one phase produces one row per phase.

    • statusobjectrequired

      Outcome. Branch on this, not on `error` or on the absence of a field.

      • TransactionControlStatus
        enum"success" · "failed" · "pending"

        Outcome. Branch on this, not on `error` or on the absence of a field.

    • executedAtstring (date-time)

      When the control finished, or when it started if it is still pending. Absent on a control the engine has not reached yet.

    • durationMsnumber

      Wall-clock execution time in milliseconds. Absent unless the control both started and finished — a `pending` control has no duration yet, and the elapsed time of an open hold is not an execution time.

    • errorstring

      Why the control rejected the transaction. Present only with `status: failed`. **Diagnostic text, not a machine-readable code.** The wording is not part of the contract and will change. Branch on `status` and on `controlType`; show this to a human.

{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "controls": [
    {
      "controlId": "9f1d4c0e-6b2a-4f73-9a51-2c7e8d0b4a16",
      "controlType": "TimeDelay",
      "name": "Deposit to Member Account",
      "phase": "PRE_ESCROW",
      "status": {},
      "executedAt": "2026-10-06T14:22:08.411Z",
      "durationMs": 125,
      "error": "Amount 500 USDC is below the configured minimum."
    }
  ]
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "read:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl 'https://api-staging.coinbax.com/api/v2/transactions/<id>/controls' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/controls', {
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Record the on-chain escrow-creation transaction hash

POST/api/v2/transactions/{id}/escrow-hashOAuth 2.0 client credentials

v1 called this `submit-escrow-hash`. Note coinbax-core proxies the v1 spelling and republishes it on the Workspace API, deliberately keeping that name rather than dragging a live consumer through a rename — so one operation has two spellings across the two surfaces.

Path parameters

  • idstringrequired

Request body

  • transactionHashstringrequired

    Blockchain transaction hash from user wallet escrow deposit

  • escrowIdstring

    Escrow ID returned by the smart contract (optional - will be detected from blockchain events if not provided)

Responses

200
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Invalid transaction state
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/escrow-hash' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "escrowId": "0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/escrow-hash', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "escrowId": "0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef"
  }),
});
const result = await response.json();

Build the escrow transaction for the sender to sign (Solana)

POST/api/v2/transactions/{id}/escrow-transactionOAuth 2.0 client credentials

For a Solana transaction created with signerType `external_wallet`, returns the `initialize_escrow` transaction for the sender to sign with their own wallet. Coinbax pays the network fee and the escrow rent and co-signs as attestor; the USDC comes from the sender's token account. Nothing is submitted. Sign it and post it to `/transactions/{id}/escrow-transaction/submit` before `lastValidBlockHeight`.

Path parameters

  • idstringrequired

Responses

200
  • transactionstringrequired

    The escrow-creating Solana transaction, base64-encoded. Coinbax has signed it as the fee and rent sponsor and as the attestor; the sender signs it with their own wallet (the wallet's signTransaction, not signAndSendTransaction) and posts it to the submit endpoint.

  • escrowAddressstringrequired

    The escrow account (a program-derived address) it creates.

  • lastValidBlockHeightnumberrequired

    The last block height at which the transaction can land. Past it, build a new one.

{
  "transaction": "string",
  "escrowAddress": "string",
  "lastValidBlockHeight": 100.5
}
400Not a sender-signed Solana transaction, or not awaiting the sender
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
409`PRE_ESCROW_PENDING`; `ESCROW_ALREADY_CREATED` when an earlier submit confirmed but was not recorded (it is recorded now: read the transaction); or `ESCROW_TERMS_MISMATCH`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422`INSUFFICIENT_FUNDS` or `TEMPLATE_NOT_SUPPORTED`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/escrow-transaction' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/escrow-transaction', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Submit the sender-signed escrow transaction (Solana)

POST/api/v2/transactions/{id}/escrow-transaction/submitOAuth 2.0 client credentials

Accepts only the transaction `escrow-transaction` built for this transaction, with the sender's signature added. On confirmation the transaction is `escrowed`, with `escrowAddress`, `transactionHash` and the on-chain `releaseAt`. If a submit fails after the escrow landed, submitting again completes it. Once the transaction is `escrowed`, submit is refused: read the transaction instead.

Path parameters

  • idstringrequired

Request body

  • signedTransactionstringrequired

    The transaction from POST /transactions/{id}/escrow-transaction, signed by the sender's wallet, base64-encoded.

Responses

200
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400`INVALID_SIGNED_TRANSACTION`, or not awaiting the sender
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
409`BLOCKHASH_EXPIRED` (build a new one), `ESCROW_TERMS_MISMATCH`, or `ESCROW_NOT_YET_VISIBLE` (the escrow is still settling on chain; submit again shortly)
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422`TRANSACTION_FAILED`: Solana rejected it
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/escrow-transaction/submit' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "signedTransaction": "string"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/escrow-transaction/submit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "signedTransaction": "string"
  }),
});
const result = await response.json();

Record the on-chain transaction hash for a RAW transfer

POST/api/v2/transactions/{id}/hashOAuth 2.0 client credentials

v1 called this `submit-hash`; the verb already says you are submitting. Pairs with `escrow-hash` for COINBAX escrows.

Path parameters

  • idstringrequired

Request body

  • transactionHashstringrequired

    Blockchain transaction hash from user wallet

Responses

200
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Invalid transaction state
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/hash' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/hash', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }),
});
const result = await response.json();

Refund transaction

POST/api/v2/transactions/{id}/refundOAuth 2.0 client credentials

Returns escrowed funds to the sender. Requires `reverse:transactions` in v2; v1 required `cancel:transactions`, which is not accepted here. `reverse:` does not inherit from the v1 scopes — they are siblings in the hierarchy — so a token minted for v1 must be re-issued.

Path parameters

  • idstringrequired

Request body

  • reasonstringrequired

    Reason for refund

Responses

200Transaction refunded successfully
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Invalid transaction state for refund
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
403Token lacks `reverse:transactions`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "reverse:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/refund' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer request - item not as described"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/refund', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "Customer request - item not as described"
  }),
});
const result = await response.json();

Release escrowed funds to the recipient (Coinbax broadcasts)

POST/api/v2/transactions/{id}/releaseOAuth 2.0 client credentials

Coinbax submits the on-chain release for you. Absorbs v1 `complete` — same intent, different signer; the platform picks the on-chain path from which wallet signs and whether the hold window has elapsed, so you never name a contract function. Call `POST /transactions/{id}/release/attest` instead if you want to broadcast yourself. **Preconditions** — each mirrors an on-chain revert, so a failure here is the chain refusing, not a Coinbax policy: - the escrow is still active (a released, refunded or rejected escrow reverts `EscrowNotActive` — one revert covers all three, so check `GET /transactions/{id}` rather than inferring the cause) - the hold window has elapsed, i.e. `[releaseTime, ∞)`. Release opens **at** `releaseTime`; before that the chain reverts `ReleaseTimeNotReached`. Use `release-early` to waive the remainder. - every required release control has passed. A failed required control auto-rejects the escrow and refunds the sender on-chain — do not then attempt a release.

Path parameters

  • idstringrequired

Request body

  • notestring

    Optional completion note

Responses

200Released. Returns the full transaction, including its terminal status and the broadcast hash.
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Not an eligible escrow, wrong status, no on-chain escrow id, or still inside the hold window.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "move:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/release' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Service delivered successfully"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/release', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "note": "Service delivered successfully"
  }),
});
const result = await response.json();

Release early with a sender signature (Coinbax broadcasts)

POST/api/v2/transactions/{id}/release-earlyOAuth 2.0 client credentials

Submits a sender-signed early release through the Coinbax relayer, which pays the gas. Get the payload from `POST /transactions/{id}/release-early/attest`, have the sender wallet sign it, then post the signature here. The signature is submitted **split** as `deadline`, `v`, `r`, `s` — not as a packed 65-byte hex string. Most wallet libraries return the packed form, so split it before calling. **Preconditions** — each mirrors an on-chain revert: - the escrow is still active (`EscrowNotActive`) - the signature has not expired: valid while `block.timestamp <= deadline`, so equal is still valid (`ReleaseAuthExpired`) - the recovered signer is the escrow sender (`OnlySenderCanRelease`) - the workspace escrow has a relayer configured; without one the chain reverts `NotAuthorizedRelayer` and no funds move Releasing early is final and forfeits the remaining hold window.

Path parameters

  • idstringrequired

Request body

  • deadlinestringrequired

    Unix-seconds after which the authorization is expired.

  • vnumberrequired

    y-parity of the signature (27 or 28).

  • rstringrequired

    r component of the signature.

  • sstringrequired

    s component of the signature.

Responses

200Released early. Returns the full transaction.
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Not an eligible escrow, wrong status, expired or malformed signature, or the signer is not the sender.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
403Early release is not enabled for this workspace.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422ESCROW_NOT_VERIFIED: the platform could not confirm the escrow supports early release (a transient probe/RPC failure, or a non-WorkspaceEscrow contract). Retry shortly; if it persists, release after the hold window instead.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "move:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/release-early' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "deadline": "1999999999",
  "v": 100.5,
  "r": "string",
  "s": "string"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/release-early', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "deadline": "1999999999",
    "v": 100.5,
    "r": "string",
    "s": "string"
  }),
});
const result = await response.json();

Get the payload for the sender to sign for an early release

POST/api/v2/transactions/{id}/release-early/attestOAuth 2.0 client credentials

Runs the release controls and, only if they pass outright, returns the EIP-712 payload for the sender wallet to sign. No transaction, no gas, no funds moved. Always returns **200** with a `mode`. `signature_required` carries `typedData`; the other three carry none, and none of them is an error condition in itself. **The payload has no nonce, deliberately.** Replay protection is structural, not counter-based — see the response schema. Do not add your own replay guard.

Path parameters

  • idstringrequired

Responses

200`signature_required` with the payload to sign, or `permissionless` / `under_review` / `rejected` when no payload should be emitted.
  • modeobjectrequired

    What to do next. Branch on this rather than on transaction state.

    • ReleaseAttestationMode
      enum"signature_required" · "permissionless" · "under_review" · "rejected"

      What to do next. Branch on this rather than on transaction state.

  • transactionIdstring (uuid)required
  • typedDataobject

    Present only when `mode` is `signature_required`. Sign this with the sender wallet and submit the signature to the matching non-attest route. **There is no nonce field, and that is deliberate.** Replay protection is structural rather than counter-based: `escrowId` is inside the signed struct, `verifyingContract` is this workspace's clone, `chainId` is in the domain, and a successful release clears the escrow's active flag so re-submitting the same signature reverts. Do not build your own replay guard, and do not look for a nonce to increment. `deadline` is the only time bound the signer controls.

    • Eip712ReleasePayloadDto
      • domainEip712DomainDtorequired
        • namestringrequired
        • versionstringrequired
        • chainIdnumberrequired

          Chain the signature is bound to.

        • verifyingContractstringrequired

          The escrow CLONE address for this workspace — not a shared implementation or factory address. Each workspace has its own clone and the contract recomputes its domain separator from its own address, so a signature cannot be replayed against another clone. Do not cache one value across workspaces.

      • typesobjectrequired

        EIP-712 type definitions. Exactly one struct: `ReleaseEarly(bytes32 escrowId,uint256 deadline)`.

        object

        EIP-712 type definitions. Exactly one struct: `ReleaseEarly(bytes32 escrowId,uint256 deadline)`.

      • primaryTypestringrequired
      • messageEip712MessageDtorequired
        • escrowIdstringrequired

          On-chain escrow id (bytes32).

        • deadlinestringrequired

          Expiry as unix seconds, sent as a DECIMAL STRING. `uint256` exceeds Number.MAX_SAFE_INTEGER, so a JSON number would risk precision loss. The signature is valid while `block.timestamp <= deadline` — equal is still valid.

  • consequencestring

    Present with `signature_required` on an early release. Show this to the sender before they sign — the hold window is a protection they are waiving.

  • releasableAtstring

    Present when `mode` is `permissionless`: the hold window elapsed at this time, so the release needs no signature from anyone.

{
  "mode": {},
  "transactionId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "typedData": {
    "domain": {
      "name": "WorkspaceEscrow",
      "version": "1",
      "chainId": 8453,
      "verifyingContract": "0xd80cd47516B4f592eEAac19bCf424bE30a088819"
    },
    "types": {
      "ReleaseEarly": [
        {
          "name": "escrowId",
          "type": "bytes32"
        },
        {
          "name": "deadline",
          "type": "uint256"
        }
      ]
    },
    "primaryType": "ReleaseEarly",
    "message": {
      "escrowId": "0x9c22ff5f21f0b81b113e63f7db6da94fedef11b2119b4088b89664fb9a3cb658",
      "deadline": "1788284400"
    }
  },
  "consequence": "Releasing now is final; you forfeit the remaining hold window.",
  "releasableAt": "2026-09-04T18:22:00.000Z"
}
400Not an eligible escrow, wrong status, or not active on-chain.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
403Early release is not enabled for this workspace.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "move:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/release-early/attest' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/release-early/attest', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Attest a release so you can broadcast it yourself

POST/api/v2/transactions/{id}/release/attestOAuth 2.0 client credentials

Runs the release controls and records the aggregate result on-chain, so your own release write does not revert on the escrow's control gate. **Never moves funds itself.** Always returns **200** with a `mode` telling you what to do next — including `permissionless`, when the hold window has elapsed and the on-chain release needs no signature from anyone. That is not an error: asking for a payload you do not need is a well-formed question. A 400 here means the request itself was invalid (wrong status, no escrow), never "you did not need a signature".

Path parameters

  • idstringrequired

Responses

200One of four modes: `signature_required` (sign `typedData`), `permissionless` (no signature needed), `under_review` (a control has not resolved), `rejected` (a required control failed; the escrow was refunded on-chain).
  • modeobjectrequired

    What to do next. Branch on this rather than on transaction state.

    • ReleaseAttestationMode
      enum"signature_required" · "permissionless" · "under_review" · "rejected"

      What to do next. Branch on this rather than on transaction state.

  • transactionIdstring (uuid)required
  • typedDataobject

    Present only when `mode` is `signature_required`. Sign this with the sender wallet and submit the signature to the matching non-attest route. **There is no nonce field, and that is deliberate.** Replay protection is structural rather than counter-based: `escrowId` is inside the signed struct, `verifyingContract` is this workspace's clone, `chainId` is in the domain, and a successful release clears the escrow's active flag so re-submitting the same signature reverts. Do not build your own replay guard, and do not look for a nonce to increment. `deadline` is the only time bound the signer controls.

    • Eip712ReleasePayloadDto
      • domainEip712DomainDtorequired
        • namestringrequired
        • versionstringrequired
        • chainIdnumberrequired

          Chain the signature is bound to.

        • verifyingContractstringrequired

          The escrow CLONE address for this workspace — not a shared implementation or factory address. Each workspace has its own clone and the contract recomputes its domain separator from its own address, so a signature cannot be replayed against another clone. Do not cache one value across workspaces.

      • typesobjectrequired

        EIP-712 type definitions. Exactly one struct: `ReleaseEarly(bytes32 escrowId,uint256 deadline)`.

        object

        EIP-712 type definitions. Exactly one struct: `ReleaseEarly(bytes32 escrowId,uint256 deadline)`.

      • primaryTypestringrequired
      • messageEip712MessageDtorequired
        • escrowIdstringrequired

          On-chain escrow id (bytes32).

        • deadlinestringrequired

          Expiry as unix seconds, sent as a DECIMAL STRING. `uint256` exceeds Number.MAX_SAFE_INTEGER, so a JSON number would risk precision loss. The signature is valid while `block.timestamp <= deadline` — equal is still valid.

  • consequencestring

    Present with `signature_required` on an early release. Show this to the sender before they sign — the hold window is a protection they are waiving.

  • releasableAtstring

    Present when `mode` is `permissionless`: the hold window elapsed at this time, so the release needs no signature from anyone.

{
  "mode": {},
  "transactionId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "typedData": {
    "domain": {
      "name": "WorkspaceEscrow",
      "version": "1",
      "chainId": 8453,
      "verifyingContract": "0xd80cd47516B4f592eEAac19bCf424bE30a088819"
    },
    "types": {
      "ReleaseEarly": [
        {
          "name": "escrowId",
          "type": "bytes32"
        },
        {
          "name": "deadline",
          "type": "uint256"
        }
      ]
    },
    "primaryType": "ReleaseEarly",
    "message": {
      "escrowId": "0x9c22ff5f21f0b81b113e63f7db6da94fedef11b2119b4088b89664fb9a3cb658",
      "deadline": "1788284400"
    }
  },
  "consequence": "Releasing now is final; you forfeit the remaining hold window.",
  "releasableAt": "2026-09-04T18:22:00.000Z"
}
400Not an eligible escrow, wrong status, or no on-chain escrow.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422RELEASE_WINDOW_NOT_ELAPSED: the escrow is still inside its hold window, so releasing now requires the sender to waive the remainder. Use `release-early/attest` to get the payload for them to sign, or wait for the window to elapse.
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "move:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/release/attest' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/release/attest', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
  },
});
const result = await response.json();

Rescind transaction during hold period (sender only)

POST/api/v2/transactions/{id}/rescindOAuth 2.0 client credentials

Allows the sender to cancel a transaction during the Payment Hold Period and have funds returned to their wallet. Only available if the TimeDelay control has allowSenderRescind enabled. Requires `reverse:transactions` in v2; v1 required `rescind:transactions`.

Path parameters

  • idstringrequired

Request body

  • reasonstring

    Reason for rescinding the transaction (required if control config has rescindRequiresReason: true)

  • senderWalletstringrequired

    Sender wallet address for authorization verification

Responses

200Transaction rescinded successfully, funds returned to sender
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400Transaction cannot be rescinded (not in ESCROWED status, rescind not enabled, or rescind window expired)
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
403Only the sender can rescind a transaction, or the token lacks `reverse:transactions`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "reverse:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/rescind' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Changed my mind about the purchase",
  "senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/rescind', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "Changed my mind about the purchase",
    "senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
  }),
});
const result = await response.json();

Build the cancel for the sender to sign (Solana)

POST/api/v2/transactions/{id}/rescind-transactionOAuth 2.0 client credentials

For a Solana escrow its sender funded with their own wallet (signerType `external_wallet`), returns the `cancel_escrow` transaction that rescinds it. The same rules as `/rescind` apply: the sender wallet must match exactly, the Payment Hold Period control must allow a rescind, and its window must be open. Coinbax pays the network fee; the escrow balance returns to the sender. Nothing is submitted. Sign it and post it to `/transactions/{id}/rescind-transaction/submit` before `lastValidBlockHeight`.

Path parameters

  • idstringrequired

Request body

  • reasonstring

    Reason for rescinding the transaction (required if control config has rescindRequiresReason: true)

  • senderWalletstringrequired

    Sender wallet address for authorization verification

Responses

200
  • transactionstringrequired

    The Solana `cancel_escrow` transaction, base64-encoded. Coinbax has signed it as the fee payer only; the sender signs it with their own wallet (the wallet's signTransaction, not signAndSendTransaction) and posts it to the submit endpoint.

  • escrowAddressstringrequired

    The escrow account (a program-derived address) it cancels. Its whole balance returns to the sender's token account.

  • lastValidBlockHeightnumberrequired

    The last block height at which the transaction can land. Past it, build a new one.

{
  "transaction": "string",
  "escrowAddress": "string",
  "lastValidBlockHeight": 100.5
}
400Not a sender-signed Solana escrow, not ESCROWED, rescind not enabled, outside the rescind window, or a required reason is missing
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
403The wallet is not the sender, or the token lacks `reverse:transactions`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
409`CANCEL_WINDOW_CLOSED` (the release time has passed) or `ESCROW_NOT_FOUND` (nothing on chain to cancel)
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422`SENDER_TOKEN_ACCOUNT_MISSING`: the sender closed the token account the balance returns to
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "reverse:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/rescind-transaction' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Changed my mind about the purchase",
  "senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/rescind-transaction', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "Changed my mind about the purchase",
    "senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
  }),
});
const result = await response.json();

Submit the sender-signed cancel (Solana)

POST/api/v2/transactions/{id}/rescind-transaction/submitOAuth 2.0 client credentials

Accepts only the cancel `rescind-transaction` built for this escrow, with the sender's signature added. On confirmation the transaction is `rescinded`, as `/rescind` leaves one, with the cancel's signature in `metadata.rescindTransactionHash`. If a submit fails after the cancel landed, submitting the same signed cancel again records it.

Path parameters

  • idstringrequired

Request body

  • reasonstring

    Reason for rescinding the transaction (required if control config has rescindRequiresReason: true)

  • senderWalletstringrequired

    Sender wallet address for authorization verification

  • signedTransactionstringrequired

    The transaction from POST /transactions/{id}/rescind-transaction, signed by the sender's wallet, base64-encoded.

Responses

200
  • paymentRailobject

    Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

    • PaymentRail
      enum"stablecoin" · "tokenized_deposit" · "fed_now" · "rtp" · "wire" · "ach"

      Which network moves the money. Not the same as `rail` (the gas-payment path of an on-chain escrow).

  • phaseenum"PRE_ESCROW" · "POST_ESCROW" · "PRE_RELEASE" · "POST_RELEASE"

    Lifecycle phase: Verify (PRE_ESCROW), Fund (POST_ESCROW), Confirm (PRE_RELEASE), Settle (POST_RELEASE).

  • holdReasonobject

    Why the transaction is held; null when it is not.

    • HoldReason
      enum"insufficient_customer_funds" · "watchlist_match" · "screening_unavailable" · "dependency_unavailable" · "beneficiary_account_verification_failed" · "master_account_shortfall" · "rtp_position_shortfall" · "reconciliation_mismatch" · "deposit_to_frozen_address" · "deposit_to_unrecoverable_address" · "no_receive_template"

      Why the transaction is held; null when it is not.

  • nextActionobject

    What clears the hold.

    • NextAction
      enum"ops_review" · "request_liquidity" · "await_funds" · "await_settlement"

      What clears the hold.

  • endToEndIdobject

    ISO 20022 EndToEndId.

    object

    ISO 20022 EndToEndId.

  • stablecoinobject

    Present on single-transaction reads when paymentRail is stablecoin.

    • TransactionStablecoin
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • fromAddressstringrequired
      • toAddressstringrequired
      • escrowAddressobject
        object
      • escrowIdobject
        object
      • transactionHashobject
        object
      • releaseTxHashobject
        object
      • burnUsdAmountobject
        object
      • circleTransferIdobject
        object
      • gasRailobject
        • Rail
          enum"rail-a" · "rail-b" · "rail-c"
  • tokenizedDepositobject

    Present on single-transaction reads when paymentRail is tokenized_deposit.

    • TransactionTokenizedDeposit
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • networkstringrequired
      • tokenAddressobject
        object
      • issuerInstitutionobject
        object
      • fromAddressstringrequired
      • toAddressstringrequired
      • transactionHashobject
        object
  • fedNowobject

    Present on single-transaction reads when paymentRail is fed_now.

    • TransactionFedNow
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • masterAccountRefobject
        object
  • rtpobject

    Present on single-transaction reads when paymentRail is rtp.

    • TransactionRtp
      • idstringrequired
      • transactionIdstringrequired
      • createdAtstring (date-time)required
      • updatedAtstring (date-time)required
      • originatorAccountNumberobject
        object
      • originatorRoutingNumberobject
        object
      • beneficiaryNameobject
        object
      • beneficiaryAccountNumberobject
        object
      • beneficiaryRoutingNumberobject
        object
      • glAccountIdobject
        object
      • glTransferReferenceobject
        object
      • liquidityAvailableobject
        object
      • liquidityBufferobject
        object
      • liquidityShortfallobject
        object
      • liquidityRequestReferenceobject
        object
      • messageIdobject
        object
      • acknowledgementStatusenum"pending" · "acknowledged" · "rejected" · "settled"
      • settlementTimestampobject
        object
      • positionAccountRefobject
        object
  • releaseTxHashobject
    object
  • burnUsdAmountobject
    object
  • circleTransferIdobject
    object
  • rescindobject

    Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.

    • TransactionRescindInfo
      • allowedbooleanrequired

        Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.

      • deadlineobjectrequired

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

        object

        ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.

      • requiresReasonbooleanrequired

        Whether the rescind endpoint requires a non-empty `reason` field in the request body.

      • notifyRecipientbooleanrequired

        Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.

{
  "paymentRail": {},
  "phase": "PRE_ESCROW",
  "holdReason": {},
  "nextAction": {},
  "endToEndId": {},
  "stablecoin": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "fromAddress": "string",
    "toAddress": "string",
    "escrowAddress": {},
    "escrowId": {},
    "transactionHash": {},
    "releaseTxHash": {},
    "burnUsdAmount": {},
    "circleTransferId": {},
    "gasRail": {}
  },
  "tokenizedDeposit": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "network": "string",
    "tokenAddress": {},
    "issuerInstitution": {},
    "fromAddress": "string",
    "toAddress": "string",
    "transactionHash": {}
  },
  "fedNow": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "masterAccountRef": {}
  },
  "rtp": {
    "id": "string",
    "transactionId": "string",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "originatorAccountNumber": {},
    "originatorRoutingNumber": {},
    "beneficiaryName": {},
    "beneficiaryAccountNumber": {},
    "beneficiaryRoutingNumber": {},
    "glAccountId": {},
    "glTransferReference": {},
    "liquidityAvailable": {},
    "liquidityBuffer": {},
    "liquidityShortfall": {},
    "liquidityRequestReference": {},
    "messageId": {},
    "acknowledgementStatus": "pending",
    "settlementTimestamp": {},
    "positionAccountRef": {}
  },
  "releaseTxHash": {},
  "burnUsdAmount": {},
  "circleTransferId": {},
  "rescind": {
    "allowed": true,
    "deadline": "2026-06-15T12:00:00.000Z",
    "requiresReason": false,
    "notifyRecipient": true
  }
}
400`INVALID_SIGNED_TRANSACTION` (build a new one), or the rescind is not allowed (see `rescind-transaction`)
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
403The wallet is not the sender, or the token lacks `reverse:transactions`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
404Transaction not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
409`BLOCKHASH_EXPIRED` (build a new one), `CANCEL_WINDOW_CLOSED`, `ESCROW_NOT_FOUND`, or `RESCIND_SUBMISSION_IN_PROGRESS`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
422`TRANSACTION_FAILED` (Solana rejected it) or `SENDER_TOKEN_ACCOUNT_MISSING`
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "reverse:transactions"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/transactions/<id>/rescind-transaction/submit' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Changed my mind about the purchase",
  "senderWallet": "0x1234567890abcdef1234567890abcdef12345678",
  "signedTransaction": "string"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/transactions/<id>/rescind-transaction/submit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "Changed my mind about the purchase",
    "senderWallet": "0x1234567890abcdef1234567890abcdef12345678",
    "signedTransaction": "string"
  }),
});
const result = await response.json();