coinbase/x402
X402
x402 is a protocol and framework that enables cryptocurrency payments for HTTP API calls, using the HTTP 402 status code to negotiate payment before granting access to resources. It supports per-request micropayments across multiple blockchain networks, with batch settlement of off-chain vouchers into a single on-chain transaction to reduce costs. The protocol also includes wallet-based signature authentication, allowing access without a payment when only identity verification is required.
The framework distinguishes itself with a service discovery registry where paid endpoints are listed with metadata and pricing, enabling autonomous agents to find and select services programmatically. It offers flexible billing models per route—fixed price, usage-based, and aggregated batch settlement—and supports gas sponsorship so users can make payments without holding native tokens. A plugin-based payment lifecycle lets developers insert custom hooks for verification, settlement, error handling, and extensions such as marketplace listing, receipts, and gas sponsorship. The system also integrates with the Model Context Protocol, wrapping tools with payment requirements so clients can pay automatically.
Additional capabilities include HTTP middleware for accepting payments, client libraries that automate the payment handshake and retry logic, and facilitator services that offload transaction signing and on-chain settlement. The framework supports multiple EVM networks with runtime registration, handles repeat payment deduplication, and allows overriding payment amounts for usage-based settlement. Payment schemes are registered using a builder pattern, and services can be published to a searchable marketplace directory accessed via natural-language queries.
Features
- HTTP Payment Gating - Implements a protocol using HTTP 402 responses to negotiate and verify cryptocurrency payments before granting access.
- Billing Model Definitions - Defines per-route billing models with fixed, usage-based, and batched settlement options.
- Fixed-Usage-Batch Pricing Models - Supports three billing modes per API route: fixed price, usage-based, and aggregated batch settlement.
- Automatic Payment Retry Clients - Wraps web requests to automatically intercept payment responses, generate payment headers, and retry the request.
- Payment Lifecycle Hooks - Supports custom lifecycle hooks at server, client, and facilitator stages to extend payment verification and settlement logic.
- Agent Payment Facilitators - Uses a remote facilitator service to coordinate payment verification and settlement.
- AI Agent Payment Frameworks - Enables autonomous AI agents to discover, negotiate, and pay for API services using blockchain transactions.
- Facilitator-Based Settlement Offloading - Offloads payment verification and blockchain settlement to an external facilitator service.
- Multi-Chain Payment Schemes - Accepts payments across multiple blockchain networks by selecting the appropriate payment scheme automatically.
- Payment Scheme Frameworks - Defines multiple payment models including fixed-price, usage-based, and batch settlement for API routes.
- Blockchain Payment Middleware - Intercepts HTTP requests with 402 responses to negotiate and verify cryptocurrency payments before granting access.
- Multi-Blockchain Payment Processing - Processes payments across multiple blockchains using native token standards with gasless transfers.
- Multi-Chain Payment Gateways - Processes and verifies cryptocurrency transfers across multiple blockchain networks with a unified interface.
- Per-Request Payment Verifiers - Verifies cryptocurrency payments per HTTP API request with automatic handshake and retry logic.
- Batch Settlement Workflows - Aggregates multiple off-chain payment vouchers into a single on-chain transaction to reduce settlement costs.
- Payment Handshake Automations - Automates the HTTP 402 payment handshake by parsing requirements, generating signed payment payloads, and retrying requests.
- Service Discovery Registries - Maintains a machine-readable directory of paid endpoints with metadata and pricing for autonomous agent discovery.
- Wallet Ownership Verification - Provides wallet signature verification to authenticate users and authorize access to gated resources.
- Facilitated Gas Sponsorships - Enables users to make blockchain payments without holding native tokens by delegating gas costs to a facilitator.
- Paid API Request Handlers - Enables automatic payment per request when calling remote APIs, handling the payment handshake transparently.
- Model Context Protocol Payment Integrations - Integrates with the Model Context Protocol to wrap tools with payment requirements and automatic client payment.
- Blockchain Network Registration - Registers new EVM blockchains at runtime without code changes to support additional payment networks.
- Multi-Network Signature Verifications - Accepts and verifies wallet signatures across multiple blockchain networks on the same service.
- Payment Extension Plugins - Adds optional payment features like marketplace listing and gas sponsorship through extension plugins.
- Fixed-Price Payment Gating - Gates resource access behind authorization of the exact fixed price amount.
- Payment Destination Management - Configures wallet addresses as payment destinations for receiving cryptocurrency payments.
- Self-Hosted Payment Facilitators - Enables deployment of custom facilitator servers for transaction signing and gas sponsorship.
- Custom Payment Extensions - Builds custom extension objects to add tailored behaviors to the payment lifecycle.
- Cryptographic Payment Proofs - Generates cryptographically signed payment offers and receipts for verifiable proof of interaction.
- Payment Artifact Verification - Verifies signed payment offers and receipts to ensure they match and are authentic.
- Configurable Settlement Schemes - Accepts multiple settlement schemes like exact amount and up-to amount for flexible payment handling.
- Marketplace Search Engines - Provides natural-language query search for paid services, returning paginated results from the marketplace.
- Paid Service Directories - Lists paid API endpoints with pricing and metadata in a searchable directory for programmatic service discovery.
- Paid Service Catalogue Publishers - Registers web resources or tools in a marketplace directory with metadata, formats, and price information.
- Paid Service Discovery Tools - Lists all registered marketplace services with filtering by type and price for autonomous agent selection.
- Automated Payment Channel Lifecycles - Automates the full payment channel lifecycle including deposit, claiming, settling, and refunding funds.
- Payment Requirement Validators - Validates payment requirements against expected criteria such as amount, network, and scheme before authorizing a payment.
- Self-Hosted Payment Facilitators - Deploys a self-hosted facilitator for independent payment verification and settlement.
- Crypto Wallet Content Payments - Uses a cryptocurrency wallet to sign payment payloads and authorize on-chain transactions for content access.
- Gas Sponsorship for Approvals - Sponsors gas costs for token approval transactions, enabling gasless user payments.
- Wallet Signature Authentication - Authenticates HTTP requests via wallet signatures, granting resource access without on-chain transactions.
- MCP Tool Discovery Metadata - Exposes tool metadata including name, description, and input schema for discovery and invocation via a marketplace.
- Channel-Based Paid API Requests - Makes paid API requests by signing vouchers, managing deposits, and handling channel recovery transparently.
- Per-Route Extension Configuration - Configures payment extensions on a per-route basis within the middleware.
- Service Marketplace Listings - Registers HTTP endpoints with pricing and metadata in a searchable directory for autonomous service discovery.
