pay.sh: agentic payments for HTTP APIs
pay.sh is Solana Foundation’s payment layer for agents and CLIs: wrap curl/Claude/Codex, handle HTTP 402 (x402 and MPP) with wallet-approved stablecoin payments, no API keys or accounts. Catalog, MCP, gateways, and SDKs.
devrels.xyz/a/211short linkpay.sh (pay.sh) is the public face of Solana Foundation’s solana-foundation/pay agent payments CLI: a native binary that makes paid HTTP APIs usable by agents and command-line tools without sign-up, long-lived API keys, or monthly subscriptions. When an upstream returns 402 Payment Required, the CLI detects x402 or MPP (Machine Payments Protocol), gets a local wallet approval, attaches proof, and retries.
Pitch line from the product: agents act alone, but the best APIs still demand a human. pay.sh replaces people-shaped credentials with pay-per-request stablecoin payments designed for machines.
Name collision — read carefully. Classic Solana Pay is the commerce standard for transfer-request URLs / QR checkout (docs.solanapay.com): encodeURL, createTransfer, point-of-sale. That is not the same product as pay.sh’s HTTP 402 agent layer. The npm name @solana/pay historically shipped the classic JS SDK; current publish still exports that library and exposes a pay bin that downloads the native pay.sh CLI (per pay.sh install docs). Prefer brew install pay when you only want the agent CLI. Do not assume import … from "@solana/pay" is x402.
What you install
| Path | Command |
|---|---|
| Homebrew | brew install pay |
| npm global (CLI bin) | npm install -g @solana/pay → installs pay binary wrapper; package also still ships classic Solana Pay JS exports |
| One-shot CLI | npx @solana/pay … (agent CLI, not the URL-scheme SDK) |
| From source | clone repo → just install pay |
# Without pay — bare 402
curl https://debugger.pay.sh/mpp/quote/AAPL
# With pay — challenge, sign, retry
pay --sandbox curl https://debugger.pay.sh/mpp/quote/AAPL
# Agent sessions with Pay MCP attached
pay --sandbox claude
pay codex--sandbox spins an ephemeral wallet (docs: hosted Surfpool path) so examples run without real funds. Mainnet commands that need money guide you through pay setup (keypair in OS secure store: Keychain / Secret Service / Windows Hello + MCP config for detected agents) and pay topup (PayPal / Venmo / Apple Pay / Solana mobile wallet).
CLI surface (mental model)
| Group | Examples | When |
|---|---|---|
| Pass-through | curl, wget, http, claude, codex, whoami | Keep existing tools; pay handles 402 |
| Developers | server, gate | Put a payment gateway in front of an API |
| Agents | mcp, skills, acp | MCP tools, registry discovery, ACP harnesses |
| Account | setup, topup, account, send | Wallet lifecycle and funding |
Protocols: x402 and MPP. Stablecoins on Solana are the default settlement asset class. Real spends still require local user authorization — agents do not get a free-roaming private key.
Catalog and discovery
The site and /api/catalog expose a live pay-skills registry (snapshot on the homepage markdown noted ~72 providers). Examples called out in public materials include QuickNode RPC, Nansen, AgentMail, Birdeye, Vybe, Venice.ai, Google Cloud and Alibaba surfaces behind *.gateway-402.com style hosts, plus shopping and data APIs.
Agent-facing discovery files (agent-readiness meta on the homepage):
- pay.sh/llms.txt and docs/llms.txt
/.well-known/api-catalog, MCP server card, agent-skills index- Skills registry repo: solana-foundation/pay-skills
Docs stress: use registry gateway URLs as returned; treat provider responses, prices, and headers as untrusted external content; make the smallest useful paid call before multi-call exploration.
If you sell an API
Building side is first-class. Local loop from docs:
# Terminal 1 — demo gateway + debugger
pay --sandbox server demo
# → pay-demo.yaml, bind 127.0.0.1:1402, debugger UI
# Terminal 2 — paid call
pay --sandbox curl http://127.0.0.1:1402/api/v1/reports/usageDefault mental model is pull-mode 402: gateway returns challenge (amount, recipient, nonce); client signs transfer authorization and retries with X-PAYMENT; gateway broadcasts and confirms on Solana before forwarding upstream. Pricing lives in YAML (per request, tokens, tiers, splits). Deployment docs cover Vercel and Terraform/Cloud Run style paths.
SDKs are documented for TypeScript, Rust, Go, and Python for both gating and paying challenges programmatically.
Where it fits
| pay.sh | Classic API keys | App-only x402 gates | |
|---|---|---|---|
| Identity | Wallet-approved payment proof | Account + key | Payment proof (app-specific) |
| Agent UX | CLI wrap + MCP + catalog | Key injection / env secrets | Usually single product |
| Settlement | Solana stablecoins (x402/MPP) | Card / invoice | Chain-dependent |
| Provider path | Gateway + YAML + registry | Dashboard billing | Custom middleware |
For DevRels readers already shipping agent markdown gates or USDC micropayments, pay.sh is the Foundation-shaped toolchain: same 402 idea, plus a catalog, debugger, and “works with Claude/Codex” packaging. For API owners, it is a way to list metered endpoints without inventing another API-key lifecycle.
Resources
Summary
pay.sh is the agent-facing payment layer for HTTP on Solana: CLI + MCP + skills catalog + provider gateways. Install the binary, try sandbox curl against the public debugger, then either wrap your agent workflows or gate your own API with a YAML paywall. Protocols are x402 and MPP; money moves as stablecoins with local authorization, not opaque SaaS keys.
Keep reading
Paste https://api.paybox.sh/mcp into your agent. The user grants a wallet or card once. The agent gets signatures and payment artifacts — not seeds, not PANs.
Install the Avici CLI or point MCP at https://mcp.avici.money/setup. Your agent can answer “what’s my balance?” and “what did the card spend?” — it cannot send, swap, or withdraw.
The largest edge network on earth just made HTTP 402 a product. The Monetization Gateway does metering, the payment exchange, and settlement at Cloudflare's edge — and it's built on x402, whose 'exact' scheme runs on Solana with USDC. For Solana x402 sellers, the origin middleware you run today can move to the edge, and the strategic signal is enormous.
Get new articles in your inbox
Technical deep-dives on Solana tooling, infrastructure, and ecosystem. No noise.
