x402 Reference - PayAI Documentation

This page describes x402 v2 over HTTP. For the normative message definitions and newer scheme extensions, see the upstream v2 specification. Protocol support varies by facilitator; check its /supported response before choosing a network or scheme.

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 reference covers common HTTP integration messages. It is not an exhaustive specification of every transport, payment scheme, or facilitator implementation.

2. Core Payment Flow

The x402 protocol follows a standard HTTP request-response cycle with payment integration:

Client Request: Client makes an HTTP request to a resource server
Payment Required Response (402): If no valid payment is attached, the server responds with an HTTP 402 status code and includes payment requirements in the PAYMENT-REQUIRED header (base64-encoded JSON)
Payment Authorization Request: Client selects a payment requirement, constructs a payment payload, and submits it in the PAYMENT-SIGNATURE header
Settlement Response: Server verifies the payment authorization, settles the payment, and includes settlement details in the PAYMENT-RESPONSE header

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 includes payment requirements in the PAYMENT-REQUIRED header as base64-encoded JSON. Example:

{  
  "x402Version": 2,  
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    },
    {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "1000000",
      "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
      "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
      "maxTimeoutSeconds": 60,
      "extra": {
        "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
      }
    }
  ],
  "extensions": {}
}

5.1.2 Field Descriptions

The Payment Requirements Response contains the following fields:

Field Name	Type	Required	Description
`x402Version`	`number`	Required	Set to `2` for this version
`error`	`string`	Optional	Explanation for the payment challenge
`resource`	`object`	Required	Describes the protected resource
`accepts`	`array`	Required	Payment options the server accepts
`extensions`	`object`	Optional	Additional protocol features

The resource object contains:

Field Name	Type	Required	Description
`url`	`string`	Required	URL of the protected resource
`description`	`string`	Optional	Human-readable description of the resource
`mimeType`	`string`	Optional	MIME type of the expected response

Each payment requirement object in the accepts array contains:

Field Name	Type	Required	Description
`scheme`	`string`	Required	Payment scheme identifier (e.g., “exact”)
`network`	`string`	Required	Blockchain network identifier in CAIP-2 format (e.g., “eip155:84532”, “solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1”)
`amount`	`string`	Required	Required payment amount in atomic token units
`asset`	`string`	Required	Token contract address
`payTo`	`string`	Required	Recipient wallet address for the payment
`maxTimeoutSeconds`	`number`	Required	Maximum time allowed for payment completion
`extra`	`object`	Optional	Scheme-specific additional information

5.2 Payment Proof (PAYMENT-SIGNATURE Header)

5.2.1 JSON Structure

The client includes payment authorization in the PAYMENT-SIGNATURE header as base64-encoded JSON:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:84532",
    "amount": "10000",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "maxTimeoutSeconds": 60
  },
  "payload": {
    "signature": "0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c",
    "authorization": {
      "from": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
      "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "value": "10000",
      "validAfter": "1740672089",
      "validBefore": "1740672154",
      "nonce": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480"
    }
  },
  "extensions": {}
}

And on Solana:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
    "amount": "1000000",
    "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
    "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
    "maxTimeoutSeconds": 60
  },
  "payload": {
    "transaction": "base64-encoded partially-signed transaction"
  },
  "extensions": {}
}

5.2.2 Field Descriptions

The Payment Payload contains the following fields:

Field Name	Type	Required	Description
`x402Version`	`number`	Required	Set to `2`
`resource`	`object`	Optional	Resource context echoed by the client
`accepted`	`object`	Required	The selected payment option, including `scheme` and `network`
`payload`	`object`	Required	Proof or authorization for that scheme
`extensions`	`object`	Optional	Extension data returned by the client

In v2, scheme and network belong inside accepted, not at the top level of the Payment Payload. The payload field contains scheme-specific data on EVM: All fields are required.

Field Name	Type	Description
`signature`	`string`	EIP-712 signature for authorization
`authorization`	`object`	EIP-3009 authorization parameters

The authorization object contains the following fields: All fields are required.

