Skip to main content
POST
/
v2
/
x402
/
settle
Settle payment
curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/x402/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "exact",
      "network": "eip155:84532",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "amount": "1000",
      "payTo": "0x122F8Fcaf2152420445Aa424E1D8C0306935B5c9",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    },
    "payload": {
      "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b",
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "value": "1000000000000000000",
        "validAfter": "1716150000",
        "validBefore": "1716150000",
        "nonce": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
      }
    },
    "resource": {
      "url": "https://api.example.com/premium/resource/123",
      "description": "Premium API access for data analysis.",
      "mimeType": "application/json"
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "amount": "1000000",
    "payTo": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "maxTimeoutSeconds": 10,
    "extra": {
      "name": "USDC",
      "version": "2"
    }
  }
}
'
{
  "success": false,
  "payer": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "transaction": "0x89c91c789e57059b17285e7ba1716a1f5ff4c5dace0ea5a5135f26158d0421b9",
  "network": "base",
  "errorReason": "insufficient_funds",
  "errorMessage": "Insufficient funds",
  "amount": "1000000",
  "extra": {
    "chargedAmount": "1000000",
    "channelState": {
      "channelId": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "balance": "9000000",
      "totalClaimed": "1000000",
      "withdrawRequestedAt": 0,
      "refundNonce": "0"
    },
    "voucherState": {
      "signedMaxClaimable": "1000000",
      "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"
    }
  }
}

Authorizations

​
Authorization
string
header
required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Body

application/json
​
x402Version
enum<integer>
required

The version of the x402 protocol.

Available options:
1,
2
Example:

2

​
paymentPayload
x402V2PaymentPayload · object
required

The x402 v2 protocol payment payload. Uses CAIP-2 network identifiers. The accepted field carries the full payment requirements; scheme and network are not top-level fields (they are on the nested accepted object).

Example:
{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:84532",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "amount": "1000",
    "payTo": "0x122F8Fcaf2152420445Aa424E1D8C0306935B5c9",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USDC", "version": "2" }
  },
  "payload": {
    "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b",
    "authorization": {
      "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "value": "1000000000000000000",
      "validAfter": "1716150000",
      "validBefore": "1716150000",
      "nonce": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    }
  },
  "resource": {
    "url": "https://api.example.com/premium/resource/123",
    "description": "Premium API access for data analysis.",
    "mimeType": "application/json"
  }
}
​
paymentRequirements
x402V2PaymentRequirements · object
required

The x402 v2 payment requirements. Uses CAIP-2 network identifiers and supports exact, upto, and batch-settlement schemes. Carries only the payment fields (no resource metadata — that is in the enclosing x402V2PaymentPayload.resource).

Response

Successfully settled payment on the x402 protocol.

​
success
boolean
required

Indicates whether the payment settlement is successful.

Example:

false

​
payer
string
required

The onchain address of the client that is paying for the resource.

For EVM networks, the payer will be a 0x-prefixed, checksum EVM address.

For Solana-based networks, the payer will be a base58-encoded Solana address.

Required string length: 1 - 128
Example:

"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

​
transaction
string
required

The transaction of the settlement. For EVM networks, the transaction will be a 0x-prefixed, EVM transaction hash. For Solana-based networks, the transaction will be a base58-encoded Solana signature.

Pattern: ^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{87,88})$
Example:

"0x89c91c789e57059b17285e7ba1716a1f5ff4c5dace0ea5a5135f26158d0421b9"

​
network
string
required

The network where the settlement occurred.

Example:

"base"

​
errorReason
enum<string>

The reason the payment settlement errored on the x402 protocol.

