From 4583269f03823f9b78fa1cb7eb3778ce114c7104 Mon Sep 17 00:00:00 2001 From: Susanne Date: Tue, 3 Nov 2026 16:00:02 +0000 Subject: [PATCH 1/6] docs(agents): add buy page --- build/agents/buy.mdx | 97 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 build/agents/buy.mdx diff --git a/build/agents/buy.mdx b/build/agents/buy.mdx new file mode 100644 index 000000000..f567b447c --- /dev/null +++ b/build/agents/buy.mdx @@ -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. + + + 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: + +```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 +``` + +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 ` 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 From 580d56ba0bac1d6cdc4e843133f341b70c91fc63 Mon Sep 17 00:00:00 2001 From: Susanne Date: Tue, 3 Nov 2026 16:13:14 +0000 Subject: [PATCH 2/6] docs(agents): add buy to navigation --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index e6cebc6e1..4e9e2112f 100644 --- a/docs.json +++ b/docs.json @@ -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", From 0247a68e4f958c887bd8e0745d7d4bb347ba0d36 Mon Sep 17 00:00:00 2001 From: Susanne Date: Tue, 3 Nov 2026 16:14:42 +0000 Subject: [PATCH 3/6] docs(agents): list buy in AI resources --- build/agents/ai-resources.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/build/agents/ai-resources.mdx b/build/agents/ai-resources.mdx index a11d224b1..2a12643ac 100644 --- a/build/agents/ai-resources.mdx +++ b/build/agents/ai-resources.mdx @@ -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 From 6b5c33ea22aeb8cc06db92f2f4bddb62526c9324 Mon Sep 17 00:00:00 2001 From: Susanne Date: Tue, 3 Nov 2026 16:16:31 +0000 Subject: [PATCH 4/6] docs(agents): mention buy in overview --- build/agents/overview.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/build/agents/overview.mdx b/build/agents/overview.mdx index 4c0e8a0c1..b848eca8e 100644 --- a/build/agents/overview.mdx +++ b/build/agents/overview.mdx @@ -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 From 37314f580489dc1c4885b42c4bd30899ee855247 Mon Sep 17 00:00:00 2001 From: Susanne Date: Fri, 6 Nov 2026 11:38:14 +0000 Subject: [PATCH 5/6] docs(agents): fix buy cap, buy_send and troubleshooting per review --- build/agents/buy.mdx | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/build/agents/buy.mdx b/build/agents/buy.mdx index f567b447c..0736c1e4c 100644 --- a/build/agents/buy.mdx +++ b/build/agents/buy.mdx @@ -50,21 +50,24 @@ Fund the printed address with a small amount of USDC, USD₮, or USA₮ on Celo 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 +# Celo mainnet (42220), pays at most 0.01 USDC +npx --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 -Install the buy MCP server in your MCP clients: +Register the buy MCP server with Claude Code and Codex: ```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. +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 `. `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](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. @@ -78,7 +81,9 @@ npx skills add celo-org/buy-skill |-------|------------| | `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. | +| `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 | With `paymentSettled: false` in the body, or no `X-PAYMENT-RESPONSE` header, the request was refused before settlement. Otherwise it may have been charged: check for a receipt, or run `buy receipts --resolve`, before retrying, and do not retry automatically. | `buy receipts --account ` lists your local payment history, including each settlement transaction. From c28919d906a5f4ada84dd12b3eebbf835095a069 Mon Sep 17 00:00:00 2001 From: Susanne Date: Fri, 6 Nov 2026 11:40:16 +0000 Subject: [PATCH 6/6] docs(agents): fix the buy cap wording and the settle sentence in overview --- build/agents/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/build/agents/overview.mdx b/build/agents/overview.mdx index b848eca8e..a3089946e 100644 --- a/build/agents/overview.mdx +++ b/build/agents/overview.mdx @@ -58,9 +58,9 @@ Agents on Celo can charge and pay for services over plain HTTP, settling in stab - **[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. -- **[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. +- **[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 per-call spending cap you set (`--max-amount`). -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). +x402 and MPP 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