@celo/buy

buy pays HTTP 402 Payment Required challenges with USDC, USDT or USAT on Celo. It signs with a wallet held in your OS keychain, retries the request with an X-PAYMENT header, and can attach a Self.xyz proof when an endpoint requires one.

Node.js 22 or newer is required. No clone, npm login, or global install is needed.

Quickstart

Sandbox: try it with no money

--sandbox runs the whole flow on Celo Sepolia with test USDC, and needs no setup.

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"}'

On the first run buy creates an account named sandbox on Celo Sepolia (no prompt, never made your default), sees that it holds no USDC, asks the gateway's faucet (POST /v1/sandbox/fund on the same origin) to fund it with 1 test USDC, waits for the transfer to land, and pays the celo-sepolia offer. Two lines on stderr say what happened:

created sandbox account 0x… on celo-sepolia (test funds only)
sandbox: funded 0x… with 1 USDC (tx 0x…)

Later runs reuse the account and only call the faucet when it runs short. Sandbox USDC has no value, and sandbox spend is kept off the account's mainnet daily cap. buy --sandbox whoami shows the sandbox wallet once a paid call has created it (it never creates one itself); --account <name> with --sandbox pays from that account on Celo Sepolia instead. The faucet grants 1 USDC per address per day, so an offer above that cannot be paid from the sandbox. A server that offers mainnet only says so: drop --sandbox to pay with real funds, or run your own gate with buy gate --sandbox.

Set BUY_SANDBOX_NO_FUND=1 to never call the faucet; an empty wallet then fails the balance check as on mainnet, pointing at https://faucet.circle.com (select "Celo Sepolia").

Mainnet

Create a dedicated wallet. Celo mainnet is the default network:

npx --yes @celo/buy@0.8.5 setup --name demo

To pay from a wallet you already control instead — one you have declared to a programme or allowlist, say — add --import and supply the raw hex private key in BUY_IMPORT_KEY or on stdin (never as an argument, which would land it in shell history). buy whoami then marks the account (imported key). Encrypted keystore files are not supported.

Fund the printed address with a small amount of USDC, USDT or USAT on Celo mainnet. The gateway sponsors transaction gas, so the buyer does not need CELO — and buy send pays its gas in the token being sent (CIP-64), so moving money back out needs none either.

Create a Self proof if you plan to buy an e2-standard-* machine — the shared-core sizes (e2-micro, e2-small, e2-medium) need none. Scope buy.celo, minimum age 18, and OFAC screening are defaults; the gateway verifies against the Self mainnet hub, so a real passport is required and mock proofs are rejected:

npx --yes @celo/buy@0.8.5 verify hosted \
  --endpoint https://usebuy.ai/self/api/verify

The gateway hosts the Self receiver, so nothing listens on this machine and no cloudflared is needed. The --endpoint is whatever the 402 challenge pinned — a failed buy curl prints the whole command with it filled in, which beats typing it. Against a gateway that pins no endpoint, use verify serve instead; that one hosts a receiver locally and does need cloudflared.

Neither command ever receives the wallet private key.

Buy a one-hour e2-micro VM and run a script. Preserve the response because its poll URL is the capability used to collect the result:

(
  umask 077
  set -o pipefail
  response_file=$(mktemp ./buy-vm.XXXXXX) || exit
  npx --yes @celo/buy@0.8.5 --verbose curl \
    --max-amount 0.02 \
    -X POST \
    --data '{"script":"uname -a; nproc","machineType":"e2-micro"}' \
    https://usebuy.ai/google/vm | tee "$response_file"
  response_status=$?
  printf 'Private response saved to %s\n' "$response_file" >&2
  exit "$response_status"
)

On Windows, write the body to a file and pass --data-file body.json in place of --data '{…}': PowerShell 5.1 corrupts an inline JSON argument (npm's buy.ps1 shim re-splits it, and Out-File prepends a UTF-8 BOM the gateway rejects as invalid JSON). buy curl reads the file itself, strips a leading BOM, and gives curl a clean copy on both the probe and the paid retry. Write the file as UTF-8 (Out-File -Encoding utf8; its BOM is fine): PowerShell 5.1's default for Out-File and > is UTF-16, which buy refuses with a hint rather than sending. --data-file - reads stdin to completion before the first request. It cannot be combined with curl's own -d/--data*/--json/-F/-T; buy fetch accepts the same option. Keep stdout and stderr separate (2>&1 interleaves the error envelope with the response), and pass curl's --ssl-no-revoke if Schannel reports a certificate-revocation failure.

--verbose (before curl — after it, -v is curl's own flag) reports the quote, the signing step and the settlement tx on stderr, one {"log":"…"} object per line whenever stdout is not a terminal, so the tee above keeps the body and the terminal keeps the tx hash.

The response contains a poll URL. Call it until scriptStatus is done; polling is free:

npx --yes @celo/buy@0.8.5 curl '<poll-url>'

USDC is the default payment token. Add --token USDT or --token USAT to the paid command to pay in one of those instead; a server must offer that token in its 402 for the payment to go through.

Limits and safety

The public service uses on-demand VMs in us-west1 and supports e2-micro, e2-small, e2-medium, e2-standard-2, e2-standard-4, and e2-standard-8. Quotes are authoritative. The service limits leases to one hour at a time and 24 hours total, admits at most 100 VMs, and stops admission at $25/hour of catalogued compute. Each VM may send at most 10 GB of network egress; one that sends more is deleted within minutes, and its lease is not refunded; its poll URL then reports egressCapExceeded: true. /google/ssh is enabled and priced identically to /google/vm for the same machine type.

Mainnet payments are real and irreversible. Use a dedicated low-balance wallet and always set --max-amount. Do not automatically retry 500 provision_failed or 500 settle_uncertain; settlement may already have occurred. A 4xx or 503 refusal happens before settlement.

buy receipts --account demo lists local payment history, including the settlement transaction and, for a VM purchase, the poll URL. A receipt does not keep the response body, instance, IP, or correlation ID, so keep the generated private response file until the lease ends; a missing recovery field is not a reason to pay again. After a paid request that ended without a 2xx, such as 500 settle_uncertain, buy receipts --resolve asks the token contract whether the payment settled.

Other commands

npx --yes @celo/buy@0.8.5 --help
npx --yes @celo/buy@0.8.5 whoami
npx --yes @celo/buy@0.8.5 mcp install --client all

buy quote takes the same arguments as buy curl and stops at the 402: it prints each offer's token, price, network, recipient and whether a Self.xyz attestation is required, without a wallet and without paying. --json emits the raw envelope. A route that answers anything other than 402 exits 1 with unexpected_response.

Wallet configuration and receipts persist between npx invocations. BUY_HOME chooses a different data directory. Existing installations continue to use ~/.config/cpay (legacy default) and the existing OS-keychain entry, whose service name is cpay (kept so the rename does not strand a wallet; buy setup prints it). buy fetch remains the compatibility alias; new usage should prefer buy curl.

This is pre-1.0 beta software without an external security review. It is not intended for production use.

License: Apache-2.0