Skip to main content
This page is for agent developers who want their agent, or their own scripts, to pay for paid HTTP services on Celo. buy is a payment client built by Celo: when a service answers 402 Payment Required, buy signs a stablecoin payment with a wallet kept in your OS keychain and retries the request with the payment attached. It pays in USDC, USDâ‚®, or USAâ‚® on Celo through the x402 flow, and works as a CLI or as an MCP server that gives an agent payment tools.
buy is pre-1.0 beta software without an external security review, and it is not intended for production use. Mainnet payments are real and irreversible: use a dedicated wallet with a small balance and always set a maximum amount.

Prerequisites

  • Node.js 22 or later. buy runs with npx, so there is nothing to clone or install globally.
  • For mainnet payments, a small amount of USDC, USDâ‚®, or USAâ‚® on Celo mainnet in the wallet buy creates. The sandbox below needs no funds.

How it works

  1. Your agent or script calls a paid endpoint through buy.
  2. The service answers 402 Payment Required with its offers: token, price, network, and recipient.
  3. buy checks the price against your maximum, signs the payment with the key in your OS keychain, and retries the request. The agent never sees the private key.
  4. The payment settles on Celo through the x402 facilitator, and buy returns the service’s response.
Paid calls to the buy gateway go to https://gateway.usebuy.ai, which holds the upstream providers’ credentials, so the agent never handles a third-party API key.

Try it in the sandbox

--sandbox runs the whole flow on Celo Sepolia with test USDC and needs no setup. On the first run buy creates a sandbox account, funds it with 1 test USDC from the gateway faucet, and pays the request:
The faucet grants 1 test USDC per address per day, so an offer above that cannot be paid from the sandbox.

Pay on mainnet

Create a dedicated wallet. Celo mainnet is the default network:
Fund the printed address with a small amount of USDC, USD₮, or USA₮ on Celo mainnet. To see what an endpoint charges before paying, use buy quote: it takes the same arguments as buy curl, prints each offer’s token, price, network and recipient, and pays nothing. Every paid call should carry --max-amount. buy refuses to sign when the quote is above it:
USDC is the default token. Add --token USDT or --token USAT to pay in one of those instead; the service must offer that token in its 402 response.

Give an agent payment tools

Register the buy MCP server with Claude Code and Codex:
For any other MCP client, configure npx --yes @celo/buy@0.8.5 mcp serve as a stdio server. The agent gets tools such as buy_pay_quote, buy_curl, buy_balance and buy_whoami. Pass maxAmount on every paid call: it is optional, in atomic units (20000 is 0.02 USDC), and without it the call is capped only by the account’s daily cap, if you set one with buy account cap <name> <amount>. buy_send, which moves money directly, is off by default. To turn it on, set BUY_MCP_ENABLE_SEND=1, BUY_MCP_SEND_ACCOUNT, and either BUY_MCP_SEND_BUDGET or BUY_MCP_SEND_ALLOWLIST. The MCP server gives an agent the ability to pay. The buy skills teach it how to use that safely: read the free catalog, quote the exact request, get your approval for the price, pay once, and report the transaction hash.

Troubleshooting

buy receipts --account <name> lists your local payment history, including each settlement transaction.

Resources