Install buy, fund a wallet and pay for a request

Install

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

$ npm install -g @celo/buy@0.8.5

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.

Try it with no money

--sandbox runs the same command on Celo Sepolia with test USDC. There is no wallet to set up and nothing to fund: the first run creates an account named sandbox in your keychain, the gateway faucet sends it 1 test USDC when it runs short, and the request is paid and served like any other.

$ buy --sandbox curl -X POST https://gateway.usebuy.ai/v1/social/x/posts/search -H 'content-type: application/json' -d '{"query":"celo"}'

To see the price and stop at the 402, buy --sandbox quote takes the same arguments and pays nothing.

$ buy --sandbox quote -X POST https://gateway.usebuy.ai/v1/social/x/posts/search -H 'content-type: application/json' -d '{"query":"celo"}'

For an agent, register the MCP server with the same flag. Every buy_curl it makes then pays on Celo Sepolia from the sandbox account; on a server registered without the flag, buy_curl with sandbox: true does the same for one call.

$ buy mcp install --client all --sandbox

Every 402 for a gateway capability (/v1/…) lists one Celo Sepolia USDC offer at the same price as the mainnet offers; the partner routes (/chainstack, /cencori) are mainnet only. The upstream call is real, so the sandbox allows 2 USD of upstream cost per day in total and 0.10 USD per payer, and answers 429 past either cap. Pick a cheap route: the search above costs 0.001 USD upstream, and a route whose upstream price is over 0.10 USD cannot be bought in the sandbox at all. The faucet gives an address 1 test USDC per UTC day and 50 a day in all. Test USDC has no value, nothing here moves real money, and sandbox spend does not count against the mainnet daily cap. Set BUY_SANDBOX_NO_FUND=1 to stop the CLI from asking the faucet.

To pay for real, set up a wallet on Celo mainnet and drop --sandbox.

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, the buy server that quotes each request and settles its payment, 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.

Claim it to the address buy setup printed. Only the wallet's owner can verify, once per person. A wallet funded this way holds only USA₮, and the default token is USDC, so pay with --token USAT (token: "USAT" in MCP); if you forget, the payment is refused before anything is signed and the error names the token to use.

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. Each one does what the CLI command next to it does: buy_discover is buy skills list, buy skills search <query> and buy skills show <fqn>; buy_pay_quote is buy quote; buy_curl and its alias buy_fetch are buy curl and buy fetch; buy_balance and buy_whoami are buy whoami; buy_verify_status is buy verify status. There is no buy discover command. The eighth tool, buy_send (buy send), moves money directly and 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 an older HTTP client with its own options (buy fetch --help); prefer 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 sanctions screening are the defaults.

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

The gateway hosts the receiver, so nothing listens on your computer. 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 VM 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, abridged from the terminal output. Open the box to watch them play; with reduced motion they are shown at once.

What happens on the wire

buy uses x402, an open protocol built on HTTP status 402. A paid request takes four steps.

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 your computer.

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 VMs, stops admission at $25 per hour of catalogued compute, uses on-demand VMs 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.

Every cap a request can hit, with its number and the response it gets, is on the Limits page.

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 MCP tools are listed under MCP for agents. The full command reference, including buy send, is in the package README on npm ↗.