Introduction

Turn any HTTP API into a pay-per-call service settled on Stellar

What is Stellar x402 Gateway?

Stellar x402 Gateway is an open-source payment infrastructure suite that implements the HTTP 402 Payment Required standard for the Stellar blockchain.

x402-stellar is an API infrastructure suite. It is neither solely a web app nor solely a CLI tool, but rather a set of developer building blocks:

• A Soroban Smart Contract (gateway-contract): Runs on the Stellar blockchain to verify cryptographic payment proofs, prevent replays, and split revenue between merchants and the protocol.
• Middleware SDKs (@stellar-x402/express, @stellar-x402/fastify, @stellar-x402/client, @stellar-x402/facilitator, @stellar-x402/streaming): Code libraries that backend developers import directly into their Node.js or TypeScript APIs to paywall routes, meter token streams, or sponsor gas fees with a single line of code.
• A Standalone Reverse Proxy Daemon (proxy/ in Go): A lightweight CLI daemon and binary (similar to Nginx or Envoy) that runs in front of backends written in any language (Python FastAPI, Go, Rust, Java). It intercepts incoming HTTP traffic, returns HTTP 402 challenges when unpaid, and forwards paid requests to the upstream server.
• A Merchant Web Dashboard (apps/web in Next.js 15): A browser-based management interface where API providers monitor revenue, inspect settled transactions on Stellar, and configure route pricing.

It allows developers and organizations to put cryptographic micropayment paywalls in front of HTTP APIs. When an unauthenticated client or autonomous AI agent calls a protected endpoint, the gateway responds with an HTTP 402 status code and a challenge specifying the token, price, network, and recipient. Once the client returns a signed authorization in the payment-signature header, the request is verified and forwarded to the backend API.

---

The Problem It Solves

Traditional API monetization relies on credit cards, monthly subscriptions, API key quotas, and invoice cycles. This model fails in three critical scenarios:

1. Autonomous AI Agents: AI agents cannot open bank accounts, solve CAPTCHAs, or negotiate enterprise billing contracts. They need machine-to-machine, per-request payments settled directly in digital dollars (USDC).
2. Micro-transaction Friction: Credit card processing incurs a 2.9% + $0.30 fixed fee per transaction. This makes it economically impossible to sell an API call for$0.005 or $0.01.
3. Complex Integration Overhead: Building on-chain billing from scratch requires writing custom smart contracts, managing nonces, parsing XDRs, and handling replay protection.

---

How x402 Solves It

• Sub-Cent Economics: Built on Stellar, where transaction fees are fractions of a cent ($0.00001) and ledger closes occur in 3 to 5 seconds.
• Zero Backend Overhaul: Middleware for Express and Fastify, plus a standalone Go reverse proxy that runs in front of Python, Go, Rust, or Ruby APIs without changing existing application code.
• On-Chain Cryptographic Settlement: Powered by a Soroban smart contract that enforces monotonic replay protection, verifies signatures, and distributes protocol and merchant fees in a single atomic transaction.
• Client Auto-Payer SDK: A lightweight client library that intercepts 402 challenges, checks caller-defined budget caps, signs payments, and retries requests automatically.

---

Core Repositories & Packages

x402-stellar
|
|-- gateway-contract            # Soroban settlement verifier contract (Rust 1.92.0)
|-- gateway-app                 # Monorepo containing:
    |-- @stellar-x402/core      # Challenge parsers, multi-primitive signatures, schemas
    |-- @stellar-x402/express   # Express middleware
    |-- @stellar-x402/fastify   # Fastify plugin
    |-- @stellar-x402/facilitator # Gasless fee-sponsor relayer and sequencer
    |-- @stellar-x402/streaming # SSE paywall and token meter for AI streams
    |-- @stellar-x402/client    # Auto-paying client SDK with budget policies
    |-- proxy/                  # Standalone Go reverse proxy daemon
    |-- apps/web/               # Next.js 15 merchant portal
|-- docs                        # Official Mintlify documentation source