Accounts5

Customers6

Deposit Destinations3

Disbursements3

End User Account Management9

End User Accounts26

EVM Accounts15

EVM Smart Accounts12

EVM Swaps2

EVM Token Balances1

Faucets2

Mandates12

Onchain Data2

Onramp7

Payment Methods2

Payment Sessions21

Policy Engine5

Solana Accounts11

Solana Token Balances1

SQL API3

Transfers5

Webhooks6

x402 Facilitator10

Webhooks

Customers2

Disbursements3

Health5

Mandates8

Onchain Data3

Onramp8

Payment Sessions14

Transfers7

Wallet Webhooks12

x402 Facilitator

Settle payment

Changed on Oct 6, 2026

Settle an x402 protocol payment with a specific scheme and network.

post/v2/x402/settle

Request

Base URL: https://api.cdp.coinbase.com/platform
URL: https://api.cdp.coinbase.com/platform/v2/x402/settle
Auth: HTTP bearer

Request body

x402Version1 | 2 required

The version of the x402 protocol.

Example request

{
  "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"
    }
  }
}

Response

Successfully settled payment on the x402 protocol.

successboolean required

Indicates whether the payment settlement is successful.

errorReason'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' | 'settlement_pending' | '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'

The reason the payment settlement errored on the x402 protocol.

errorMessagestring

The message describing the error reason.

payerstring required

A blockchain address. Format varies by network (e.g., 0x-prefixed for EVM, base58 for Solana).

transactionstring 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.

networkstring required

The network where the settlement occurred.

amountstring

The amount that was settled, in atomic units.

extraobject

Optional scheme-specific success metadata returned by the facilitator.

Example response

{
  "errorReason": "insufficient_funds",
  "errorMessage": "Insufficient funds",
  "payer": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "transaction": "0x89c91c789e57059b17285e7ba1716a1f5ff4c5dace0ea5a5135f26158d0421b9",
  "network": "base",
  "amount": "1000000",
  "extra": {
    "chargedAmount": "1000000",
    "channelState": {
      "channelId": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "balance": "9000000",
      "totalClaimed": "1000000",
      "withdrawRequestedAt": 0,
      "refundNonce": "0"
    },
    "voucherState": {
      "signedMaxClaimable": "1000000",
      "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"
    }
  }
}

Changes

Oct 6, 2026156440e9f8df Revision changes
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
Sep 25, 2026229ed860a74b Revision changes
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status

Operation history (22 revisions)