Settle Transaction#
After verification passes, submit on-chain settlement. Aligned with Coinbase V2 protocol + OKX extension field syncSettle.
Request URL#
POST /api/v6/pay/x402/settle
Request Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
| x402Version | Integer | Yes | x402 protocol version, e.g. 2 |
| paymentPayload | Object | Yes | x402 payment payload carried by the client. See PaymentPayload for details |
| paymentRequirements | Object | Yes | Payment requirements defined by the seller. See PaymentRequirements for details |
| syncSettle | Boolean | No | OKX extension. true = wait synchronously for on-chain confirmation before returning; false (default) = asynchronous, returns immediately after broadcast. Only effective for the exact scheme |
Response Parameters#
| Parameter | Type | Description |
|---|---|---|
| success | Boolean | Whether the settlement succeeded |
| errorReason | String | Machine-readable failure reason (returned on failure) |
| errorMessage | String | Human-readable failure description (returned on failure) |
| payer | String | Payer wallet address |
| transaction | String | On-chain transaction hash (returned on exact success; empty string for deferred) |
| network | String | CAIP-2 chain identifier, e.g. eip155:196 |
| status | String | OKX extension. Settlement status; see the status table below |
status Values#
| scheme | syncSettle | Result | status Value | transaction |
|---|---|---|---|---|
| exact | false (default) | Broadcast | pending | txHash |
| exact | true | On-chain confirmation succeeded | success | txHash |
| exact | true | Wait timed out | timeout | txHash |
| aggr_deferred | — | Stored | success | Empty string |
Request Example#
Bash
curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/settle' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z' \
--data '{
"x402Version": 2,
"paymentPayload": {
"x402Version": 2,
"resource": {
"url": "https://api.example.com/premium-data",
"description": "Access to premium data",
"mimeType": "application/json"
},
"accepted": {
"scheme": "exact",
"network": "eip155:196",
"amount": "10000",
"asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
"payTo": "0xRecipientAddress",
"maxTimeoutSeconds": 60,
"extra": { "name": "USDG", "version": "2" }
},
"payload": {
"signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480...",
"authorization": {
"from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
"to": "0xRecipientAddress",
"value": "10000",
"validAfter": "0",
"validBefore": "1740672154",
"nonce": "0xf374661..."
}
}
},
"paymentRequirements": {
"scheme": "exact",
"network": "eip155:196",
"amount": "10000",
"asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
"payTo": "0xRecipientAddress",
"maxTimeoutSeconds": 60,
"extra": { "name": "USDG", "version": "2" }
},
"syncSettle": true
}'
Response Example - Synchronous Settlement (syncSettle=true)#
Json
{
"code": "0",
"msg": "success",
"data": {
"success": true,
"errorReason": null,
"errorMessage": null,
"payer": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d",
"transaction": "0x4f46ed8eac92ddbccfb56a88ff827db3616c7beb191adabbeeded901340bd7d5",
"network": "eip155:196",
"status": "success"
}
}
Response Example - Asynchronous Settlement (syncSettle=false)#
Json
{
"code": "0",
"msg": "success",
"data": {
"success": true,
"errorReason": null,
"errorMessage": null,
"payer": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d",
"transaction": "0x4f46ed8eac92ddbccfb56a88ff827db3616c7beb191adabbeeded901340bd7d5",
"network": "eip155:196",
"status": "pending"
}
}
Response Example - Settlement Failed#
Json
{
"code": "0",
"msg": "success",
"data": {
"success": false,
"errorReason": "insufficient_funds",
"errorMessage": "Transaction reverted",
"payer": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d",
"transaction": "",
"network": "eip155:196",
"status": ""
}
}