X402 Stellar Context

x402-stellar Context

What This Is

An implementation of the x402 payment protocol for the Stellar network. The x402 protocol uses HTTP status code 402 (Payment Required) to enable machine-readable paywalls — a server responds with 402 + a PAYMENT-REQUIRED header, the client pays via blockchain, then retries the request with a PAYMENT-SIGNATURE header. The facilitator verifies and settles payments on-chain.

This repo provides:

• A Stellar facilitator that verifies and settles x402 payments on the Stellar blockchain
• A paywall server example using Express + the @x402/express middleware
• A React SPA client that renders a wallet-connect paywall UI when it receives a 402
• A paywall package that generates the HTML paywall page with Stellar wallet integration

How x402 Payment Flow Works

Client                    Server                  Facilitator         Stellar
  |                         |                         |                 |
  |-- GET /networks ------->|                         |                 |
  |<-- { networks: [...] } -|                         |                 |
  |                         |                         |                 |
  |-- GET /protected/:net ->|                         |                 |
  |<-- 402 + requirements --|                         |                 |
  |                         |                         |                 |
  | (user signs tx in wallet)                         |                 |
  |                         |                         |                 |
  |-- GET /protected/:net ->|                         |                 |
  | (PAYMENT-SIGNATURE hdr)|-- POST /verify -------->|                 |
  |                         |<-- { valid: true } -----|                 |
  |                         |                         |                 |
  |                         |-- POST /settle -------->|                 |
  |                         |                         |-- submit tx --->|
  |                         |<-- { success, txHash } -|                 |
  |<-- 200 + PAYMENT-RESPONSE + content -------------|                 |

1. Client fetches GET /networks to discover which networks are available (testnet, mainnet, or both)
2. Client requests a protected resource via GET /protected/testnet or GET /protected/mainnet
3. Server responds with 402 Payment Required + PAYMENT-REQUIRED header (base64 PaymentRequired payload: price, network, payTo address)
4. Client renders a paywall page where the user connects a Stellar wallet and signs a transaction
5. Client retries the request with the signed payment in the PAYMENT-SIGNATURE header
6. Server forwards the payment to the facilitator for verification
7. Facilitator checks the transaction is valid (correct amount, recipient, not expired)
8. Server serves the content; facilitator settles (submits) the transaction on-chain
9. Server returns content with PAYMENT-RESPONSE header (base64 SettlementResponse) and injects the transaction hash link via txHashInjector middleware

Header compatibility note

x402 v2 HTTP transport uses:

• PAYMENT-REQUIRED (server → client, 402 response)
• PAYMENT-SIGNATURE (client → server, retried request)
• PAYMENT-RESPONSE (server → client, settlement metadata)

