# x402-foundation/x402 architecture

> Architecture diagram of the GitHub repository x402-foundation/x402, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/x402-foundation/x402
- Repository: https://github.com/x402-foundation/x402

## Overview

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: [`python/x402/server.py`](https://github.com/x402-foundation/x402/blob/main/python/x402/server.py) (Resource Server), [`typescript/site/app/facilitator/index.ts`](https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/index.ts) (Facilitator), [`python/x402/mechanisms/evm/batch_settlement`](https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/evm/batch_settlement) (EVM Batch Settlement), [`typescript/site/app/facilitator/settle/route.ts`](https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/settle/route.ts) (Settle Endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol Workflow"]
  node_client["Payment Client<br/>[client.py]"]
  node_resource["Resource Server<br/>[server.py]"]
  node_requirements["Payment Requirements<br/>[server_base.py]"]
end

subgraph group_integration["Transport Integrations"]
  node_http["HTTP Middleware"]
  node_http_client["HTTP Client Adapters"]
  node_mcp["MCP Integration<br/>[server.py]"]
end

subgraph group_settlement["Payment Mechanisms"]
  node_evm_exact["EVM Exact"]
  node_evm_upto["EVM Upto"]
  node_evm_batch["EVM Batch Settlement"]
  node_evm_channel_store[("EVM Channel Storage<br/>[storage.py]")]
  node_svm_schemes["SVM Schemes"]
  node_tvm_schemes["TVM Schemes"]
end

subgraph group_facilitation["Facilitator and Extensions"]
  node_facilitator["Facilitator<br/>[index.ts]"]
  node_verify["Verify Endpoint<br/>[route.ts]"]
  node_settle["Settle Endpoint<br/>[route.ts]"]
  node_extensions["Protocol Extensions"]
  node_bazaar["Bazaar Discovery<br/>[server.py]"]
end

node_actor_client(("Client"))
node_actor_resource(("Resource Host"))
node_blockchain(("Blockchain Network"))

node_actor_client -->|"requests resource"| node_resource
node_resource -->|"returns requirements"| node_requirements
node_requirements -->|"describes payment"| node_actor_client
node_actor_client -->|"retries with payload"| node_resource
node_resource -->|"requests verification"| node_facilitator
node_resource -.->|"verifies locally"| node_evm_exact
node_facilitator -->|"serves verification"| node_verify
node_verify -->|"calls verify"| node_facilitator
node_resource -->|"fulfills request"| node_actor_resource
node_resource -->|"requests settlement"| node_settle
node_settle -->|"calls settle"| node_facilitator
node_facilitator -->|"submits payment"| node_blockchain
node_settle -->|"returns settlement"| node_resource
node_resource -->|"returns resource and receipt"| node_actor_client
node_http -.->|"adapts requests"| node_resource
node_http_client -.->|"handles payment retry"| node_actor_client
node_mcp -.->|"integrates payments"| node_resource
node_facilitator -->|"registers scheme"| node_evm_exact
node_facilitator -->|"registers scheme"| node_evm_upto
node_facilitator -->|"registers scheme"| node_evm_batch
node_facilitator -.->|"registers scheme"| node_svm_schemes
node_facilitator -.->|"supports scheme"| node_tvm_schemes
node_evm_batch -.->|"persists channels"| node_evm_channel_store
node_evm_batch -.->|"settles batches"| node_blockchain
node_extensions -.->|"extends payment flow"| node_resource
node_bazaar -.->|"catalogs discovery"| node_facilitator

click node_client "https://github.com/x402-foundation/x402/blob/main/python/x402/client.py"
click node_resource "https://github.com/x402-foundation/x402/blob/main/python/x402/server.py"
click node_requirements "https://github.com/x402-foundation/x402/blob/main/python/x402/server_base.py"
click node_facilitator "https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/index.ts"
click node_verify "https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/verify/route.ts"
click node_settle "https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/settle/route.ts"
click node_evm_exact "https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/evm/exact"
click node_evm_upto "https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/evm/upto"
click node_evm_batch "https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/evm/batch_settlement"
click node_evm_channel_store "https://github.com/x402-foundation/x402/blob/main/python/x402/mechanisms/evm/batch_settlement/server/storage.py"
click node_svm_schemes "https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/svm"
click node_tvm_schemes "https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/tvm"
click node_extensions "https://github.com/x402-foundation/x402/tree/main/python/x402/extensions"
click node_bazaar "https://github.com/x402-foundation/x402/blob/main/python/x402/extensions/bazaar/server.py"
click node_http "https://github.com/x402-foundation/x402/tree/main/python/x402/http/middleware"
click node_http_client "https://github.com/x402-foundation/x402/blob/main/python/x402/http/x402_http_client.py"
click node_mcp "https://github.com/x402-foundation/x402/blob/main/python/x402/mcp/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_resource,node_requirements,node_actor_client toneBlue
class node_http,node_http_client,node_mcp toneAmber
class node_evm_exact,node_evm_upto,node_evm_batch,node_evm_channel_store,node_svm_schemes,node_tvm_schemes toneMint
class node_facilitator,node_verify,node_settle,node_extensions,node_bazaar toneRose
class node_actor_resource,node_blockchain toneIndigo
```

## Components

### Protocol Workflow

- [Payment Client](https://github.com/x402-foundation/x402/blob/main/python/x402/client.py): `python/x402/client.py`
- [Resource Server](https://github.com/x402-foundation/x402/blob/main/python/x402/server.py): `python/x402/server.py`
- [Payment Requirements](https://github.com/x402-foundation/x402/blob/main/python/x402/server_base.py): `python/x402/server_base.py`

### Transport Integrations

- [HTTP Middleware](https://github.com/x402-foundation/x402/tree/main/python/x402/http/middleware): `python/x402/http/middleware`
- [HTTP Client Adapters](https://github.com/x402-foundation/x402/blob/main/python/x402/http/x402_http_client.py): `python/x402/http/x402_http_client.py`
- [MCP Integration](https://github.com/x402-foundation/x402/blob/main/python/x402/mcp/server.py): `python/x402/mcp/server.py`

### Payment Mechanisms

- [EVM Exact](https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/evm/exact): `python/x402/mechanisms/evm/exact`
- [EVM Upto](https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/evm/upto): `python/x402/mechanisms/evm/upto`
- [EVM Batch Settlement](https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/evm/batch_settlement): `python/x402/mechanisms/evm/batch_settlement`
- [EVM Channel Storage](https://github.com/x402-foundation/x402/blob/main/python/x402/mechanisms/evm/batch_settlement/server/storage.py): `python/x402/mechanisms/evm/batch_settlement/server/storage.py`
- [SVM Schemes](https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/svm): `python/x402/mechanisms/svm`
- [TVM Schemes](https://github.com/x402-foundation/x402/tree/main/python/x402/mechanisms/tvm): `python/x402/mechanisms/tvm`

### Facilitator and Extensions

- [Facilitator](https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/index.ts): `typescript/site/app/facilitator/index.ts`
- [Verify Endpoint](https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/verify/route.ts): `typescript/site/app/facilitator/verify/route.ts`
- [Settle Endpoint](https://github.com/x402-foundation/x402/blob/main/typescript/site/app/facilitator/settle/route.ts): `typescript/site/app/facilitator/settle/route.ts`
- [Protocol Extensions](https://github.com/x402-foundation/x402/tree/main/python/x402/extensions): `python/x402/extensions`
- [Bazaar Discovery](https://github.com/x402-foundation/x402/blob/main/python/x402/extensions/bazaar/server.py): `python/x402/extensions/bazaar/server.py`

### Other components

- **Client**
- **Resource Host**
- **Blockchain Network**

## Connections

- Client → Resource Server: requests resource
- Resource Server → Payment Requirements: returns requirements (evidence: `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 (evidence: `python/x402/server.py`)
- Facilitator → Verify Endpoint: serves verification (evidence: `typescript/site/app/facilitator/verify/route.ts`)
- Verify Endpoint → Facilitator: calls verify (evidence: `typescript/site/app/facilitator/verify/route.ts`)
- Resource Server → Resource Host: fulfills request
- Resource Server → Settle Endpoint: requests settlement
- Settle Endpoint → Facilitator: calls settle (evidence: `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 (evidence: `typescript/site/app/facilitator/index.ts`)
- Facilitator → EVM Upto: registers scheme (evidence: `typescript/site/app/facilitator/index.ts`)
- Facilitator → EVM Batch Settlement: registers scheme (evidence: `typescript/site/app/facilitator/index.ts`)
- Facilitator → SVM Schemes: registers scheme
- Facilitator → TVM Schemes: supports scheme
- EVM Batch Settlement → EVM Channel Storage: persists channels (evidence: `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
