Architecture Overview

How Stellar x402 Gateway routes and settles payments

System Architecture

Stellar x402 Gateway acts as an intermediary layer between clients (users or AI agents) and backend API services.

+-------------------+           +-------------------+           +-------------------+
|                   |           |                   |           |                   |
|  AI Agent / User  | <-------> |  x402 Gateway     | <-------> |  Upstream API     |
|  Client           |           |  (Proxy / Member) |           |  (Protected)      |
|                   |           |                   |           |                   |
+-------------------+           +-------------------+           +-------------------+
          ^                               |
          | (Payment Signature)           | (Verify / Settle)
          v                               v
+-----------------------------------------------------------------------------------+
|                           Stellar Network (Soroban)                               |
|                                                                                   |
|   +---------------------------------------------------------------------------+   |
|   | settlement-verifier Smart Contract                                        |   |
|   | - Nonce Tracking (Replay Protection)                                      |   |
|   | - Atomic Revenue Splitting (Merchant Net + Protocol Fee)                  |   |
|   | - Ledger Timestamp Expiry Verification                                    |   |
|   +---------------------------------------------------------------------------+   |
+-----------------------------------------------------------------------------------+

Key Layers

1. Ingress Layer (Reverse Proxy / Middleware)

• Express & Fastify Middlewares: Node.js plugins that intercept unauthenticated HTTP requests, evaluate route pricing rules, inject HTTP 402 challenge headers, and attach decoded payment signatures to request contexts.
• Go Reverse Proxy Daemon: High-throughput Go reverse proxy that inspects incoming HTTP traffic, enforces rate limits, handles 402 challenges, and proxies valid requests to upstream APIs.

2. Core Protocol Primitives (@stellar-x402/core)

• Standardizes challenge formatting in the PAYMENT-REQUIRED and WWW-Authenticate headers.
• Parses base64-encoded Payment-Signature headers into typed data structures.
• Validates CAIP-2 network identifiers (stellar:pubnet, stellar:testnet, stellar:futurenet).

3. Settlement Contract (settlement-verifier)

• Written in Rust for Soroban runtime (wasm32v1-none).
• Enforces strict monotonic nonces (current_nonce + 1) per payer account.
• Splits token amounts between merchant recipients and protocol fee recipients in a single atomic transaction.
• Emits structured SettlementReceipt contract events for indexing and accounting.