x402 - HTTP 402 Payment Protocol

💰 Give Claude Money!

npx @nirholas/universal-crypto-mcp

Overview

x402 is an open standard for internet native payments. It aims to support all networks (both crypto & fiat) and forms of value (stablecoins, tokens, fiat).

Why x402 for AI?

Challenge	Traditional	x402
Account Required	✗ Yes	✓ No
Human Approval	✗ Every time	✓ Pre-authorized
Micropayments	✗ Min $0.50+	✓ Any amount
Programmable	✗ Limited	✓ Full SDK
Speed	✗ Days to settle	✓ Seconds

Quick Start (5 Lines!)

// Configure
export X402_PRIVATE_KEY=0x...

// Make paid request (auto-handles 402)
const data = await x402_pay_request({
  url: "https://api.example.com/premium",
  maxPayment: "0.10"
});

MCP Tools Reference

Tool	Description
`x402_pay_request`	Make HTTP request with automatic payment
`x402_balance`	Check wallet balance (USDC/USDs + native)
`x402_send`	Send direct payment to address
`x402_estimate`	Check cost before paying
`x402_networks`	List supported networks
`x402_address`	Get your wallet address
`x402_yield`	Check USDs yield earnings
`x402_batch_send`	Send multiple payments in one tx
`x402_gasless_send`	Send via EIP-3009 (recipient pays gas)
`x402_approve`	Approve token spending
`x402_apy`	Get current USDs APY
`x402_yield_estimate`	Project yield over time
`x402_tx_status`	Check transaction status
`x402_config`	View current configuration

📖 Full Tools Reference

Documentation

Document	Description
QUICKSTART.md	5-minute setup guide
MCP_TOOLS.md	Complete tools reference
ARCHITECTURE.md	Technical deep dive
EXAMPLES.md	Real-world use cases
SECURITY.md	Security best practices
llms.txt	LLM-readable summary

Protocol Details

x402 is an open standard for internet native payments. It aims to support all networks (both crypto & fiat) and forms of value (stablecoins, tokens, fiat).

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [...],                 // As many networks / schemes as you want to support
        description: "Weather data",    // what your endpoint does
      },
    },
  ),
);
// That's it! See examples/ for full details

Installation

Typescript

# All available reference sdks
npm install @x402/core @x402/evm @x402/svm @x402/axios @x402/fetch @x402/express @x402/hono @x402/next @x402/paywall @x402/extensions

# Minimal Fetch client
npm install @x402/core @x402/evm @x402/svm @x402/fetch

# Minimal express Server
npm install @x402/core @x402/evm @x402/svm @x402/express

Python

pip install x402

Go

go get github.com/coinbase/x402/go

Principles

Open standard: the x402 protocol will never force reliance on a single party
HTTP Native: x402 is meant to seamlessly complement the existing HTTP request made by traditional web services, it should not mandate additional requests outside the scope of a typical client / server flow.
Chain and token agnostic: we welcome contributions that add support for new chains, signing standards, or schemes, so long as they meet our acceptance criteria laid out in CONTRIBUTING.md
Trust minimizing: all payment schemes must not allow for the facilitator or resource server to move funds, other than in accordance with client intentions
Easy to use: x402 needs to be 10x better than existing ways to pay on the internet. This means abstracting as many details of crypto as possible away from the client and resource server, and into the facilitator. This means the client/server should not need to think about gas, rpc, etc.

Ecosystem

The x402 ecosystem is growing! Check out our ecosystem page to see projects building with x402, including:

Client-side integrations
Services and endpoints
Ecosystem infrastructure and tooling
Learning and community resources

Want to add your project to the ecosystem? See our demo site README for detailed instructions on how to submit your project.

Roadmap: see ROADMAP.md

Documentation: see docs/ for the GitBook documentation source

Terms:

resource: Something on the internet. This could be a webpage, file server, RPC service, API, any resource on the internet that accepts HTTP / HTTPS requests.
client: An entity wanting to pay for a resource.
facilitator: A server that facilitates verification and execution of payments for one or many networks.
resource server: An HTTP server that provides an API or other resource for a client.

Technical Goals:

Permissionless and secure for clients, servers, and facilitators
Minimal friction to adopt for both client and resource servers
Minimal integration for the resource server and client (1 line for the server, 1 function for the client)
Ability to trade off speed of response for guarantee of payment
Extensible to different payment flows and networks

Specification

See specs/ for full documentation of the x402 standard/

Typical x402 flow

x402 payments typically adhere to the following flow, but servers have a lot of flexibility. See advanced folders in examples/.

