██████╗  █████╗ ██╗██╗     ██╗  ██╗ ██████╗ ██████╗
██╔══██╗██╔══██╗██║██║     ██║  ██║██╔═████╗╚════██╗
██████╔╝███████║██║██║     ███████║██║██╔██║ █████╔╝
██╔══██╗██╔══██║██║██║     ╚════██║████╔╝██║██╔═══╝
██║  ██║██║  ██║██║███████╗     ██║╚██████╔╝███████╗
╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝     ╚═╝ ╚═════╝ ╚══════╝

Rail402 is a programmable API marketplace for autonomous agents on Base. It treats HTTP endpoints as first-class economic objects: discoverable by machine, callable without credentials, and settled onchain in USDC via the x402 protocol.

The core idea is simple: the payment is the authentication. Instead of issuing API keys, provisioning subscription tiers, and operating billing infrastructure, a provider returns a standard 402 Payment Required. The agent pays. The proof is verified onchain. The data is returned. No session state, no credential rotation, no approval loop.

That property is what makes it composable with agent runtimes, MCP servers, and multi-agent pipelines — settings where per-call economic settlement is the only access-control model that actually scales to software acting on its own behalf.

Make an endpoint payable — wrap any handler, deploy, and list it:

npm install @rail402/x402 viem

Call a paid API as an agent — discovery and payment are one round trip:

npx -y @rail402/mcp@latest     # expose the marketplace to Claude, Codex, Antigravity, and more

Jump to Provider Integration or Agent Integration below.

Rail402 implements the x402 flow on top of standard HTTP semantics.

Agent                          Rail402 Gateway                 Provider Endpoint
  │                                   │                               │
  ├─── POST /api/services/{id}/call ─▶│                               │
  │                                   ├── validate input schema       │
  │◀── 402 Payment Required ──────────┤                               │
  │    X-Payment-Address: 0x…         │                               │
  │    X-Payment-Amount:  0.05        │                               │
  │    X-Payment-Network: base        │                               │
  │    X-Payment-Currency: USDC       │                               │
  │                                   │                               │
  ├── submit USDC transfer on Base ───────────── ~2s finality ────────┤
  │                                   │                               │
  ├─── POST /api/services/{id}/call ─▶│                               │
  │    X-Payment-Proof: {txHash}      ├── verify transfer onchain      │
  │                                   ├── reject replayed txHash       │
  │                                   ├── forward request ───────────▶│
  │◀── 200 OK + payload ──────────────┤◀──── provider response ────────┤
  │                                   │                               │

• Stateless verification — the transaction hash is the credential; proof validation needs no session lookup.
• Atomic settlement — payment and delivery are causally linked. No payment, no data.
• Replay protection — each txHash is indexed per service; reused proofs are rejected at the gateway.
• Schema-enforced inputs — request bodies are validated against the service's JSON Schema before reaching the provider; malformed input never touches provider infrastructure.
• Direct settlement — Rail402 takes no custody. USDC routes straight to the provider's registered wallet on every verified call.

The full normative flow — PaymentRequirements/PaymentProof objects, verification rules, and header semantics — is specified in agent-services-spec.

Rail402 publishes a machine-readable registry at three canonical endpoints:

Each service is self-describing — an agent can select, price-check, and invoke it in a single discovery pass:

{
  "id": "cmpjq32i80002qaimfb2fezm4",
  "slug": "wallet-risk",
  "name": "Wallet Risk Score API",
  "capabilities": ["risk", "wallet", "security"],
  "price": { "amount": "0.05", "currency": "USDC" },
  "network": "base",
  "endpoint": "https://www.rail402.app/api/services/{id}/call",
  "inputSchema":  { /* JSON Schema */ },
  "outputSchema": { /* JSON Schema */ },
  "reliability": {
    "verified": true,
    "successRate": 99.5,
    "averageLatencyMs": 132,
    "totalCalls": 2057
  },
  "playgroundUrl": "https://rail402.app/playground/wallet-risk"
}

The discovery document format is a published standard — validate your own with npx @rail402/validate-spec ./agent-services.json.

Wrap an existing handler — the middleware handles the 402 challenge, onchain verification, and replay protection. Your business logic only runs after payment is confirmed.

Express / Node.js

import { withX402 } from "@rail402/x402";

app.post(
  "/your-api",
  withX402(
    async (req, res) => {
      // payment already verified; req.x402.payerWallet is available
      res.json(await yourBusinessLogic(req.body));
    },
    { price: "0.05", wallet: process.env.PROVIDER_WALLET, network: "base" },
  ),
);

FastAPI / Python

from rail402_x402 import X402Middleware

app.add_middleware(
    X402Middleware,
    price="0.05",
    wallet=os.environ["PROVIDER_WALLET"],
    network="base",
    protected_paths=["/your-api"],
)

@app.post("/your-api")
async def handler(body: YourInputModel, request: Request):
    # request.state.x402 holds the verified payment
    return await your_business_logic(body)

A Next.js App Router adapter (withX402Payment) ships in the same package. Once deployed, publish at rail402.app/publish with your inputSchema, outputSchema, and endpoint URL — the registry updates in real time and USDC settles directly to your wallet.

Direct HTTP — settle the 402 and retry in one call. fetchWithPayment takes a viem wallet and does the rest:

import { fetchWithPayment } from "@rail402/x402";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const wallet = createWalletClient({
  account: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`),
  chain: base,
  transport: http(),
});

const res = await fetchWithPayment(
  "https://www.rail402.app/api/services/{id}/call",
  { method: "POST", body: JSON.stringify({ input: { address: "0x…" } }) },
  wallet,
);
const data = await res.json();

Prefer a higher-level client with discovery helpers? Rail402/examples ships a reusable Rail402Client (discover(), getService(), call()) used by all four reference agents.

MCP — give Claude, Codex, Antigravity, or any MCP-compatible runtime the marketplace as tools:

{
  "mcpServers": {
    "rail402": {
      "command": "npx",
      "args": ["-y", "@rail402/mcp@latest"],
      "env": {
        "RAIL402_API_BASE": "https://www.rail402.app",
        "RAIL402_NETWORK": "base",
        "RAIL402_PRIVATE_KEY": "0xYourBaseWalletKey"
      }
    }
  }
}

RAIL402_PRIVATE_KEY is required only for paid call_service; discovery tools work read-only without it.

Rail402 sits at the intersection of three Base-native primitives.

x402 — Machine-native payments · implemented HTTP-layer payment protocol for autonomous systems. Payment requirements are encoded directly in the 402 response, so any HTTP client can implement the flow with no SDK on the consumer side.

ERC-8021 — Builder attribution · on the roadmap Provider wallets already receive settlement directly per call. Builder Code attribution will make that revenue composable across multi-agent pipelines, crediting the originating provider through a chain of delegated calls.

ERC-8004 — Agent identity · on the roadmap An onchain registry for agent reputation and capabilities. Rail402 is designed to key differential pricing and access policies to an agent's ERC-8004 reputation, letting providers reward trusted callers.

Responsible disclosure → contact@rail402.app

Rail402 operates on Base mainnet. Payment proofs are verified against the canonical USDC contracts below; proofs referencing any other network or token are rejected.

The SDKs, spec, and examples are open source and welcome contributions. Good entry points:

• Build a provider — ship a paid API from provider-starter.
• Extend the spec — propose changes against agent-services-spec.
• List your work — add APIs, SDKs, or agents to awesome-rail402.

Each repo documents its own setup, tests, and contribution guidelines.

Built on Base · Settled in USDC · Powered by x402