Solana Pay CLI for Agentic HTTP Payments

Pay's HTTP 402 payment flow

Pay addresses a specific gap in HTTP-based agent tooling: a paid API can return a 402 response, while the calling agent has no built-in way to inspect the challenge, prepare a stablecoin transaction, obtain a signature, and retry the request. The README describes Pay as a wrapper around commands such as `curl`, `claude`, and `codex`. When the wrapped request receives a 402 response, Pay detects the payment protocol, prepares the transaction, asks the local wallet to authorize and sign it, and retries the request with payment proof.

The documented payment standards are MPP, the Machine Payments Protocol, and x402. The README says that stablecoins deployed to Solana are supported out of the box. That scope matters. Pay is not presented as a general card, bank transfer, or multi-chain payment interface. It is designed around HTTP payment challenges and Solana transaction signing.

The data flow is local until the wrapped command is retried. The client receives the server challenge, Pay translates it into a payment request, the wallet applies its authorization step, and Pay attaches the resulting proof to the retry. If the wallet prompt is rejected, the README states that the payment is not signed and the request does not go through. This makes authorization an explicit part of the request path rather than an ambient API-wide credential.

Agent sessions through MCP and ACP

Pay includes two interfaces for agent use. Its built-in MCP server lets an AI assistant request paid API calls through the same local wallet-approval flow. The README shows Pay injecting itself into Claude Code or Codex sessions with `pay claude` and `pay codex`.

For unattended agents, `pay mcp` accepts inline permissions or a YAML file. The documented command applies an origin restriction, mainnet restriction, and maximum payment amount:

pay mcp --allow-origin https://api.example.com --allow-network mainnet --max-payment '$1.00'

The corresponding configuration keys are:

