Once merged, you will be able to read the x402 protocol specification in the x402 repository.

1. Overview

x402 is an open payment standard that enables clients to pay for HTTP resources using blockchain technology. The protocol leverages the existing HTTP 402 “Payment Required” status code to indicate when payment is required for resource access, providing a standardized mechanism for micropayments on the web. This specification is based on the x402 protocol implementation and documentation available in the Coinbase x402 repository. It aims to provide a comprehensive and implementation-agnostic specification for the x402 HTTP-native micropayment protocol.

2. Core Payment Flow

The x402 protocol follows a standard HTTP request-response cycle with payment integration:
  1. Client Request: Client makes an HTTP request to a resource server
  2. Payment Required Response (402): If no valid payment is attached, the server responds with an HTTP 402 status code and payment requirements
  3. Payment Authorization Request: Client submits a signed payment authorization in the subsequent request
  4. Settlement Response: Server verifies the payment authorization and initiates blockchain settlement

3. Protocol Components

The x402 protocol involves three primary components:
  • Resource Server: A web service that requires payment for access to protected resources (APIs, content, data, etc.)
  • Client: Any application or agent that requests access to protected resources
  • Facilitator: An endpoint service that handles payment verification and blockchain settlement

4. HTTP Status Codes

The x402 protocol uses standard HTTP status codes with specific semantics:
  • 200 OK: Request successful, payment verified and settled
  • 402 Payment Required: Payment required to access the resource
  • 400 Bad Request: Invalid payment payload or payment requirements
  • 500 Internal Server Error: Server error during payment processing

5. Data Types

This section defines the core data structures used in the x402 protocol.

5.1 Payment Requirements Response

5.1.1 JSON Payload

When a resource server requires payment, it responds with an HTTP 402 status code and a JSON payload containing payment requirements. Example:
{  
  "x402Version": 1,  
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "resource": "https://api.example.com/premium-data",
      "description": "Access to premium market data",
      "mimeType": "application/json",
      "outputSchema": null,
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    },
    {
      "scheme": "exact",
      "network": "solana-devnet",
      "maxAmountRequired": "1000000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
      "resource": "https://api.example.com/premium-data",
      "description": "Access to premium market data",
      "mimeType": "application/json",
      "outputSchema": null,
      "maxTimeoutSeconds": 60,
      "extra": {
        "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
      }
    }
  ]  
}

5.1.2 Field Descriptions

The Payment Requirements Response contains the following fields: All fields are required.
Field NameTypeDescription
x402VersionnumberProtocol version identifier
errorstringHuman-readable error message explaining why payment is required
acceptsarrayArray of payment requirement objects defining acceptable payment methods
Each payment requirement object in the accepts array contains:
Field NameTypeRequiredDescription
schemestringRequiredPayment scheme identifier (e.g., “exact”)
networkstringRequiredBlockchain network identifier (e.g., “base-sepolia”, “ethereum-mainnet”, “solana”)
maxAmountRequiredstringRequiredRequired payment amount in atomic token units
assetstringRequiredToken contract address
payTostringRequiredRecipient wallet address for the payment
resourcestringRequiredURL of the protected resource
descriptionstringRequiredHuman-readable description of the resource
mimeTypestringOptionalMIME type of the expected response
outputSchemaobjectOptionalJSON schema describing the response format
maxTimeoutSecondsnumberRequiredMaximum time allowed for payment completion
extraobjectOptionalScheme-specific additional information

5.2 Payment Proof (X-PAYMENT Header)

5.2.1 JSON Structure

The client includes payment authorization in the X-PAYMENT header as base64-encoded JSON:
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base-sepolia",
  "payload": {
    "signature": "0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c",
    "authorization": {
      "from": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
      "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "value": "10000",
      "validAfter": "1740672089",
      "validBefore": "1740672154",
      "nonce": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480"
    }
  }
}
And on Solana:
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "solana-devnet",
  "payload": {
    "transaction": "base64-encoded partially-signed transaction",
  }
}

5.2.2 Field Descriptions

