# PipRail

> Last-Updated: 2026-09-06 · SDK-Version: 2.16.2 · MCP-Version: 0.9.0 · Type: APIService · License: MIT · Repository: https://github.com/piprail/piprail

> Accept and make x402 "402 Payment Required" crypto payments from any HTTP request — across 29 chains in 10 families (every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & the XRP Ledger). No backend, no database, no account, no fee: payments settle straight to your wallet, verified locally against your own RPC. Built for AI agents. It also does x402 **discovery** — emit a machine-readable manifest, register your endpoint on the open indexes (402 Index, CDP Bazaar), and let agents find payable APIs to use — on every chain. And `@piprail/mcp` — an MCP (Model Context Protocol) server, listed in the official MCP registry (`io.github.piprail/mcp`), that lets any MCP client (Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Cline) pay, discover, and register x402 URLs autonomously, capped by a local spend policy the model cannot exceed.

PipRail is `@piprail/sdk`, an open-source (MIT) TypeScript SDK. Gate any route so it charges for itself, or point an agent at a paid URL and it pays itself. `requirePayment` is the Express one-liner; `createPaymentGate` is the framework-agnostic core for everything else (Next.js, Hono, Fastify, Workers, Bun, Deno); `PipRailClient` pays; `paymentTools` hands payment to a model with a spend budget.