origins: [https://api.example.com]
networks: [mainnet]
max_payment: "$1.00"
allow_any_asset: false

According to the README, these permissions apply to MPP charge requests and x402 exact, upto, and batch-settlement payments. Stateful MPP sessions and subscriptions fail closed while a permission policy is active. That is a concrete boundary rather than a general promise that every payment pattern is unrestricted.

Pay also provides an ACP path for clients such as Buzz. The documented adapter commands are `goose`, `claude`, and `codex`. `pay acp` starts the payer proxy, configures the selected ACP adapter, and passes ACP JSON-RPC through stdin and stdout without changing the protocol stream. A terminal client can select its provider and model interactively. A headless client can use the documented flags:

pay acp goose --provider alibaba --model qwen3.7-plus

The README also names `PAY_ACP_PROVIDER` and `PAY_ACP_MODEL` for headless configuration. These features make Pay useful when the agent process needs a controlled payment route, although they do not remove the need for a wallet policy.

Installing Pay and making a sandbox request

The README provides three installation routes. Homebrew installs a prebuilt macOS binary, npm installs the global package `@solana/pay`, and contributors can clone the Rust repository and use the project's Justfile. The shortest installation for many developers is:

npm install -g @solana/pay

For a source checkout, use the documented commands:

git clone https://github.com/solana-foundation/pay.git
cd pay
just install pay

After installation, check that the CLI is available:

pay --version

The first documented account setup uses:

pay setup
pay whoami

The README says setup selects Touch ID on macOS, Windows Hello on Windows, GNOME Keyring on Linux, or 1Password. It also documents an Openfort backend wallet option. The local key-based path is intended to keep signing authority out of the agent's direct command environment, but the README does not define a rollback procedure for wallet setup or credential changes.

A first sandbox request can then be made through the bundled sandbox endpoints:

pay --sandbox curl https://debugger.pay.sh/mpp/quote/AAPL

This is a real use of the CLI's 402 handling path without asking the reader to assume that a paid production endpoint is appropriate as a first test. The non-sandbox comparison is also documented:

curl https://debugger.pay.sh/mpp/quote/AAPL
pay curl https://debugger.pay.sh/mpp/quote/AAPL

The README presents the first command as returning a 402 and the Pay-wrapped command as handling the challenge and returning the response.

Debugging and sandboxing payment failures

Payment systems need an inspection path because a 402 response can fail at several points: challenge parsing, protocol selection, asset handling, wallet authorization, signing, or proof submission. Pay includes an embedded Payment Debugger, described as a local web UI that visualizes each 402 challenge-response cycle as a sequence diagram. The README says the view shows which headers were sent, whether MPP or x402 was used, and where the exchange failed. It states that the debugger runs locally and that no data leaves the machine.

Pay can attach the debugger to a gateway defined by a YAML file:

pay gate api paywall.yml --debugger

For local inference and optional per-model rates, the documented sandbox syntax is:

pay --sandbox gate inference rates.yml

There is also a bundled demonstration mode:

pay gate demo

This debugger is more useful than a generic request logger because it is tied to Pay's payment protocol state. However, the README does not document retention behavior for local debugger data, export formats, or a formal way to replay a failed production transaction. It also says that a public debugger is available at `https://debugger.pay.sh`, so users who require a strictly local investigation should distinguish the embedded local mode from that public service.

Wallet authorization and operational limits

Pay's security model is centered on local authorization. The README says agents can use paid APIs without giving the agent a private key or an API-wide spending credential. Pay prepares the payment locally, then asks the wallet backend to authorize the signature. On macOS the documented backend is Touch ID through Keychain, on Windows it is Windows Hello, and on Linux it is GNOME Keyring or polkit.

That arrangement reduces the amount of payment authority exposed to an agent, but it does not make payments risk-free. A user can still authorize an unwanted transaction if the origin, asset, amount, or network policy is too broad. Pay accepts MCP restrictions such as `origins`, `networks`, `max_payment`, and `allow_any_asset`. Separately, headless ACP clients can set `PAY_ACP_PROVIDER` and `PAY_ACP_MODEL`.

The README documents a Linux-specific failure mode involving `pay topup` and `pay curl` errors containing `auth failed`. It attributes the issue to GNOME Keyring authentication through polkit and gives this setup command:

sudo cp rust/config/polkit/sh.pay.unlock-keypair.policy /usr/share/polkit-1/actions/

This is a system-level change with elevated privileges, so it should be understood as a troubleshooting step rather than a default installation step. The README does not provide a Windows or macOS equivalent for that policy file.

The wallet model also introduces dependencies. Users need a supported wallet backend, a signing mechanism, and a stablecoin deployment on Solana. The project is not documented as a self-contained payment ledger, and the README does not explain how Pay behaves when a wallet is offline, a challenge expires, or a transaction changes state between signing and submission.

Pay versus server-side payment gateways and wallet libraries

Pay's alternative is not another agent CLI. It is a different placement of payment logic. A server-side payment gateway can terminate the HTTP request, issue its own session, and control billing rules inside the service. A wallet library exposes signing or transaction APIs to an application, leaving the application to implement 402 parsing, payment proof construction, retries, permissions, and agent integration.

Pay takes the client-side route. It intercepts a command's 402 response, recognizes MPP or x402, coordinates local authorization, and retries the original request. It also adds agent-specific surfaces such as MCP, ACP, paid API discovery, and a debugger. This is a better fit when the caller is an agent that must pay per request or when a service already speaks one of these HTTP payment protocols.

The trade-off is that Pay depends on the payment protocol and wallet environment being correct on the caller's machine. A library can be embedded into a server with controlled credentials and custom accounting. Pay is more directly useful for local command execution, but the README does not claim that it covers every payment model. Stateful MPP sessions and subscriptions fail closed under an active permission policy, and the documented permissions apply to a defined set of MPP and x402 payment types.

The open-source `pay-skills` catalog is a separate discovery resource. Pay can search it with `pay skills search "maps"`, but the catalog does not itself replace Pay's transaction signing or HTTP challenge handling.

Maintenance, upgrades, and license implications

The repository is not archived, and the last push was on 2026-10-16. Recent releases include `pay-v0.29.0` dated 2026-09-26, `pay-v0.28.0` dated 2026-08-26, and `pay-v0.27.0` dated 2026-08-02. Those facts indicate recent release activity, but the README does not provide a formal compatibility policy for wallet backends, protocol versions, stablecoins, or agent clients. Upgrading therefore requires checking the release-specific documentation and testing the payment path in a controlled environment.

The project is written primarily in Rust and uses the MIT license. The MIT license permits use, modification, distribution, and private derivative works under its stated conditions, including preservation of the license and copyright notice. This is a licensing summary, not legal advice. The repository also contains Rust, TypeScript, and web UI directories, so teams adopting more than the CLI should review the relevant source and dependency files rather than assuming every component has the same operational surface.

The README gives contribution commands under `rust`, including `just build`, `just test`, and `just lint`. It does not document a migration or rollback procedure for account configuration, permission YAML files, or a previously deployed wallet. Before an upgrade, compare the permission policy and backend settings, then verify `pay --version` and the intended payment protocol in sandbox mode.

Editorial conclusion

Adopt Pay when an agent or developer needs to call Solana-based paid HTTP APIs without embedding a private key in agent code, especially when x402, MPP, MCP, or ACP support is required. Do not choose it as a general payment processor, a non-Solana wallet, or a replacement for a service-side paywall. Verify first that the required protocol, wallet backend, spending permissions, network, and stablecoin are supported in the target deployment.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. solana-foundation/pay on GitHub