Field Name	Type	Description
`from`	`string`	Payer’s wallet address
`to`	`string`	Recipient’s wallet address
`value`	`string`	Payment amount in atomic units
`validAfter`	`string`	Unix timestamp when authorization becomes valid
`validBefore`	`string`	Unix timestamp when authorization expires
`nonce`	`string`	32-byte random nonce to prevent replay attacks

The payload field contains scheme-specific data on SVM: All fields are required.

Field Name	Type	Description
`transaction`	`string`	Base64-encoded partially-signed transaction

5.3 Settlement Response

5.3.1 JSON Structure

After payment settlement, the server includes transaction details in the PAYMENT-RESPONSE header as base64-encoded JSON:

{
  "success": true,
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "eip155:84532",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}

5.3.2 Field Descriptions

The Settlement Response contains the following fields:

Field Name	Type	Required	Description
`success`	`boolean`	Required	Indicates whether the payment settlement was successful
`errorReason`	`string`	Optional	Error reason if settlement failed (omitted if successful)
`transaction`	`string`	Required	Transaction identifier; a failed or pending result may still include a broadcast transaction
`network`	`string`	Required	Blockchain network identifier in CAIP-2 format
`payer`	`string`	Optional	Address 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 EVM exact example below uses EIP-3009 authorization for compatible tokens. This is one scheme/network implementation, not a requirement for all x402 payments. Solana uses a different payload, described in the next section.

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:

Signature Validation: Verify the EIP-712 signature is valid and properly signed by the payer
Balance Verification: Confirm the payer has sufficient token balance for the transfer
Amount Validation: Ensure the payment amount meets or exceeds the required amount
Time Window Check: Verify the authorization is within its valid time range
Parameter Matching: Confirm authorization parameters match the original payment requirements
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.

6.2 Exact Scheme on Solana (SVM)

On Solana, the “exact” scheme uses a partially-signed transaction (base64-encoded in the payment payload) that includes a TransferChecked instruction plus compute-budget instructions. Facilitators expect a specific instruction order and enforce limits on compute units and priority fee.

6.2.1 Expected Transaction Structure

Instructions must appear in this order:

SetComputeUnitLimit — set the transaction compute unit limit
SetComputeUnitPrice — set the priority fee (in microlamports per compute unit)
TransferChecked — the token transfer (amount, mint, decimals, etc.)
Optional: Lighthouse — may be added by the wallet
Optional: Lighthouse — may be added by the wallet

Some SDK versions also include a Memo instruction for uniqueness. Additional instruction support is version-specific; use compatible SDK and facilitator versions rather than manually assuming a fixed instruction count.

6.2.2 Limits

Compute-unit and priority-fee limits are facilitator policy, not universal protocol constants. Use the supported SDK to construct the transaction and check the facilitator’s current policy when troubleshooting a rejection. Limits can change between deployments.

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": 2,
    "accepted": {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USDC", "version": "2" }
    },
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x...",
        "to": "0x...",
        "value": "10000",
        "validAfter": "1740672089",
        "validBefore": "1740672154",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:84532",
    "amount": "10000",
    "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "maxTimeoutSeconds": 60,
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "extra": {
      "name": "USDC",
      "version": "2"
    }
  }
}

Request (Exact Scheme on Solana):

{
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "1000000",
      "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
      "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
      "maxTimeoutSeconds": 60,
      "extra": { "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4" }
    },
    "payload": {
      "transaction": "base64-encoded partially-signed transaction"
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
    "amount": "1000000",
    "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
    "maxTimeoutSeconds": 60,
    "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
    "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": 2,
    "accepted": {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USDC", "version": "2" }
    },
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x...",
        "to": "0x...",
        "value": "10000",
        "validAfter": "1740672089",
        "validBefore": "1740672154",
        "nonce": "0x..."
      }
    },
    "extensions": {}
  },
  "paymentRequirements": {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    }
}

Request (Exact Scheme on Solana):

{
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "1000000",
      "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
      "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
      "maxTimeoutSeconds": 60,
      "extra": { "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4" }
    },
    "payload": {
      "transaction": "base64-encoded partially-signed transaction"
    },
    "extensions": {}
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
    "amount": "1000000",
    "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
    "payTo": "6oD1Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k8Qw1k",
    "maxTimeoutSeconds": 60,
    "extra": {
      "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4"
    }
  }
}

