How x402-foundation/x402 works
x402 is a cross-language SDK and open protocol for HTTP-native payments. Its typical workflow is: a client requests a protected resource, receives payment requirements, creates a scheme/network-specific payload, and retries; the resource server verifies it locally or through a facilitator, fulfills the request, then settles and returns a payment receipt. The repository also provides transport adapters, MCP support, extensions, and chain-specific schemes, including deferred batch settlement. Edges follow the README flow or explicit excerpts/index references; many implementation links remain unshown, so they are omitted rather than inferred.
Main entry points: server.py Resource Server · index.ts Facilitator · batch_settlement EVM Batch Settlement · route.ts Settle Endpoint
Components 20
Protocol Workflow
- Payment Client
python/x402/client.py - Resource Server
python/x402/server.py - Payment Requirements
python/x402/server_base.py
Transport Integrations
- HTTP Middleware
python/x402/http/middleware - HTTP Client Adapters
python/x402/http/x402_http_client.py - MCP Integration
python/x402/mcp/server.py
Payment Mechanisms
- EVM Exact
python/x402/mechanisms/evm/exact - EVM Upto
python/x402/mechanisms/evm/upto - EVM Batch Settlement
python/x402/mechanisms/evm/batch_settlement - EVM Channel Storage
python/x402/mechanisms/evm/batch_settlement/server/storage.py - SVM Schemes
python/x402/mechanisms/svm - TVM Schemes
python/x402/mechanisms/tvm
Facilitator and Extensions
- Facilitator
typescript/site/app/facilitator/index.ts - Verify Endpoint
typescript/site/app/facilitator/verify/route.ts - Settle Endpoint
typescript/site/app/facilitator/settle/route.ts - Protocol Extensions
python/x402/extensions - Bazaar Discovery
python/x402/extensions/bazaar/server.py
Other components
- Client
- Resource Host
- Blockchain Network
Connections 26
- Client → Resource Server: requests resource
- Resource Server → Payment Requirements: returns requirements
python/x402/server.py - Payment Requirements → Client: describes payment
- Client → Resource Server: retries with payload
- Resource Server → Facilitator: requests verification
- Resource Server → EVM Exact: verifies locally
python/x402/server.py - Facilitator → Verify Endpoint: serves verification
typescript/site/app/facilitator/verify/route.ts - Verify Endpoint → Facilitator: calls verify
typescript/site/app/facilitator/verify/route.ts - Resource Server → Resource Host: fulfills request
- Resource Server → Settle Endpoint: requests settlement
- Settle Endpoint → Facilitator: calls settle
typescript/site/app/facilitator/settle/route.ts - Facilitator → Blockchain Network: submits payment
- Settle Endpoint → Resource Server: returns settlement
- Resource Server → Client: returns resource and receipt
- HTTP Middleware → Resource Server: adapts requests
- HTTP Client Adapters → Client: handles payment retry
- MCP Integration → Resource Server: integrates payments
- Facilitator → EVM Exact: registers scheme
typescript/site/app/facilitator/index.ts - Facilitator → EVM Upto: registers scheme
typescript/site/app/facilitator/index.ts - Facilitator → EVM Batch Settlement: registers scheme
typescript/site/app/facilitator/index.ts - Facilitator → SVM Schemes: registers scheme
- Facilitator → TVM Schemes: supports scheme
- EVM Batch Settlement → EVM Channel Storage: persists channels
python/x402/mechanisms/evm/batch_settlement/server/file_storage.py - EVM Batch Settlement → Blockchain Network: settles batches
- Protocol Extensions → Resource Server: extends payment flow
- Bazaar Discovery → Facilitator: catalogs discovery