Let an AI agent or a CLI pay for HTTP APIs, data, and compute in stablecoins on Celo with buy, an x402 payment client
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
Your agent or script calls a paid endpoint through buy.
The service answers 402 Payment Required with its offers: token, price, network, and recipient.
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.
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:
# Celo Sepolia (11142220), test USDC, no real fundsnpx --yes @celo/buy@0.8.5 --sandbox curl https://gateway.usebuy.ai/v1/social/x/posts/search \ -X POST -H 'content-type: application/json' -d '{"query":"celo"}'
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:
# Celo mainnet (42220)npx --yes @celo/buy@0.8.5 setup --name demo
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:
# Celo mainnet (42220), pays at most 0.01 USDCnpx --yes @celo/buy@0.8.5 curl --max-amount 0.01 https://gateway.usebuy.ai/v1/social/x/posts/search \ -X POST -H 'content-type: application/json' -d '{"query":"celo"}'
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:
npx --yes @celo/buy@0.8.5 mcp install --client all
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.
npx skills add celo-org/buy-skill
Troubleshooting
Error
What to do
500 provision_failed or 500 settle_uncertain
Do not retry automatically: the payment may already have settled. Run buy receipts --resolve to ask the token contract whether it did.
unexpected_response from buy quote
The route answered with something other than 402, so it is not a paid endpoint. Check the URL.
amount_exceeds_max
The quote is above your --max-amount (or maxAmount). Nothing was signed. Raise the cap only if the price is expected.
insufficient_balance
The wallet holds less than the price. Nothing was signed. Fund the account.
A 4xx or 503 response
If the body says paymentSettled: false (buy gateway), the request was refused before settlement. If buy printed the paid request ended with HTTP …; the payment may have settled, run buy receipts --resolve before paying again, and do not retry automatically.
buy receipts --account <name> lists your local payment history, including each settlement transaction.