Everything your agent needs to pay for a service.

Install

Node.js 20 or newer. No clone and no npm login: one global install, then every command is buy.

$ npm install -g @celo/buy@0.8.2

The package and its runtime dependencies are public on npm. You do not need access to the source repository to use the CLI or the MCP server.

Wallet and funding

Create a dedicated wallet. The key is generated and stored in your OS keychain, and Celo mainnet is the default network.

$ buy setup --name demo

Fund the printed address with a small amount of USDC, USD₮ or USA₮ on Celo mainnet. The gateway sponsors transaction gas, so the wallet does not need CELO, and buy send pays its own gas in the token being sent, so moving money back out needs none either.

To pay from a wallet you already control, add --import to buy setup and supply the raw hex private key on stdin, never as an argument. buy whoami then marks the account as imported. Encrypted keystore files are not supported.

$ buy whoami

MCP for agents

Register the buy tools with Claude Code and Codex. The server runs over stdio and reads the wallet from your keychain; nothing runs remotely.

$ buy mcp install --client all

Seven tools are registered by default: discover services, quote a price, pay for a request (buy_curl and its alias buy_fetch), check a balance, check who the wallet is, and check a Self attestation. The eighth, which moves money directly, stays opt-in behind an explicit budget or allowlist.

Pay for a request

buy curl takes the same arguments as curl. It sends the request, reads the 402 challenge, signs a stablecoin transfer locally and retries with the payment attached. --max-amount is the most the call may spend; the request is refused before anything is signed if the quote is higher.

$ buy curl --max-amount 0.01 -X POST -H 'Content-Type: application/json' --data '[{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}]' https://gateway.usebuy.ai/chainstack/celo

To see the price without paying, buy quote takes the same arguments and stops at the 402. It prints each offer's token, price, network and recipient, and whether a Self attestation is required.

$ buy quote -X POST -H 'Content-Type: application/json' --data '[{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}]' https://gateway.usebuy.ai/chainstack/celo

• USDC is the default token. Add --token USDT or --token USAT to pay in USD₮ or USA₮ instead; the service must offer that token in its 402.
• --verbose (before curl) reports the quote, the signing step and the settlement transaction on stderr, one JSON object per line when stdout is not a terminal.
• On Windows, write the body to a file and pass --data-file body.json instead of an inline JSON argument. PowerShell 5.1 re-splits inline JSON and writes UTF-16 by default; save the file as UTF-8.
• buy fetch is the compatibility alias for buy curl.

Verify with Self

Some services ask for proof of a person behind the wallet: age 18 or over and not on a sanctions list. The proof is zero-knowledge, created in the Self app from a real passport, and bound to the paying wallet. The gateway checks it against the Self mainnet hub, so mock proofs are rejected. Scope buy.celo, minimum age 18 and OFAC screening are the defaults.

$ buy verify hosted --endpoint https://usebuy.ai/self/api/verify

The gateway hosts the receiver, so nothing listens on your machine. Open the Self app, scan the QR code, and the proof is stored locally for later purchases. A failed buy curl prints this command with the right endpoint filled in. Re-run it when a stored proof expires. Neither command ever receives the wallet's private key.

Rent a VM

The gateway sells one-hour Google Cloud VMs in us-west1. The shared-core sizes (e2-micro, e2-small, e2-medium) need no proof; the e2-standard sizes ask for the Self proof above. The response carries a poll URL: keep it, it is the only way to collect the result.

# buy an e2-standard-2 VM; the 0.15 cap is the most this call may spend$ buy --verbose curl --max-amount 0.15 -X POST --data '{"script":"uname -a; nproc","machineType":"e2-standard-2"}' https://usebuy.ai/google/vm  402   about 0.1341 USDC · celo · e2-standard-2 VM for 1 hour        identity  age 18+ · not sanctioned  200   { "transaction": "0x8238…", "instance": "<instance>",          "poll": "https://usebuy.ai/google/vm/823847337baade7f…" } # collect the output; this GET is free$ buy curl https://usebuy.ai/google/vm/823847337baade7f…  200   { "scriptStatus": "done", "result": "Linux 6.1.0-51-cloud…" }  ↳ no scriptStatus yet means the VM is still booting: wait and poll again  ↳ add --token USDT or --token USAT to pay in one of those instead of USDC

A purchase usually answers after about a minute and a renewal after two to three; the payment settles first, so do not interrupt the request. /google/vm runs a startup script and returns its output through the poll URL. /google/ssh sells the same machine with an external IP and your public key installed, priced identically. Instances delete themselves when the lease ends.

Prices in US dollars, payable in USDC, USD₮ or USA₮. The 402 quote for the exact request is authoritative.

A real exchange

Three requests, each actually paid for on Celo mainnet and pasted from the terminal. Open the box to watch them play; with reduced motion they are shown at once.

What happens on the wire

buy speaks x402, the open protocol that gives HTTP status 402 a job. Four steps, numbered by the status code each one produces.

1. 01 / Call service

   Request

   An ordinary request to an ordinary URL. No key, no session, no prior relationship with the server.

2. 02 / Receive price

   402 Payment Required

   The challenge carries the amount, the token, the recipient and the chain, plus a demand for a Self proof if the endpoint requires one.

3. 03 / Authorize payment

   Pay

   Your wallet signs an EIP-3009 transfer locally for one amount, to one recipient, once. The key never leaves the machine.

4. 04 / Receive result

   200 Response

   The signature rides back on an X-PAYMENT header. The server verifies it, settles on Celo, and answers the original request.

Payments are final; there are no refunds. The spending cap per call is the main safety control.

Limits and safety

• Mainnet payments are real and irreversible. Use a dedicated low-balance wallet and always set --max-amount close to the quote.
• Do not automatically retry 500 provision_failed or 500 settle_uncertain: settlement may already have happened. A 4xx or 503 refusal happens before settlement.
• The VM service allows at most 100 machines, stops admission at $25 per hour of catalogued compute, uses on-demand instances only, and limits leases to one hour at a time and 24 hours in total.
• Each VM may send at most 10 GB of network egress. One that sends more is deleted within minutes, its lease is not refunded, and its poll URL reports egressCapExceeded: true.
• buy is pre-1.0 beta software without an external security review. It is not intended for production use.

buy receipts lists local payment history, including the settlement transaction and, for a VM purchase, the poll URL. After a paid request that ended without a 2xx, --resolve asks the token contract whether the payment settled.

$ buy receipts --account demo --resolve

Other commands

$ buy --help

Wallet configuration and receipts persist between runs. BUY_HOME chooses a different data directory. The full reference, including buy send and the MCP tool list, is in the package README on npm ↗.