The Payment Payload contains the following fields: All fields are required.
Field NameTypeDescription
x402VersionnumberProtocol version identifier (must be 1)
schemestringPayment scheme identifier (e.g., “exact”)
networkstringBlockchain network identifier (e.g., “base-sepolia”, “ethereum-mainnet”)
payloadobjectPayment data object
The payload field contains scheme-specific data on EVM: All fields are required.
Field NameTypeDescription
signaturestringEIP-712 signature for authorization
authorizationobjectEIP-3009 authorization parameters
The authorization object contains the following fields: All fields are required.
Field NameTypeDescription
fromstringPayer’s wallet address
tostringRecipient’s wallet address
valuestringPayment amount in atomic units
validAfterstringUnix timestamp when authorization becomes valid
validBeforestringUnix timestamp when authorization expires
noncestring32-byte random nonce to prevent replay attacks
The payload field contains scheme-specific data on SVM: All fields are required.
Field NameTypeDescription
transactionstringBase64-encoded partially-signed transaction

5.3 Settlement Response

5.3.1 JSON Structure

After payment settlement, the server includes transaction details in the X-PAYMENT-RESPONSE header as base64-encoded JSON:
{
  "success": true,
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "base-sepolia",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}

5.3.2 Field Descriptions

The Settlement Response contains the following fields:
Field NameTypeRequiredDescription
successbooleanRequiredIndicates whether the payment settlement was successful
errorReasonstringOptionalError reason if settlement failed (omitted if successful)
transactionstringRequiredBlockchain transaction hash (empty string if settlement failed)
networkstringRequiredBlockchain network identifier
payerstringRequiredAddress of the payer’s wallet

6. Payment Schemes

This section describes the payment schemes supported by the x402 protocol. Each scheme defines a specific method for authorizing and executing payments.

6.1 Exact Scheme

The “exact” scheme uses EIP-3009 (Transfer with Authorization) to enable secure, gasless transfers of specific amounts of ERC-20 tokens.

6.1.1 EIP-3009 Authorization

The authorization follows the EIP-3009 standard for transferWithAuthorization:
const authorizationTypes = {
  TransferWithAuthorization: [
    { name: "from", type: "address" },
    { name: "to", type: "address" },
    { name: "value", type: "uint256" },
    { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce", type: "bytes32" },
  ],
};

6.1.2 Verification Steps

The facilitator performs the following verification steps:
  1. Signature Validation: Verify the EIP-712 signature is valid and properly signed by the payer
  2. Balance Verification: Confirm the payer has sufficient token balance for the transfer
  3. Amount Validation: Ensure the payment amount meets or exceeds the required amount
  4. Time Window Check: Verify the authorization is within its valid time range
  5. Parameter Matching: Confirm authorization parameters match the original payment requirements
  6. Transaction Simulation: Simulate the transferWithAuthorization transaction to ensure it would succeed

6.1.3 Settlement

Settlement is performed by calling the transferWithAuthorization function on the ERC-20 contract with the signature and authorization parameters provided in the payment payload.

7. Facilitator Interface

The facilitator provides REST APIs for payment verification and settlement. This allows resource servers to delegate blockchain operations to trusted third parties or host the endpoints themselves.

7.1 POST /verify

Verifies a payment authorization without executing the transaction on the blockchain.

Request (Exact Scheme):

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base-sepolia",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x...",
        "to": "0x...",
        "value": "10000",
        "validAfter": "1740672089",
        "validBefore": "1740672154",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "10000",
    "resource": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json",
    "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "maxTimeoutSeconds": 60,
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "extra": {
      "name": "USDC",
      "version": "2"
    }
  }
}

Request (Exact Scheme on Solana):

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "solana-devnet",
    "payload": {
      "transaction": "base64-encoded partially-signed transaction",
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana-devnet",
    "maxAmountRequired": "1000000",
    "resource": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
    "maxTimeoutSeconds": 60,
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "extra": {
      "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
    }
}

Successful Response:

{
  "isValid": true,
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}

Error Response:

{
  "isValid": false,
  "invalidReason": "insufficient_funds",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}

7.2 POST /settle

Settles a payment by broadcasting the transaction to the blockchain.

Request (Exact Scheme):

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base-sepolia",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x...",
        "to": "0x...",
        "value": "10000",
        "validAfter": "1740672089",
        "validBefore": "1740672154",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "10000",
    "resource": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json",
    "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "maxTimeoutSeconds": 60,
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "extra": {
      "name": "USDC",
      "version": "2"
    }
  }
}

