solana/pay: the missing payment layer for HTTP and AI agents

HTTP has had a 402 Payment Required status code since 1991. For three decades it went unused — no settlement layer existed that made per-request micropayments viable. Solana's 400ms finality and sub-cent fees changed that. The Solana Foundation's pay is the tooling that makes it practical: a CLI that intercepts 402s, handles the payment challenge, and retries with proof — transparently, without changing the API or the caller.

The repo description is precise: "Let your agents pay for any API." The agent never holds your private key. It never sees the signing credential. It just gets the response it asked for, and you get a Touch ID prompt before any money moves.

Two protocols, one CLI

pay supports both live payment standards on Solana:

• x402 — the Coinbase-originated protocol where the server returns a 402 with a JSON payment payload in theX-PAYMENT-RESPONSE header. The client attaches a signed payment as X-PAYMENT and retries. Single-shot: one request, one payment.
• MPP (Machine Payments Protocol) — the IETF-adjacent spec designed for streaming and session-based billing. The server issues a WWW-Authenticate: MPP challenge. The client opens a payment channel, sends vouchers for each request, and commits the channel at the end. Cheaper for many requests against the same endpoint.

pay detects which protocol the server speaks from the response headers and handles the correct flow automatically. You don't need to know which one an API uses.

# Without pay — you get a 402
curl https://debugger.pay.sh/mpp/quote/AAPL

# With pay — it handles the 402 and returns the data
pay curl https://debugger.pay.sh/mpp/quote/AAPL

The challenge-response flow

When pay curl gets a 402:

1. Parse the WWW-Authenticate or response body to extract the challenge — stablecoin, amount, destination, network.
2. Load the local account for that network (mainnet or sandbox devnet).
3. Prepare the transaction but do not sign it — present a biometric prompt instead (Touch ID on macOS, Windows Hello on Windows, GNOME Keyring on Linux).
4. If approved, sign with the key from the platform keychain and retry the original request with the payment proof attached.
5. Return the response to stdout as if no 402 ever happened.

The agent (or human) running the command never touches the key material. The key stays in the OS keychain. Rejection at step 3 means the payment is not signed and the request does not go through.

Installation and setup

# macOS
brew install pay

# npm (cross-platform)
npm install -g @solana/pay

# From source
git clone https://github.com/solana-foundation/pay.git
cd pay && just install pay

# Setup — creates a wallet, stores key in OS keychain
pay setup
pay whoami

# Fund with USDC for mainnet use
pay topup

AI-native: wrapping Claude Code and Codex

pay ships a built-in MCP server. When you run pay claude or pay codex, it injects itself into the agent session so every outbound HTTP request the agent makes is routed through the payment proxy. The agent gains access to paid APIs — Perplexity, stock data feeds, premium RPC endpoints — without any credential management in the prompt or tool configuration.

# Launch Claude Code with pay injected
pay claude

# Or add to claude_desktop_config.json for persistent access
# {
#   "mcpServers": {
#     "pay": { "command": "pay", "args": ["mcp"] }
#   }
# }

# Once inside the session the agent can run paid calls naturally
pay skills search "stock quotes"
pay skills endpoints perplexity
pay curl https://api.perplexity.ai/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"sonar","messages":[{"role":"user","content":"SOL price"}]}'

The skills catalog

pay has an open-source catalog of pay-compatible API providers in the pay-skills repo. Each entry defines endpoints, pricing, and agent-readable usage notes. The CLI can search, browse, and install provider sources locally.

pay skills search "maps"           # find providers by keyword
pay skills endpoints perplexity    # list all endpoints + prices
pay skills list                    # show installed provider sources
pay skills update                  # refresh local cache

# Add a custom or pinned provider source
pay skills add https://github.com/my-org/my-api-skills

Running a payment gateway for your own API

pay isn't just a client — it can turn any OpenAPI spec into a monetised endpoint in one command:

# Start a pay-aware gateway from your OpenAPI spec
pay server start --debugger spec.yml

# Or spin up the bundled sandbox demo
pay server demo

The --debugger flag starts the embedded Payment Debugger — a local web UI that renders every 402 challenge-response cycle as a sequence diagram. You can see exactly which headers were exchanged, which protocol was detected, and where a flow failed. A public instance is available for testing without running it locally.

PR #389: devex improvements (session 2)

The latest merged PR from lgalabru ships 27 files of developer experience improvements across the CLI and the Payment Debugger. The main areas:

• Debugger session view — a new SessionChannel component visualises the MPP channel lifecycle as a flow diagram, with colour-coded ribbons showing how payments split across recipients and capacity utilisation. The ReceiptLink component links each completed payment to its on-chain transaction.
• Skills provider management — the pay skills sub-commands gain a provider group with prune-merged (drop pinned providers whose upstream PRs have merged) and a boxed display mode for better terminal formatting. show and search get richer output.
• Account and send UX — pay account list and pay account new get cleaner output; pay send gains --confidential (Token-2022 Confidential Transfer extension — amount hidden on-chain) and --fee-within (deduct fee from amount rather than adding on top, implied for max sends).
• Server auth improvements — session authenticate handling in pay server updated for cleaner channel-open / voucher / commit / close lifecycle.

# Confidential transfer — amount hidden on-chain via Token-2022 CT extension
pay send 50 <recipient> --confidential

# Send entire balance (fee deducted from amount automatically)
pay send max <recipient>

# Browse improved skills output
pay skills show perplexity

MPP sessions: cheaper for high-frequency agent calls

x402 costs one on-chain transaction per API call. For an agent making ten calls in a session, that's ten transactions. MPP payment channels amortise that: you open a channel with a deposit, sign off-chain vouchers for each request, and settle on-chain once at the end. For an agent making 50 calls against one endpoint, the cost difference is roughly 50× in transaction fees.

# MPP session visualised in the debugger
# open → [voucher × N] → commit
#
# Channel state at each step is now visible in the SessionChannel
# component — capacity bars, recipient splits, running total

pay server demo   # start local sandbox + debugger
# navigate to http://localhost:4000 to see live session flows

Ecosystem

The protocols are open. You don't need the pay CLI to accept payments — any server that returns a properly formatted 402 with x402 or MPP headers will work with any compliant client. Projects building on this infrastructure include pointifsol.com and the growing pay-skills catalog. The public debugger at debugger.pay.sh lets you test any 402-compatible endpoint without a local setup.

The full docs are at docs.solanapay.com. The repo is MIT-licensed and contributions to the skills catalog are open.