The vendored @x402/* packages in this repo still include v1 fallbacks (X-PAYMENT, X-PAYMENT-RESPONSE) for backward compatibility, but v2 headers are the canonical protocol path.

Architecture

pnpm 10.7.0 monorepo with Turborepo. All own packages are scoped @x402-stellar/*.

Packages

Vendored Packages

4 pre-built @x402/* packages live under vendors/x402/typescript/packages/. They are a git submodule from the upstream coinbase/x402 repo, included as dist-only (never modify source, never rebuild).

Build Order

Turborepo resolves ^build dependencies. In practice: paywall builds first (esbuild + tsup), then server (imports paywall). Facilitator and client have no cross-dependencies and build in parallel.

Key Design Decisions

Paywall as bundled HTML: The paywall package pre-bundles the entire React wallet UI into an HTML string at build time. When the server returns a 402, it sends this HTML directly — no client-side JS bundle loading needed. The template.ts file (~2.25 MB, auto-generated) contains the base64-encoded bundle.

txHashInjector middleware: Registered before the @x402/express middleware. It wraps res.end/res.write to intercept the response body after payment settlement and replaces {{TX_LINK}} with a Stellar Expert transaction link. This lets the protected content reference its own payment transaction.

Facilitator is internal: In the Docker Compose setup, the facilitator is not exposed externally — it runs on an internal network. Facilitator routes (/verify, /settle, /supported) are NOT externally accessible — they are an internal service, not a public API.

Startup validation: Before creating the Express app, the server calls Env.validateFacilitators() which fetches GET /supported from every configured facilitator (with optional Authorization: Bearer header). If any facilitator is unreachable or returns a non-200 status, the server throws with aggregated diagnostics.

trust proxy via proxy-addr: Both server and facilitator use the proxy-addr package with TRUST_PROXY env var (defaulting to loopback,linklocal,uniquelocal) instead of Express's built-in string-based trust. This matches the pattern used in Stellar's laboratory-backend.

Repository Layout

x402-stellar/
├── packages/paywall/              # Paywall HTML builder
│   └── src/
│       ├── builder.ts             # PaywallBuilder class
│       ├── stellar-handler.ts     # Stellar wallet integration
│       ├── stellar.ts             # Re-export for paywall/stellar entry
│       ├── types.ts               # PaywallConfig, PaywallProvider types
│       └── browser/               # esbuild source for the wallet UI
│           └── build.ts           # Build script -> gen/template.ts
├── examples/
│   ├── facilitator/               # Stellar facilitator service
│   │   └── src/
│   │       ├── app.ts             # Express app: /verify, /settle, /supported, /health
│   │       ├── index.ts           # Entrypoint: listen + graceful shutdown
│   │       ├── config/env.ts      # Typed Env class (validates at startup)
│   │       └── utils/logger.ts    # Pino structured logging
│   └── simple-paywall/
│       ├── server/                # Paywall server
│       │   └── src/
│       │       ├── app.ts         # Express app: helmet, cors, trust proxy, error handler
│       │       ├── index.ts       # Entrypoint: listen + graceful shutdown
│       │       ├── config/env.ts  # Typed Env class
│       │       ├── middleware/
│       │       │   ├── payment.ts # Creates x402 paymentMiddleware
│       │       │   └── txHashInjector.ts  # Replaces {{TX_LINK}} in responses
│       │       ├── routes/
│       │       │   ├── health.ts  # GET /health
│       │       │   └── protected.ts  # GET /protected/:network (paywalled content)
│       │       └── utils/logger.ts
│       ├── client/                # React/Vite SPA
│       └── docker-compose.yml     # 3-container local setup
├── vendors/x402/                  # Git submodule (dist-only, never modify)
│   └── typescript/packages/{core,extensions,http/express,mechanisms/stellar}
├── Dockerfile                     # Multi-target: facilitator, server, client
├── Makefile                       # check = install + format + lint + typecheck + test + build
├── turbo.json                     # Task config with ^build dependency
├── pnpm-workspace.yaml            # Workspace globs
└── .env.example                   # Template for required env vars

Deployment Modes

Environment Variables

Minimum required for the system to function:

Per-network server variables use TESTNET_ or MAINNET_ prefixes: <NET>_SERVER_STELLAR_ADDRESS, <NET>_STELLAR_RPC_URL, <NET>_FACILITATOR_URL, <NET>_FACILITATOR_API_KEY. Provide at least one set to enable that network.

Client env variables are resolved as follows: VITE_SERVER_URL, VITE_APP_NAME, and VITE_PAYMENT_PRICE may be provided via runtime window.__CONFIG__ (Docker, injected by docker-entrypoint.sh) or via Vite build-time env, with hardcoded defaults as fallback. VITE_PORT configures the Vite dev server port at startup (default 5173) and is not read from window.__CONFIG__ at runtime in Docker.

Full reference in the root README.md and per-service .env.example files.

Test Coverage

101 tests across 6 files:

• examples/facilitator/tests/config/env.test.ts — 25 tests (Env class validation)
• examples/facilitator/tests/routes/facilitator.test.ts — 10 tests (route behavior)
• examples/simple-paywall/server/tests/config/env.test.ts — 41 tests (Env + dual-network config + address validation + validateFacilitators)
• examples/simple-paywall/server/tests/middleware/txHashInjector.test.ts — 10 tests
• examples/simple-paywall/server/tests/routes/protected.test.ts — 12 tests (health + networks + protected routes per network)
• examples/simple-paywall/server/tests/routes/protected-single-network.test.ts — 3 tests (single-network deployment behavior)

Run with pnpm test (Turborepo runs vitest in each package).