Architecture
Overview
x402 RPC Proxy is designed as a modular, multi-layered system that separates authentication, payments, routing, and execution.
It acts as an intermediary layer between clients and blockchain nodes, enforcing access control, payment validation, and request metering before forwarding requests.
High-Level Architecture
The system consists of four primary layers:
┌─────────────────────────────────────────────┐
│ Client Layer │
│ Apps · Backends · AI Agents · Wallets │
└─────────────────────┬───────────────────────┘
│ JSON-RPC 2.0 / REST
┌─────────────────────▼───────────────────────┐
│ Gateway Layer (x402) │
│ Auth · Credit Check · Routing · Metering │
└──────┬────────────────────────┬─────────────┘
│ │
┌──────▼──────┐ ┌────────▼────────────┐
│ Payment & │ │ RPC Provider │
│ Credit │ │ Layer │
│ Layer │ │ EVM · Cosmos · │
│ │ │ Solana (planned) │
└─────────────┘ └─────────────────────┘Request Lifecycle
Every RPC request follows a deterministic flow:
- Client sends request to
/mcp - Gateway authenticates the request (JWT)
- Credits are checked
- If insufficient → return
402 Payment Required - If sufficient → deduct credits
- Route request to appropriate RPC provider
- Return response to client
This ensures strict enforcement of payment before execution.
Core Components
API Gateway
The gateway is the central entry point:
- Exposes a single endpoint:
/mcp - Implements JSON-RPC 2.0
- Handles request validation and routing
- Acts as the enforcement layer for auth and credits
Authentication Layer
Responsible for identity and session management:
| Feature | Detail |
|---|---|
| Supported standards | SIWE (Ethereum), SIWC (Cosmos), SIWS (Solana — upcoming) |
| Token type | JWT (short-lived access + refresh token pair) |
| Session state | Refresh tokens, expiry tracking, revocation support |
Payment & Credit Layer
Handles economic enforcement:
| Step | Action |
|---|---|
| 1 | Pricing plans defined by the platform |
| 2 | Consumer makes on-chain payment |
| 3 | Gateway verifies payment on-chain |
| 4 | Credits issued to consumer wallet |
| 5 | Credits deducted atomically before each request |
Routing Layer
Responsible for selecting RPC endpoints:
- Supports multiple providers per chain
- Handles load distribution, failover, and endpoint selection
- Abstracts underlying RPC infrastructure from the client
Execution Layer
Handles actual RPC forwarding:
| Protocol | Transport |
|---|---|
| JSON-RPC | Standard EVM and Cosmos RPC |
| REST | Cosmos LCD / REST APIs |
| gRPC | High-performance binary |
| WebSocket | Streaming and subscriptions |
Data Flows
Authentication Flow
Client Gateway
│ │
│── GET /auth/nonce ───────▶│
│◀─ { nonce } ─────────────│
│ │
│ [sign message in wallet]│
│ │
│── POST /auth/login ──────▶│
│ { address, sig, msg } │── verify signature
│ │── issue JWT
│◀─ { token, refresh } ────│Payment Flow
Client Gateway Chain
│ │ │
│── GET /pricing ──────────▶│ │
│◀─ { plans } ─────────────│ │
│ │ │
│── POST /payments/initiate▶│ │
│◀─ { recipient, amount } ─│ │
│ │ │
│── [on-chain transfer] ───────────────────────────▶│
│ │ │
│── POST /payments/confirm ▶│── verify tx ─────────▶│
│ │◀─ confirmed ──────────│
│◀─ { credits_issued } ────│ │Execution Flow
Client Gateway Provider
│ │ │
│── POST /mcp ─────────────▶│ │
│ { jsonrpc, method } │── check JWT │
│ │── check credits │
│ │── deduct credits │
│ │── route request ───▶│
│ │◀─ rpc response ─────│
│◀─ { jsonrpc, result } ───│ │Multi-Chain Support
x402 is designed to support multiple ecosystems:
| Ecosystem | Auth | Status |
|---|---|---|
| EVM-based chains | SIWE | Available |
| Cosmos-based chains | SIWC | Available |
| Solana | SIWS | Planned |
Each chain can have:
- Multiple providers
- Independent pricing models
- Different transport protocols
Scalability Considerations
The system is designed for horizontal scalability:
| Component | Scaling Strategy |
|---|---|
| Gateway | Stateless — scale horizontally |
| Payment Processor | Independent service, scalable separately |
| RPC Providers | Multiple providers per chain; auto-routing |
| Session Store | Distributed token validation |
Reliability & Failover
| Mechanism | Description |
|---|---|
| Multi-provider routing | Multiple RPC endpoints registered per chain |
| Automatic failover | Reroutes on provider failure |
| Retry policies | Configurable per-provider retry behavior |
| Health monitoring | Provider health checks (planned) |
Security Model
| Layer | Mechanism |
|---|---|
| Identity | Wallet signature — no passwords or shared secrets |
| Session | Short-lived JWT; single-use refresh tokens |
| Authorization | Request-level credit check before execution |
| Payment integrity | On-chain verification — not self-reported |
| Abuse prevention | Credit exhaustion causes hard stop |
Design Principles
| Principle | Description |
|---|---|
| Separation of concerns | Auth, payments, routing, and execution are independent layers |
| Deterministic execution | Payment enforced before request — no exceptions |
| Extensibility | New chains and payment networks can be integrated |
| Interoperability | Unified interface across all supported ecosystems |
| Minimal trust | Verifiable payments and auditable usage at every step |