szapelao · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026
@@ -26,6 +26,7 @@ Install the docs skill with `npx skills add https://docs.celo.org`. MCP clients
 |----------|------------------------|------|
 | Celopedia | A skill with curated Celo knowledge: contract addresses, MiniPay, DeFi, grants and agent infrastructure | [Celopedia](/build/agents/celopedia) |
 | Celo MCP server | Live chain data: balances, blocks, gas fees, governance and staking | [Celo MCP server](/build/agents/mcp/celo-mcp) |
+| buy | Pay for HTTP APIs, data and compute in stablecoins, as a CLI or MCP server | [buy](/build/agents/buy) |
 
 ## Third-party tools
 

@@ -0,0 +1,97 @@
+---
+title: "buy: Pay for APIs from an agent"
+sidebarTitle: "buy (agent payments)"
+description: 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](https://usebuy.ai) 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](/build/agents/x402) flow, and works as a CLI or as an MCP server that gives an agent payment tools.
+
+<Warning>
+  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.
+</Warning>
+
+## 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:
+
+```bash
+# Celo Sepolia (11142220), test USDC, no real funds
+npx --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:
+
+```bash
+# 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:
+
+```bash
+# Celo mainnet (42220), pays at most 0.02 USDC
+npx --yes @celo/buy@0.8.5 curl --max-amount 0.02 <paid-endpoint-url>
+```
+
+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
+
+Install the buy MCP server in your MCP clients:
+
+```bash
+npx --yes @celo/buy@0.8.5 mcp install --client all
+```
+
+The agent gets tools such as `buy_pay_quote`, `buy_curl`, `buy_balance` and `buy_whoami`. Every paid call over MCP carries a `maxAmount` and is refused before signing when the quote is above it. `buy_send`, which moves money directly, stays off unless you enable it with a budget or an allowlist.
+
+The MCP server gives an agent the ability to pay. The [buy skills](https://github.com/celo-org/buy-skill) 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.
+
+```bash
+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. |
+| A `4xx` or `503` response | The service refused the request before settlement, so nothing was charged. |
+
+`buy receipts --account <name>` lists your local payment history, including each settlement transaction.
+
+## Resources
+
+| Resource | Link |
+|----------|------|
+| buy website and catalog | [usebuy.ai](https://usebuy.ai) |
+| `@celo/buy` on npm | [npmjs.com/package/@celo/buy](https://www.npmjs.com/package/@celo/buy) |
+| buy skills | [github.com/celo-org/buy-skill](https://github.com/celo-org/buy-skill) |
+
+## Related
+
+- [x402](/build/agents/x402) - the payment flow buy uses, and how to charge for your own API
+- [x402: Get your endpoint discovered](/build/agents/x402-get-discovered) - how to ask for a listing in the buy catalog
+- [Give your agent a wallet and test funds](/build/agents/agent-wallet) - other ways for an agent to hold and spend funds on Celo
@@ -4,7 +4,7 @@ sidebarTitle: "Overview"
 description: Build AI agents on Celo that pay, transact, and coordinate onchain with stablecoins
 ---
 
-## Agentic Activity with Real World Utility
+## Agentic Activity with Real-World Utility
 
 Celo is a leading Ethereum Layer 2 optimized for agentic activity with real-world utility, enabling AI agents to autonomously perform onchain actions tied directly to payments, commerce, and financial coordination.
 
@@ -57,21 +57,22 @@ On Celo, agents are first-class participants in the economy. They can send and r
 Agents on Celo can charge and pay for services over plain HTTP, settling in stablecoins in a single request — no accounts, invoices, or checkout flows.
 
 - **[x402](/build/agents/x402)** gives meaning to the HTTP `402 Payment Required` status code, letting an agent settle a stablecoin micropayment inline with the request.
-- **[MPP (Machine Payments Protocol)](/build/agents/mpp)** is a separate protocol that uses the same `402` flow, so any service can charge USDC per request. On Celo it settles through the same hosted facilitator as x402 — the buyer pays no gas.
+- **[MPP (Machine Payments Protocol)](/build/agents/mpp)** is a separate protocol that uses the same `402` flow, so any service can charge USDC per request. On Celo, it settles through the same hosted facilitator as x402 — the buyer pays no gas.
+- **[buy](/build/agents/buy)** is Celo's x402 payment client: it lets an agent or a script pay for paid HTTP APIs in stablecoins, with a spending cap on every call.
 
 Both settle on-chain in seconds, making them well-suited to paid APIs, pay-per-use tools, and agent-to-agent commerce. A paid API, MCP server, or bot can also carry its own ERC-8004 identity, so agents can discover it and rate it — see [Register a service](/build/agents/8004#register-a-service).
 
 ## Giving an agent a wallet
 
-An agent that pays for things needs an account it can read from and sign with. To create one and fund it on Celo Sepolia, follow [Give your agent a wallet and test funds](/build/agents/agent-wallet). You can wire this up directly with [viem](/build/tools/libraries-sdks/viem), or use a tool that exposes the calls to an LLM: [Celina](/build/agents/mcp/celina) covers balances, transfers, DeFi, governance, staking and Self Agent ID through an SDK, an MCP server, and a REST API. The SDK and MCP server are open source.
+An agent that pays for things needs an account it can read from and sign with. To create one and fund it on Celo Sepolia, follow [Give your agent a wallet and test funds](/build/agents/agent-wallet). You can wire this up directly with [viem](/build/tools/libraries-sdks/viem), or use a tool that exposes the calls to an LLM: [Celina](/build/agents/mcp/celina) covers balances, transfers, DeFi, governance, staking, and Self Agent ID through an SDK, an MCP server, and a REST API. The SDK and MCP server are open source.
 
 ## Paying by card and signing in to websites
 
-Some merchants accept only cards, and some websites have no API. [Agent Vault](/build/agents/agent-vault), a product of Self Labs, lets an agent you build pay by card and sign in to websites through a hosted MCP server, a Playwright SDK or an HTTP API. The agent works with mock tokens and never holds the card number or password. It is not a Celo protocol and does not settle onchain; for onchain payments, use [x402](/build/agents/x402) and [MPP](/build/agents/mpp).
+Some merchants accept only cards, and some websites have no API. [Agent Vault](/build/agents/agent-vault), a product of Self Labs, lets an agent you build pay by card and sign in to websites through a hosted MCP server, a Playwright SDK, or an HTTP API. The agent works with mock tokens and never holds the card number or password. It is not a Celo protocol and does not settle onchain; for onchain payments, use [x402](/build/agents/x402) and [MPP](/build/agents/mpp).
 
 ## Getting reviews from agents
 
-[AskBots](/build/agents/askbots) is a product built by the Celo team together with an AI agent, where builders pay AI agents in USDT to review a website, API, MCP server, skill file or Mini App, and where agent developers can run an agent that earns USDT for accepted reviews.
+[AskBots](/build/agents/askbots) is a product built by the Celo team together with an AI agent, where builders pay AI agents in USDT to review a website, API, MCP server, skill file, or Mini App, and where agent developers can run an agent that earns USDT for accepted reviews.
 
 ## Fee Abstraction for Agents
 

@@ -192,6 +192,7 @@
               "build/agents/x402",
               "build/agents/x402-get-discovered",
               "build/agents/mpp",
+              "build/agents/buy",
               "build/agents/celopedia",
               "build/agents/vibe-coding",
               "build/agents/mcp/index",