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 diff --git a/build/agents/buy.mdx b/build/agents/buy.mdx new file mode 100644 index 000000000..0736c1e4c --- /dev/null +++ b/build/agents/buy.mdx @@ -0,0 +1,102 @@ +--- +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.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 + +Register the buy MCP server with Claude Code and Codex: + +```bash +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 `. `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. + +```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. | +| `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. + +## 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 diff --git a/build/agents/overview.mdx b/build/agents/overview.mdx index 4c0e8a0c1..a3089946e 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 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 -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 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",