pay x402 tool

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/solana-foundation/pay/raw/main/docs/assets/banner-main-dark.png"> <source media="(prefers-color-scheme: light)" srcset="https://github.com/solana-foundation/pay/raw/main/docs/assets/banner-main-light.png"> <img alt="pay.sh" width="100%" src="https://github.com/solana-foundation/pay/raw/main/docs/assets/banner-main-light.png"> </picture> </div> <p align="center"> <a href="https://skills.sh/solana-foundation/pay"><img alt="skills.sh" src="https://skills.sh/b/solana-foundation/pay"></a> <a href="https://x402.org"><img alt="x402" src="https://img.shields.io/badge/protocol-x402-black"></a> <a href="https://paymentauth.org"><img alt="MPP" src="https://img.shields.io/badge/protocol-MPP-black"></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a> </p> <p align="center"> <b>The missing payment layer for HTTP — x402 &amp; MPP payment challenges with user-authorized stablecoin signing.</b> </p> <p align="center"> <a href="#installation">Install</a> · <a href="#quick-start">Quick Start</a> · <a href="https://docs.solanapay.com">Docs</a> </p>

---

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

# With pay -- it handles the 402 challenge and returns the response
pay curl https://debugger.pay.sh/mpp/quote/AAPL

Key Features

💵 Transparent 402 Handling

Wrap your CLI (curl, claude, codex, etc.) -- when an API returns 402, pay detects the payment protocol, prepares the stablecoin transaction, asks the local wallet to authorize and sign it, then retries with the payment proof.

Supports both live payment standards on Solana:

• MPP — Machine Payments Protocol
• x402 — x402 Payment Protocol

Stablecoins deployed to Solana are supported out of the box.

🤖 AI-Native with MCP

pay ships with a built-in MCP server, letting AI assistants request paid API calls through the same local wallet-approval flow.

# Run Claude Code or Codex with pay injected into the agent session
pay claude
pay codex

For unattended agents, pay mcp can enforce pay-kit's payment permissions before any transaction is built or signed. Configure them inline or with a strict YAML file:

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

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

Configured permissions apply to MPP charge and x402 exact, upto, and batch-settlement payments. Stateful MPP sessions and subscriptions fail closed while a permission policy is active.

ACP clients such as Buzz can launch the same paid inference route without sharing their protocol stream with Pay:

# Interactive provider/model selection when run from a terminal
pay acp goose

# Deterministic configuration for a headless ACP client
pay acp goose --provider alibaba --model qwen3.7-plus

pay acp supports goose, claude, and codex. It starts the payer proxy, configures the selected ACP adapter to use it, and passes ACP JSON-RPC through stdin/stdout unchanged. Headless clients may set PAY_ACP_PROVIDER and PAY_ACP_MODEL instead of passing flags.

🛠️ Payment debugging and simulations

pay ships with an embedded Payment Debugger — a local web UI that visualizes every 402 challenge-response cycle as a sequence diagram. See exactly which headers were sent, which protocol was used (MPP or x402), and where things went wrong.

Everything runs locally — no data leaves your machine.

# Start a gateway with the debugger on any paywall
pay gate api paywall.yml --debugger

# Discover and gate local inference with optional per-model rates
pay --sandbox gate inference rates.yml

# Or run the bundled demo (sandbox + debugger + sample endpoints)
pay gate demo

A public debugger is also available.

🔐 Gated Payments via Biometrics

pay lets AI agents use paid APIs without giving them your private key or an API-wide spending credential.

When a command, Claude Code, Codex, or another MCP client hits a paid endpoint, pay prepares the payment locally and asks your wallet backend to authorize the signature. On macOS, that means Touch ID via Keychain. On Windows, Windows Hello. On Linux, GNOME Keyring / polkit. If you reject the prompt, the payment is not signed and the request does not go through.

pay setup    # Touch ID on macOS, Windows Hello on Windows, GNOME Keyring on Linux, or choose 1Password

Prefer to keep no key on the machine at all? pay can also sign through an Openfort backend wallet: the private key stays in Openfort's TEE, each payment is a policy-checked API call, and the local credentials are revocable.

pay account new agent --backend openfort   # connect an existing Openfort backend wallet (acc_…)

📚 Open Source Catalog

The paid API catalog is open source in the pay-skills repo.

Anyone can contribute a provider listing, improve endpoint metadata, or add usage guidance for agents. Catalog entries follow the pay-skills contributing guide, which defines the metadata, pricing, endpoint, and usage-note standards that keep Agent experience consistent.

  pay skills search "maps"

Good catalog entries make paid APIs easier for both humans and agents to discover, compare, and use safely.

Installation

Prebuilt Binaries

# macOS
brew install pay

# via NPM
npm install -g @solana/pay

From Source

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

Verify

pay --version

Quick Start

# 1. Setup your account
pay setup
pay whoami

# 2. Make a paid gated API call to https://debugger.pay.sh sandbox endpoints
pay --sandbox curl https://debugger.pay.sh/mpp/quote/AAPL

# 3. Or let your AI agent handle it
pay claude

Contributing

cd rust
just build   # release binary
just test    # all tests
just lint    # clippy (warnings = errors)

We welcome contributions — check open issues to get started.

Troubleshooting

Linux: pay topup or pay curl errors with "auth failed"

GNOME Keyring auth uses polkit, which requires a one-time setup step:

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

This grants pay the right to prompt for your password or fingerprint before accessing the keypair.

License

MIT — see LICENSE.

Subject to the foregoing, the Terms of Service available at solana.com/tos