Install: `npm install @piprail/sdk viem`. Take a payment in one line:
`requirePayment({ chain: 'base', token: 'USDC', amount: '0.05', payTo: '0xYourWallet' })`.
Full pitch + all code inline: [llms-full.txt](https://piprail.com/llms-full.txt).

## Docs

- [SDK guide](https://piprail.com/sdk): the on-site developer page — accept (`requirePayment` / `createPaymentGate`) and pay (`PipRailClient`), one-line multi-chain, the agent spend policy, `planPayment`, the four-step 402 loop, a backendless-vs-facilitator comparison, and a glossary. Funnels to the full README below.
- [SDK README](https://github.com/piprail/piprail/blob/main/sdk/README.md): full API — take & make payments, all 29 chains, per-family wallet formats, custom tokens, multi-chain accepts, spend policy, gas estimation, and `planPayment()` (affordability + recipient-readiness preflight).
- **planPayment (the agent unlock):** `client.planPayment(url)` is a read-only call that checks a 402 against your wallet's OWN holdings — token balance, native-coin gas, and whether the recipient can receive (trustline / ATA / storage_deposit / ASA opt-in / activation) — across every rail it offers on your chain. Returns `payable` + the best rail, per-rail `blockers` (INSUFFICIENT_TOKEN / INSUFFICIENT_GAS / RECIPIENT_NOT_READY / OUTSIDE_POLICY), and a one-line `fundingHint`. Completes the trio `quote()` (price) → `estimateCost()` (gas) → `planPayment()` (can I settle, and where). `canAfford(url)` is the boolean; `fetch(url, { autoRoute: true })` pays the cheapest settleable rail; `planAcross(clients, url)` plans across chains. Never throws for a read; returns null when not gated. Backendless + self-custodial: reads balances and receive-rules from your own RPC across all 29 chains, no facilitator/oracle.
- **Verifiable receipts (2.10):** `receipts: true` on a gate emits a self-contained, chain-grounded receipt anyone re-verifies against the chain with only an RPC — no key, no backend. `client.lastReceipt()` captures it; `PipRailClient.verifyReceipt(receipt)` re-reads the tx and re-derives payTo/asset/payer, ignoring the receipt's claims (never throws). Optional Tier-2 EIP-712 service-delivery attestation signed with the merchant's existing payTo wallet (`receipts: { attest }`); byte-compatible with the x402 offer-receipt extension.
- **The `upto` rail (2.10):** ratified x402 metered / variable-amount billing — the buyer signs a Permit2 authorization for a MAXIMUM, the merchant serves + meters, then self-settles the ACTUAL (≤ max) from its own relayer through the on-chain x402UptoPermit2Proxy. Backendless, no fee, EVM-Permit2 only. Meter inside the `settleAmount` callback on a direct `gate.verify()` call.
- **A2A transport (2.10):** `gate.verifyObject(payload)` makes any gate verify a raw-JSON payment object (not just a base64 HTTP header), and `createA2APaymentHandler(gate)` maps a gate onto Google's A2A JSON-RPC Task/Message metadata — sharing one replay set with HTTP. Backendless, zero @a2a dependency.
- [Concepts](https://github.com/piprail/piprail/blob/main/examples/CONCEPTS.md): the 402 loop, who owns what, which primitive to use when, replay protection, local verification.
- [Error codes](https://github.com/piprail/piprail/blob/main/sdk/ERRORS.md): the two-channel error model — thrown `PipRailError` codes and returned `VerifyErrorCode`s — and how to handle each.
- [Agent guidelines](https://github.com/piprail/piprail/blob/main/AGENTS.md): commands, project structure, API ground truth, and the Always/Ask-first/Never rules.

## MCP — @piprail/mcp

- `@piprail/mcp` wraps the SDK as an MCP server so any MCP client pays, discovers, and registers x402 URLs autonomously, budget-bound. Run: `npx -y @piprail/mcp` (speaks MCP over stdio). Local-only, zero custody — your key, your RPC, your limits. Listed in the official MCP registry as `io.github.piprail/mcp`.
- Eight tools: `piprail_discover` (find payable x402 endpoints on the open indexes), `piprail_quote_payment` (price a gated URL without paying), `piprail_plan_payment` (check balance + gas + recipient-readiness + policy across every rail, read-only), `piprail_pay_request` (fetch with payment on the cheapest affordable rail), `piprail_register` (list an x402 endpoint so other agents can find it), `piprail_budget` (read the remaining spend budget + time leash, read-only), `piprail_guide` (read the agent contract), and `piprail_verify_receipt` (re-verify a verifiable receipt against the chain — read-only, key-less; confirm a payment really settled without trusting the issuer). A failed pay returns a structured `{ ok:false, code, reason, explain, ref?, reasonCode? }` — never an uncaught crash.
- Two modes: Mode A (headless, default) — the agent runs free inside a budget AND time envelope (the policy is the consent, no per-pay prompt); Mode B (supervised, `PIPRAIL_CONFIRM=1`) — the human approves each payment via MCP elicitation, fail-safe to not-pay.
- Config is all env vars: `PIPRAIL_PRIVATE_KEY` (optional — omit it and the server boots read-only: discover/quote/plan/register/budget/guide still work, only paying needs a key), `PIPRAIL_CHAIN` (default base), `PIPRAIL_MAX_AMOUNT` (per-call cap, default 0.10), `PIPRAIL_MAX_TOTAL` (lifetime per-token cap, default 10.00), `PIPRAIL_TOKENS` (default USDC; USDT on Tron/TON), `PIPRAIL_TTL` (session deadline, seconds), `PIPRAIL_WINDOW_TOTAL`+`PIPRAIL_WINDOW_SECONDS` (rolling rate-limit), `PIPRAIL_MAX_TOTAL_DENOM` (cross-token GRAND TOTAL, e.g. `USD:20.00,EUR:5.00` — one cap across every stablecoin AND chain; not a price oracle), `PIPRAIL_MAX_PAYMENTS`/`PIPRAIL_MAX_PAYMENTS_PER_WINDOW` (payment-count caps), `PIPRAIL_SPEND_LOG` (durable budget — survives a restart), `PIPRAIL_EVENT_LOG` (one-line-JSON event sink to stderr/file), `PIPRAIL_WARN_AT_FRACTION` (early "approaching cap" warning), `PIPRAIL_CONFIRM` (Mode B), `PIPRAIL_HOSTS`, `PIPRAIL_RPC_URL`, `PIPRAIL_NEAR_ACCOUNT_ID`. Caps are enforced before any on-chain send and checked against the token's true decimals — the model cannot overspend.
- Works in Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, and Cline. EVM works out of the box; non-EVM chains pull their SDK peer on demand. One wallet per chain per instance.
- Page: [MCP setup guide](https://piprail.com/mcp) · npm: [@piprail/mcp](https://www.npmjs.com/package/@piprail/mcp) · registry: [io.github.piprail/mcp](https://registry.modelcontextprotocol.io) · [README](https://github.com/piprail/piprail/blob/main/mcp/README.md) — install, add one env block, and your agent pays, discovers, and registers x402 URLs on its own across 29 chains. A worked 60-second walkthrough (install → config → a sample agent paying a gated URL) and a cite-ready fact list live in [llms-full.txt](https://piprail.com/llms-full.txt).

## Discovery — get found, find others

- PipRail does x402 service **discovery** with no backend and no fee, on top of OPEN third-party indexes (PipRail hosts nothing). Four moves: **EMIT**, **REGISTER**, **VERIFY**, **DISCOVER** — every method returns a typed result that tells an agent what to do next.
- **EMIT** — turn your payment gate into a machine-readable manifest crawlers and agents can read: `gate.describe()` plus the pure emitters `buildOpenApi()` (OpenAPI 3.1 with an `x-payment-info` block per priced operation, stamped with an `x-generator` attribution by default), `buildWellKnownX402()` (a `/.well-known/x402` document), and `buildX402DnsTxt()` (a `_x402` DNS TXT record).
- **REGISTER** — `client.register(url)` lists your x402 endpoint on the open indexes. Default target **402 Index** (no auth, no signature, any chain); **x402scan** is an optional bonus (SIWX sign-in, Base/Solana only). Every outcome carries a `visibility` (`live`/`pending-review`/`not-listable`) + `note` so "ok" never means "searchable now": 402 Index returns `pending-review` (probed on submit, then searchable once it passes automated checks — no verification required; verify your domain for instant approval — see VERIFY); a listing on x402scan is `live` but `discover()` doesn't read x402scan. Attribution is **on by default** (opt out with `attribution: false`) — a `via: "@piprail/sdk"` field + a tasteful `· Built with @piprail/sdk` description suffix. Per-index facts: the exported `DIRECTORY_INFO` map.
- **VERIFY** — the instant, guaranteed go-live for a 402 Index listing: verify the domain you control with `client.claimDomain(url)` (returns a hash to serve at your `/.well-known/402index-verify.txt`), then `client.verifyDomain(url)` approves it — flipping every pending listing on the domain to searchable at once, with a verified badge. No funds, no sign-up.
- **DISCOVER** — `client.discover({ network })` returns payable x402 resources from the open indexes (CDP Bazaar + 402 Index) — **not x402scan** (its reads are paid), so a live x402scan listing won't appear here. Free, read-only. `network: 'self'` (default) filters to your chain; `'any'` searches all chains; or pass a CAIP-2 id.
- **Every chain:** EMIT is pure serialization, REGISTER's default (402 Index) has no chain limit, and DISCOVER keeps unresolved networks rather than hiding them — so discovery works on every chain PipRail supports, present and future. Only the optional x402scan target is Base/Solana-only.
- Page: [Discovery guide](https://piprail.com/discovery) · reference: [DISCOVERY.md](https://github.com/piprail/piprail/blob/main/sdk/DISCOVERY.md) (the three moves, a step-by-step walkthrough, exactly what you need at each step, and honest caveats). Status: discovery is experimental — the pay/accept core is the stable product.

## Examples

- [Live demo](https://piprail.com/demo): an interactive page that loads the SDK from a CDN and runs a real x402 `402` challenge + quote **in your browser**, across chains — no install, no backend. Proof the SDK runs client-side as well as server-side.
- [Examples overview](https://github.com/piprail/piprail/blob/main/examples/README.md): runnable merchant + agent demos (Express, Next.js App Router, an auto-paying agent with a spend policy, an MCP server, and a no-build **browser/CDN** HTML page) — pick the folder for your task and navigate from there.

## Integrations

- PipRail drops into agent frameworks by wrapping the published @piprail/mcp server — no new code, just one config entry. Five are live and tested: **OpenClaw** (a ClawHub skill — `clawhub install piprail`), **Hermes** (NousResearch's agent runtime — one `mcp_servers` block in `~/.hermes/config.yaml`), **elizaOS** (a native plugin, `@piprail/elizaos-plugin`, wrapping `paymentTools()` as 6 budget-bound actions), **n8n** (a native community node, `@piprail/n8n-nodes-piprail`, `usableAsTool` so AI Agent nodes can call it), and **Mastra** (the first x402 integration for Mastra, wiring `@piprail/mcp` in via `MCPClient`). Each gives the agent the 8 piprail_* tools, budget-bound. Vercel AI SDK is planned. Any MCP client can use PipRail today without a dedicated integration. See https://docs.piprail.com/integrations/

## Scaffolding — @piprail/create

- `npm create @piprail` scaffolds a complete, runnable, **mainnet-by-default** x402 merchant in one command — the seller's mirror of the buyer's `npx -y @piprail/mcp`. An interactive wizard asks what you're selling, which chain + token, and your **public** wallet address (no private key, no account, no backend, no fee), then generates the app: a `createPaywall`/`createTipJar` gate, a `npm run verify` config self-test, and either a node/express server or a Cloudflare Worker. Published as [@piprail/create](https://www.npmjs.com/package/@piprail/create).

## Chains

- [Chains catalog](https://piprail.com/chains): the full on-site list — every supported chain with its tokens, grouped by family, plus the handful of one-time setup caveats, each chain deep-linkable by anchor (e.g. `/chains#solana`).
- 29 chains, 10 families: 20 EVM mainnets + Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar, and the XRP Ledger. USDC almost everywhere, USDT on most, EURC on Ethereum, Base, Avalanche & Stellar, RLUSD on XRPL — or any token by address. One `chain` parameter picks everything. Covered in the [SDK README](https://github.com/piprail/piprail/blob/main/sdk/README.md).
- [Per-chain setup & caveats](https://github.com/piprail/piprail/blob/main/sdk/CHAINS.md): what each chain needs before it can pay or receive. Most need nothing. Native coin is a valid payment asset on every chain — all ten families, no exceptions (Tron's native TRX included, digest-bound). On NEAR, native is the zero-setup path while the NEP-141 token path needs a one-time `storage_deposit`; Stellar & XRPL need a one-time trustline + funded/activated account; and TON needs an API-keyed `rpcUrl` (free toncenter key in the URL). On Algorand, receiving USDC needs a one-time ASA opt-in (native ALGO is zero-setup).

## Writing — the PipRail blog

- [Blog](https://piprail.com/blog): essays from the PipRail team on x402, agent payments, and the trust layer the agent economy still has to build. First essay coming soon.

## Links

- [Website](https://piprail.com)
- [Blog](https://piprail.com/blog) — essays on x402, agent payments & the agent-economy trust layer
- [SDK guide](https://piprail.com/sdk) — accept & make x402 payments in code
- [MCP setup guide](https://piprail.com/mcp) — give any agent a budget-bound wallet
- [Discovery guide](https://piprail.com/discovery) — emit, register & find x402 endpoints
- [Chains catalog](https://piprail.com/chains) — every supported chain + per-chain setup
- [Live demo](https://piprail.com/demo) — try x402 in your browser, no install
- [npm: @piprail/sdk](https://www.npmjs.com/package/@piprail/sdk)
- [npm: @piprail/mcp](https://www.npmjs.com/package/@piprail/mcp) — MCP server for budget-bound agent payments
- [MCP registry: io.github.piprail/mcp](https://registry.modelcontextprotocol.io) — the official MCP server listing
- [GitHub](https://github.com/piprail/piprail)