Available options:
insufficient_funds,
invalid_scheme,
invalid_network,
invalid_x402_version,
invalid_payment_requirements,
invalid_payload,
invalid_exact_evm_payload_authorization_value,
invalid_exact_evm_payload_authorization_value_too_low,
invalid_exact_evm_payload_authorization_valid_after,
invalid_exact_evm_payload_authorization_valid_before,
invalid_exact_evm_payload_authorization_typed_data_message,
invalid_exact_evm_payload_authorization_from_address_kyt,
invalid_exact_evm_payload_authorization_to_address_kyt,
invalid_exact_evm_payload_signature,
invalid_exact_evm_payload_signature_address,
invalid_exact_evm_permit2_payload_allowance_required,
invalid_exact_evm_permit2_payload_signature,
invalid_exact_evm_permit2_payload_deadline,
invalid_exact_evm_permit2_payload_valid_after,
invalid_exact_evm_permit2_payload_spender,
invalid_exact_evm_permit2_payload_recipient,
invalid_exact_evm_permit2_payload_amount,
invalid_exact_svm_payload_transaction,
invalid_exact_svm_payload_transaction_amount_mismatch,
invalid_exact_svm_payload_transaction_create_ata_instruction,
invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_payee,
invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_asset,
invalid_exact_svm_payload_transaction_instructions,
invalid_exact_svm_payload_transaction_instructions_length,
invalid_exact_svm_payload_transaction_instructions_compute_limit_instruction,
invalid_exact_svm_payload_transaction_instructions_compute_price_instruction,
invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high,
invalid_exact_svm_payload_transaction_instruction_not_spl_token_transfer_checked,
invalid_exact_svm_payload_transaction_instruction_not_token_2022_transfer_checked,
invalid_exact_svm_payload_transaction_not_a_transfer_instruction,
invalid_exact_svm_payload_transaction_cannot_derive_receiver_ata,
invalid_exact_svm_payload_transaction_receiver_ata_not_found,
invalid_exact_svm_payload_transaction_sender_ata_not_found,
invalid_exact_svm_payload_transaction_simulation_failed,
invalid_exact_svm_payload_transaction_transfer_to_incorrect_ata,
invalid_exact_svm_payload_transaction_fee_payer_included_in_instruction_accounts,
invalid_exact_svm_payload_transaction_fee_payer_transferring_funds,
settle_exact_evm_transaction_confirmation_timed_out,
settle_exact_node_failure,
settle_exact_failed_onchain,
settle_exact_svm_block_height_exceeded,
settle_exact_svm_transaction_confirmation_timed_out,
invalid_batch_settlement_evm_unknown_settle_action,
invalid_batch_settlement_evm_claim_payload,
invalid_batch_settlement_evm_settle_payload,
invalid_batch_settlement_evm_authorizer_address_mismatch,
invalid_batch_settlement_evm_claim_simulation_failed,
invalid_batch_settlement_evm_claim_transaction_failed,
invalid_batch_settlement_evm_deposit_transaction_failed,
invalid_batch_settlement_evm_refund_simulation_failed,
invalid_batch_settlement_evm_refund_transaction_failed,
invalid_batch_settlement_evm_settle_simulation_failed,
invalid_batch_settlement_evm_settle_transaction_failed,
invalid_batch_settlement_evm_transaction_reverted,
invalid_batch_settlement_evm_wait_for_receipt_failed,
invalid_batch_settlement_evm_erc20_approval_broadcast_failed,
invalid_batch_settlement_evm_channel_id_mismatch,
invalid_batch_settlement_evm_channel_state_read_failed,
invalid_batch_settlement_evm_cumulative_below_claimed,
invalid_batch_settlement_evm_cumulative_exceeds_balance,
invalid_batch_settlement_evm_eip2612_amount_mismatch,
invalid_batch_settlement_evm_eip2612_asset_mismatch,
invalid_batch_settlement_evm_eip2612_deadline_expired,
invalid_batch_settlement_evm_eip2612_invalid_format,
invalid_batch_settlement_evm_eip2612_invalid_signature,
invalid_batch_settlement_evm_eip2612_owner_mismatch,
invalid_batch_settlement_evm_eip2612_spender_mismatch,
invalid_batch_settlement_evm_erc20_approval_asset_mismatch,
invalid_batch_settlement_evm_erc20_approval_from_mismatch,
invalid_batch_settlement_evm_erc20_approval_invalid_format,
invalid_batch_settlement_evm_erc20_approval_unavailable,
invalid_batch_settlement_evm_erc20_approval_wrong_spender,
invalid_batch_settlement_evm_erc3009_authorization_required,
invalid_batch_settlement_evm_insufficient_balance,
invalid_batch_settlement_evm_deposit_payload,
invalid_batch_settlement_evm_receive_authorization_signature,
invalid_batch_settlement_evm_refund_payload,
invalid_batch_settlement_evm_voucher_payload,
invalid_batch_settlement_evm_voucher_signature,
invalid_batch_settlement_evm_missing_eip712_domain,
invalid_batch_settlement_evm_payload_authorization_valid_after,
invalid_batch_settlement_evm_payload_authorization_valid_before,
invalid_batch_settlement_evm_permit2_allowance_required,
invalid_batch_settlement_evm_permit2_amount_mismatch,
invalid_batch_settlement_evm_permit2_authorization_required,
invalid_batch_settlement_evm_permit2_deadline_expired,
invalid_batch_settlement_evm_permit2_invalid_signature,
invalid_batch_settlement_evm_permit2_invalid_spender,
invalid_batch_settlement_evm_receiver_authorizer_mismatch,
invalid_batch_settlement_evm_receiver_mismatch,
invalid_batch_settlement_evm_rpc_read_failed,
invalid_batch_settlement_evm_token_mismatch,
invalid_batch_settlement_evm_withdraw_delay_mismatch,
invalid_batch_settlement_evm_withdraw_delay_out_of_range,
invalid_batch_settlement_evm_scheme,
invalid_batch_settlement_evm_network_mismatch,
invalid_batch_settlement_evm_payload_type,
invalid_batch_settlement_evm_channel_not_found,
invalid_batch_settlement_evm_deposit_simulation_failed,
invalid_exact_evm_scheme,
invalid_exact_evm_network_mismatch,
invalid_exact_evm_payload,
invalid_exact_evm_payload_missing_signature,
invalid_exact_evm_failed_to_get_network_config,
invalid_exact_evm_missing_eip712_domain,
invalid_exact_evm_recipient_mismatch,
invalid_exact_evm_authorization_value,
invalid_exact_evm_required_amount,
invalid_exact_evm_payload_authorization_value_mismatch,
invalid_exact_evm_failed_to_check_nonce,
invalid_exact_evm_nonce_already_used,
invalid_exact_evm_failed_to_get_balance,
invalid_exact_evm_insufficient_balance,
invalid_exact_evm_signature_format,
invalid_exact_evm_failed_to_verify_signature,
invalid_exact_evm_signature,
invalid_exact_evm_token_name_mismatch,
invalid_exact_evm_token_version_mismatch,
invalid_exact_evm_eip3009_not_supported,
invalid_exact_evm_transaction_simulation_failed,
invalid_exact_evm_verification_failed,
invalid_exact_evm_failed_to_parse_signature,
invalid_exact_evm_failed_to_check_deployment,
invalid_exact_evm_failed_to_execute_transfer,
invalid_exact_evm_failed_to_get_receipt,
invalid_exact_evm_transaction_failed,
invalid_exact_evm_payload_undeployed_smart_wallet,
smart_wallet_deployment_failed,
unsupported_payload_type,
invalid_erc20_approval_extension_format,
erc20_approval_tx_failed,
erc20_approval_from_mismatch,
erc20_approval_asset_mismatch,
erc20_approval_spender_not_permit2,
erc20_approval_tx_parse_failed,
erc20_approval_tx_wrong_target,
erc20_approval_tx_wrong_selector,
erc20_approval_tx_wrong_spender,
erc20_approval_tx_signer_mismatch,
erc20_approval_tx_invalid_signature,
invalid_exact_evm_unsupported_scheme,
invalid_exact_evm_extra_field,
invalid_exact_evm_payload_recipient_mismatch,
invalid_exact_evm_insufficient_funds,
invalid_exact_evm_transaction_state,
invalid_permit2_spender,
invalid_permit2_recipient_mismatch,
permit2_deadline_expired,
permit2_not_yet_valid,
permit2_amount_mismatch,
permit2_token_mismatch,
invalid_permit2_signature,
permit2_allowance_required,
permit2_invalid_amount,
permit2_invalid_destination,
permit2_invalid_owner,
permit2_payment_too_early,
permit2_invalid_nonce,
permit2_2612_amount_mismatch,
permit2_simulation_failed,
permit2_insufficient_balance,
permit2_proxy_not_deployed,
erc20_approval_insufficient_eth_for_gas,
erc20_approval_broadcast_failed,
invalid_exact_solana_unsupported_scheme,
invalid_exact_solana_network_mismatch,
invalid_exact_solana_payload_missing_fee_payer,
invalid_exact_solana_fee_payer_not_managed_by_facilitator,
invalid_exact_solana_payload_transaction,
invalid_exact_solana_payload_transaction_could_not_be_decoded,
invalid_exact_solana_payload_transaction_instructions_length,
invalid_exact_solana_payload_unknown_fourth_instruction,
invalid_exact_solana_payload_unknown_fifth_instruction,
invalid_exact_solana_payload_unknown_sixth_instruction,
invalid_exact_solana_payload_transaction_instructions_compute_limit_instruction,
invalid_exact_solana_payload_transaction_instructions_compute_price_instruction,
invalid_exact_solana_payload_transaction_instructions_compute_price_instruction_too_high,
invalid_exact_solana_payload_no_transfer_instruction,
invalid_exact_solana_payload_transaction_fee_payer_transferring_funds,
invalid_exact_solana_payload_mint_mismatch,
invalid_exact_solana_payload_recipient_mismatch,
invalid_exact_solana_payload_amount_insufficient,
invalid_exact_solana_invalid_fee_payer,
invalid_exact_solana_transaction_signing_failed,
invalid_exact_solana_transaction_simulation_failed,
invalid_exact_solana_payload_memo_mismatch,
invalid_exact_solana_payload_memo_count,
invalid_exact_solana_verification_failed,
invalid_exact_solana_fee_payer_mismatch,
invalid_exact_solana_transaction_failed,
invalid_exact_solana_transaction_confirmation_failed,
duplicate_settlement,
invalid_exact_solana_extra_field,
batch_settlement_cumulative_amount_mismatch,
batch_settlement_channel_busy,
missing_batch_settlement_channel,
batch_settlement_charge_exceeds_signed_cumulative,
batch_settlement_refund_no_balance,
batch_settlement_refund_amount_invalid,
batch_settlement_refund_amount_exceeds_balance,
amount_too_low,
invalid_amount,
kyt_risk_detected,
permit2_disabled,
preflight_validation_failed,
request_blocked_by_location,
self_send_not_allowed,
invalid_bazaar_extension,
unknown_error
Example:

"insufficient_funds"

​
errorMessage
string

The message describing the error reason.

Example:

"Insufficient funds"

​
amount
string

The amount that was settled, in atomic units.

Example:

"1000000"

​
extra
object

Optional scheme-specific success metadata returned by the facilitator.

Example:
{
  "chargedAmount": "1000000",
  "channelState": {
    "channelId": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "balance": "9000000",
    "totalClaimed": "1000000",
    "withdrawRequestedAt": 0,
    "refundNonce": "0"
  },
  "voucherState": {
    "signedMaxClaimable": "1000000",
    "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"
  }
}