> ## Documentation Index
> Fetch the complete documentation index at: https://x402-stellar.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.