Successful Response:

{
  "success": true,
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "eip155:84532"
}

Error Response:

{
  "success": false,
  "errorReason": "insufficient_funds",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
  "transaction": "",
  "network": "eip155:84532"
}

7.3 GET /supported

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

Response:

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:84532"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:43113"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:43114"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "extra": {
        "feePayer": "address of facilitator"
      }
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "extra": {
        "feePayer": "address of facilitator"
      }
    }
  ],
  "extensions": [],
  "signers": {}
}

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. For how listing, refreshing, and the EXTENSION-RESPONSES header work on the PayAI facilitator, see Bazaar Discovery.

8.1 GET /discovery/resources

List discoverable x402 resources from the Bazaar.

Request Parameters:

Parameter	Type	Required	Description	Default
`limit`	`number`	Optional	Maximum number of results to return (1-1000)	100
`offset`	`number`	Optional	Number of results to skip for pagination	0

Response:

{
  "x402Version": 2,
  "items": [
    {
      "resource": "https://api.example.com/premium-data",
      "type": "http",
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:84532",
          "amount": "10000",
          "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
          "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
          "maxTimeoutSeconds": 60,
          "extra": {
            "name": "USDC",
            "version": "2"
          }
        }
      ],
      "lastUpdated": "2023-12-21T02:17:36.000Z",
      "metadata": {
        "category": "finance",
        "provider": "Example Corp"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

8.2 Discovered Resource Fields

Field Name	Type	Required	Description
`resource`	`string`	Required	The resource URL or identifier being monetized
`type`	`string`	Required	Resource type (currently “http” for HTTP endpoints)
`x402Version`	`number`	Required	Protocol version supported by the resource
`accepts`	`array`	Required	Array of payment requirement objects specifying payment methods
`lastUpdated`	`string`	Required	ISO 8601 timestamp of when the resource was last updated
`metadata`	`object`	Optional	Additional 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

# Fetch the next page
GET /discovery/resources?type=http&limit=10&offset=10

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_exact_svm_payload_transaction_instructions_length: The Solana transaction’s instruction layout does not meet the selected facilitator’s policy. Required compute-budget and transfer instructions, plus supported optional wallet or memo instructions, depend on the SDK and facilitator version (see §6.2 Exact scheme on Solana). Do not assume a universal instruction-count limit.
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

Examples of CAIP-2 network identifiers are listed below. This is not a live support guarantee; use /supported for the selected facilitator.

eip155:84532: Base Sepolia testnet (Chain ID: 84532)
eip155:8453: Base mainnet (Chain ID: 8453)
eip155:43113: Avalanche Fuji testnet (Chain ID: 43113)
eip155:43114: Avalanche mainnet (Chain ID: 43114)
solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1: Solana devnet
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp: Solana mainnet

11.2 Supported Assets

For EVM implementations using EIP-3009, token compatibility includes:

USDC: USD Coin (EIP-3009 compliant ERC-20 token)
Additional ERC-20 tokens: May be supported if they implement EIP-3009 (Transfer with Authorization)

Solana exact payments use SPL-token transfers rather than EIP-3009. Asset support depends on:

Compatibility with the selected scheme and network
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: Server middleware guide
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.

Looking for V1 documentation? Visit the V1 (Legacy) documentation section.

13. Version History

Version	Date	Changes	Author
v0.1	2025-8-29	Initial draft	[derived from repository]

14. Supported Networks

x402 is supported on the following networks:

Network Name	V1 Network String	V2 CAIP-2 ID
Arbitrum One	`arbitrum`	`eip155:42161`
Arbitrum Sepolia	`arbitrum-sepolia`	`eip155:421614`
Avalanche	`avalanche`	`eip155:43114`
Avalanche Fuji	`avalanche-fuji`	`eip155:43113`
Base	`base`	`eip155:8453`
Base Sepolia	`base-sepolia`	`eip155:84532`
Polygon	`polygon`	`eip155:137`
Polygon Amoy	`polygon-amoy`	`eip155:80002`
Sei	`sei`	`eip155:1329`
Sei Testnet	`sei-testnet`	`eip155:713715`
SKALE Base	`skale-base`	`eip155:1187947933`
SKALE Base Sepolia	`skale-base-sepolia`	`eip155:324705682`
Solana	`solana`	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
Solana Devnet	`solana-devnet`	`solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`
X Layer	`xlayer`	`eip155:196`
X Layer Testnet	`xlayer-testnet`	`eip155:1952`

15. Facilitators

x402 is supported by the following facilitators:

Facilitator	URL	Networks
PayAI Facilitator	https://facilitator.payai.network	Base, Base Sepolia, Solana, Solana Devnet, Avalanche

Need help?

Join our Community

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

​1. Overview

​2. Core Payment Flow

​3. Protocol Components

​4. HTTP Status Codes

​5. Data Types

​5.1 Payment Requirements Response

​5.1.1 JSON Payload

​5.1.2 Field Descriptions

​5.2 Payment Proof (PAYMENT-SIGNATURE Header)

​5.2.1 JSON Structure

​5.2.2 Field Descriptions

​5.3 Settlement Response

​5.3.1 JSON Structure

​5.3.2 Field Descriptions

​6. Payment Schemes

​6.1 Exact Scheme

​6.1.1 EIP-3009 Authorization

​6.1.2 Verification Steps

​6.1.3 Settlement

​6.2 Exact Scheme on Solana (SVM)

​6.2.1 Expected Transaction Structure

​6.2.2 Limits

​7. Facilitator Interface

​7.1 POST /verify

​Request (Exact Scheme):

​Request (Exact Scheme on Solana):

​Successful Response:

​Error Response:

​7.2 POST /settle

​Request (Exact Scheme):

​Request (Exact Scheme on Solana):

​Successful Response:

​Error Response:

​7.3 GET /supported

​Response:

​8. Discovery API

​8.1 GET /discovery/resources

​Request Parameters:

​Response:

​8.2 Discovered Resource Fields

​8.3 Bazaar Concept

​8.4 Example Usage

​9. Error Handling

​10. Security Considerations

​10.1 Replay Attack Prevention

​10.2 Authentication Integration

​11. Implementation Notes

​11.1 Supported Networks

​11.2 Supported Assets

​12. Use Cases and Applications

​12.1 AI Agent Integration

​12.2 Human User Applications

​12.3 Server Frameworks

​12.4 Client Libraries

​12.5 Advanced Patterns

​13. Version History

​14. Supported Networks

​15. Facilitators

​Need help?

Join our Community

1. Overview

2. Core Payment Flow

3. Protocol Components

4. HTTP Status Codes

5. Data Types

5.1 Payment Requirements Response

5.1.1 JSON Payload

5.1.2 Field Descriptions

5.2 Payment Proof (PAYMENT-SIGNATURE Header)

5.2.1 JSON Structure

5.2.2 Field Descriptions

5.3 Settlement Response

5.3.1 JSON Structure

5.3.2 Field Descriptions

6. Payment Schemes

6.1 Exact Scheme

6.1.1 EIP-3009 Authorization

6.1.2 Verification Steps

6.1.3 Settlement

6.2 Exact Scheme on Solana (SVM)

6.2.1 Expected Transaction Structure

6.2.2 Limits

7. Facilitator Interface

7.1 POST /verify

Request (Exact Scheme):

Request (Exact Scheme on Solana):

Successful Response:

Error Response:

7.2 POST /settle

Request (Exact Scheme):

Request (Exact Scheme on Solana):

Successful Response:

Error Response:

7.3 GET /supported

Response:

8. Discovery API

8.1 GET /discovery/resources

Request Parameters:

Response:

8.2 Discovered Resource Fields

8.3 Bazaar Concept

8.4 Example Usage

9. Error Handling

10. Security Considerations

10.1 Replay Attack Prevention

10.2 Authentication Integration

11. Implementation Notes

11.1 Supported Networks

11.2 Supported Assets

12. Use Cases and Applications

12.1 AI Agent Integration

12.2 Human User Applications

12.3 Server Frameworks

12.4 Client Libraries

12.5 Advanced Patterns

13. Version History

14. Supported Networks

15. Facilitators

Need help?