Request (Exact Scheme on Solana):

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "solana-devnet",
    "payload": {
      "transaction": "base64-encoded partially-signed transaction",
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana-devnet",
    "maxAmountRequired": "1000000",
    "resource": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
    "maxTimeoutSeconds": 60,
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "extra": {
      "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
    }
  }
}

Successful Response:

{
  "success": true,
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "base-sepolia"
}

Error Response:

{
  "success": false,
  "errorReason": "insufficient_funds",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
  "transaction": "",
  "network": "base-sepolia"
}

7.3 GET /supported

Returns the list of payment schemes and networks supported by the facilitator.

Response:

{
  "kinds": [
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "base-sepolia"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "base"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "avalanche-fuji"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "avalanche"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "iotex"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "solana-devnet",
      "extra": {
        "feePayer": "address of facilitator"
      }
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "solana",
      "extra": {
        "feePayer": "address of facilitator"
      }
    }
  ]
}

8. Discovery API

The x402 protocol includes a discovery mechanism that allows clients to find and explore available x402-enabled resources. This enables the creation of marketplaces (known as ‘Bazaars’) where users can discover and access monetized APIs and digital services.

8.1 GET /discovery/resources

List discoverable x402 resources from the Bazaar.

Request Parameters:

ParameterTypeRequiredDescriptionDefault
typestringOptionalFilter by resource type (e.g., “http”)-
limitnumberOptionalMaximum number of results to return (1-100)20
offsetnumberOptionalNumber of results to skip for pagination0

Response:

{
  "x402Version": 1,
  "items": [
    {
      "resource": "https://api.example.com/premium-data",
      "type": "http",
      "x402Version": 1,
      "accepts": [
        {
          "scheme": "exact",
          "network": "base-sepolia",
          "maxAmountRequired": "10000",
          "resource": "https://api.example.com/premium-data",
          "description": "Access to premium market data",
          "mimeType": "application/json",
          "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
          "maxTimeoutSeconds": 60,
          "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
          "extra": {
            "name": "USDC",
            "version": "2"
          }
        }
      ],
      "lastUpdated": 1703123456,
      "metadata": {
        "category": "finance",
        "provider": "Example Corp"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

8.2 Discovered Resource Fields

Field NameTypeRequiredDescription
resourcestringRequiredThe resource URL or identifier being monetized
typestringRequiredResource type (currently “http” for HTTP endpoints)
x402VersionnumberRequiredProtocol version supported by the resource
acceptsarrayRequiredArray of payment requirement objects specifying payment methods
lastUpdatednumberRequiredUnix timestamp of when the resource was last updated
metadataobjectOptionalAdditional metadata (category, provider, etc.)

8.3 Bazaar Concept

The Bazaar is a marketplace ecosystem where x402-enabled resources can be discovered and accessed. Key features:
  • Resource Discovery: Find APIs and services by category, provider, or payment requirements
  • Payment Transparency: View pricing and payment methods upfront
  • Provider Information: Learn about service providers and their offerings
  • Dynamic Updates: Resources can be added, updated, or removed dynamically

8.4 Example Usage

# Discover financial data APIs
GET /discovery/resources?type=http&limit=10

# Search for a specific provider
GET /discovery/resources?metadata[provider]=Coinbase

9. Error Handling

The x402 protocol defines standard error codes that may be returned by facilitators or resource servers. These error codes help clients understand why a payment failed and take appropriate action.
  • insufficient_funds: Client does not have enough tokens to complete the payment
  • invalid_exact_evm_payload_authorization_valid_after: Payment authorization is not yet valid (before validAfter timestamp)
  • invalid_exact_evm_payload_authorization_valid_before: Payment authorization has expired (after validBefore timestamp)
  • invalid_exact_evm_payload_authorization_value: Payment amount is insufficient for the required payment
  • invalid_exact_evm_payload_signature: Payment authorization signature is invalid or improperly signed
  • invalid_exact_evm_payload_recipient_mismatch: Recipient address does not match payment requirements
  • invalid_network: Specified blockchain network is not supported
  • invalid_payload: Payment payload is malformed or contains invalid data
  • invalid_payment_requirements: Payment requirements object is invalid or malformed
  • invalid_scheme: Specified payment scheme is not supported
  • unsupported_scheme: Payment scheme is not supported by the facilitator
  • invalid_x402_version: Protocol version is not supported
  • invalid_transaction_state: Blockchain transaction failed or was rejected
  • unexpected_verify_error: Unexpected error occurred during payment verification
  • unexpected_settle_error: Unexpected error occurred during payment settlement

10. Security Considerations

10.1 Replay Attack Prevention

The x402 protocol implements multiple layers of protection against replay attacks:
  • EIP-3009 Nonce: Each authorization includes a unique 32-byte nonce to prevent replay attacks
  • Blockchain Protection: EIP-3009 contracts inherently prevent nonce reuse at the smart contract level
  • Time Constraints: Authorizations have explicit valid time windows to limit their lifetime
  • Signature Verification: All authorizations are cryptographically signed by the payer

10.2 Authentication Integration

The protocol supports integration with authentication systems (e.g., Sign-In with Ethereum (SIWE)) to enable authenticated pricing models where verified users receive discounted rates or special access terms.

11. Implementation Notes

11.1 Supported Networks

The following blockchain networks are currently supported by the reference implementation:
  • base-sepolia: Base Sepolia testnet (Chain ID: 84532)
  • base: Base mainnet (Chain ID: 8453)
  • avalanche-fuji: Avalanche Fuji testnet (Chain ID: 43113)
  • avalanche: Avalanche mainnet (Chain ID: 43114)

11.2 Supported Assets

The protocol currently supports the following token types:
  • USDC: USD Coin (EIP-3009 compliant ERC-20 token)
  • Additional ERC-20 tokens: May be supported if they implement EIP-3009 (Transfer with Authorization)
Token support depends on:
  • EIP-3009 compliance for the “exact” scheme
  • Facilitator service capabilities
  • Network-specific token availability

12. Use Cases and Applications

The x402 protocol enables diverse monetization scenarios across the internet. While the core protocol is HTTP-native and chain-agnostic, specific implementations can vary based on use case requirements.

12.1 AI Agent Integration

AI agents can use x402 to autonomously pay for resources and services. The protocol supports:
  • Automatic payment handling for API calls
  • Resource discovery through facilitator services
  • Budget management and spending controls (implementation-specific)
  • Correlation tracking for operation grouping (implementation-specific)

12.2 Human User Applications

Traditional web applications can implement x402 for:
  • Session-based access (time-limited subscriptions)
  • Pay-per-use content (articles, videos, downloads)
  • API monetization with per-call pricing
  • Authentication-based pricing (discounted rates for verified users)

12.3 Server Frameworks

x402 integrates with popular web frameworks:
  • Express.js: require_payment() middleware
  • FastAPI/Flask: Framework-specific middleware
  • Hono: Edge runtime support
  • Next.js: Full-stack integration

12.4 Client Libraries

HTTP clients can be enhanced with x402 payment capabilities:
  • Axios/fetch: Browser-based payments
  • httpx/requests: Python client support
  • Custom integrations: Application-specific payment handling

12.5 Advanced Patterns

The protocol enables sophisticated monetization strategies:
  • Dynamic pricing based on user authentication or usage patterns
  • Session management for time-based access control
  • Batch payments for multiple resource access
  • Subscription models built on micropayments
Note: Implementation details for specific patterns (such as budget management, correlation tracking, or session handling) are available in application notes and implementation guides.

13. Version History

VersionDateChangesAuthor
v0.12025-8-29Initial draft[derived from repository]

14. Supported Networks

x402 is supported on the following networks:
Network NameNetwork String
Solanasolana
Solana Devnetsolana-devnet
Basebase
Base Sepoliabase-sepolia
Avalancheavalanche
Avalanche Fujiavalanche-fuji
IoTeXiotex
Seisei
Sei Testnetsei-testnet

15. Facilitators

x402 is supported by the following facilitators:
FacilitatorEndpointSupported Networks
PayAI Facilitatorhttps://facilitator.payai.networksolana, solana-devnet, base, base-sepolia, avalanche, avalanche-fuji, iotex, sei, sei-testnet
x402.org Facilitatorhttps://x402.org/facilitatorbase-sepolia
CDP’s x402 Facilitatorhttps://cdp.coinbase.combase, base-sepolia
x402.rs Facilitatorhttps://facilitator.x402.rsbase-sepolia, base, xdc

Need help?

Join our Community

Have questions or want to connect with other developers? Join our Discord server.