The following outlines the flow of a payment using the x402 protocol. Note that steps (1) and (2) are optional if the client already knows the payment details accepted for a resource.

Client makes an HTTP request to a resource server.
Resource server responds with a 402 Payment Required status and a PaymentRequired b64 object return as a PAYMENT-REQUIRED header.
Client selects one of the PaymentRequirements returned by the server response and creates a PaymentPayload based on the scheme & network of the PaymentRequirements they have selected.
Client sends the HTTP request with the PAYMENT-SIGNATURE header containing the PaymentPayload to the resource server.
Resource server verifies the PaymentPayload is valid either via local verification or by POSTing the PaymentPayload and PaymentRequirements to the /verify endpoint of a facilitator.
Facilitator performs verification of the object based on the scheme and network of the PaymentPayload and returns a Verification Response.
If the Verification Response is valid, the resource server performs the work to fulfill the request. If the Verification Response is invalid, the resource server returns a 402 Payment Required status and a Payment Required Response JSON object in the response body.
Resource server either settles the payment by interacting with a blockchain directly, or by POSTing the Payment Payload and Payment PaymentRequirements to the /settle endpoint of a facilitator server.
Facilitator server submits the payment to the blockchain based on the scheme and network of the Payment Payload.
Facilitator server waits for the payment to be confirmed on the blockchain.
Facilitator server returns a Payment Execution Response to the resource server.
Resource server returns a 200 OK response to the Client with the resource they requested as the body of the HTTP response, and a PAYMENT-RESPONSE header containing the Settlement Response as Base64 encoded JSON if the payment was executed successfully.

Schemes

A scheme is a logical way of moving money.

Blockchains allow for a large number of flexible ways to move money. To help facilitate an expanding number of payment use cases, the x402 protocol is extensible to different ways of settling payments via its scheme field.

Each payment scheme may have different operational functionality depending on what actions are necessary to fulfill the payment. For example exact, the first scheme shipping as part of the protocol, would have different behavior than upto. exact transfers a specific amount (ex: pay $1 to read an article), while a theoretical upto would transfer up to an amount, based on the resources consumed during a request (ex: generating tokens from an LLM).

See specs/schemes for more details on schemes, and see specs/schemes/exact/scheme_exact_evm.md to see the first proposed scheme for exact payment on EVM chains.

Schemes vs Networks

Because a scheme is a logical way of moving money, the way a scheme is implemented can be different for different blockchains. (ex: the way you need to implement exact on Ethereum is very different from the way you need to implement exact on Solana).

Clients and facilitators must explicitly support different (scheme, network) pairs in order to be able to create proper payloads and verify / settle payments.

Supported Networks

EVM Networks (CAIP-2 Format)

Network	CAIP-2 ID	Status
Base Mainnet	`eip155:8453`	✅ Recommended
Base Sepolia	`eip155:84532`	✅ Testnet
Arbitrum One	`eip155:42161`	✅ Supported
Ethereum	`eip155:1`	✅ Supported
Polygon	`eip155:137`	✅ Supported
Optimism	`eip155:10`	✅ Supported
BNB Chain	`eip155:56`	✅ Supported

Solana Networks

Network	CAIP-2 ID	Status
Mainnet	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	✅ Supported
Devnet	`solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`	✅ Testnet

Resources

x402 Protocol: https://x402.org
Documentation: https://docs.x402.org
GitHub: https://github.com/coinbase/x402
Universal Crypto MCP: https://github.com/nirholas/universal-crypto-mcp
Discord: https://discord.gg/cdp

License

Apache-2.0 - See LICENSE for details.

💰 Give Claude Money!
npx @nirholas/universal-crypto-mcp

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

x402 - HTTP 402 Payment Protocol

Overview

Why x402 for AI?

Quick Start (5 Lines!)

MCP Tools Reference

Documentation

Protocol Details

Typescript

Python

Go

Principles

Ecosystem

Terms:

Technical Goals:

Specification

Typical x402 flow

Schemes

Schemes vs Networks

Supported Networks

EVM Networks (CAIP-2 Format)

Solana Networks

Resources

License

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

x402 - HTTP 402 Payment Protocol

Overview

Why x402 for AI?

Quick Start (5 Lines!)

MCP Tools Reference

Documentation

Protocol Details

Typescript

Python

Go

Principles

Ecosystem

Terms:

Technical Goals:

Specification

Typical x402 flow

Schemes

Schemes vs Networks

Supported Networks

EVM Networks (CAIP-2 Format)

Solana Networks

Resources

License