@celo/buy

buy pays HTTP 402 Payment Required challenges with USDC or USDT 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 20 or newer is required. No clone, npm login, or global install is needed.

Quickstart

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

npx --yes @celo/[email protected] setup --name demo

Fund the printed address with a small amount of USDC or USDT on Celo mainnet. The gateway sponsors transaction gas, so the buyer does not need CELO.

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/[email protected] 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/[email protected] --verbose curl \
    --max-amount 0.02 \
    -X POST \
    --data '{"script":"uname -a; nproc","machineType":"e2-micro"}' \
    https://usebuy.ai/gcloud/vm | tee "$response_file"
  response_status=$?
  printf 'Private response saved to %s\n' "$response_file" >&2
  exit "$response_status"
)

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

npx --yes @celo/[email protected] curl '<poll-url>'

USDC is the default payment token. Add --token USDT to the paid command to use USDT.

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 200 VMs, and stops admission at $25/hour of catalogued compute. /gcloud/ssh is enabled and priced identically to /gcloud/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, but streamed buy curl receipts currently do not retain the paid response, transaction hash, poll URL, instance, IP, or correlation ID. Until cpay#85 is fixed, keep the generated private response file until the lease ends; a missing recovery field is not a reason to pay again.

Other commands

npx --yes @celo/[email protected] --help
npx --yes @celo/[email protected] whoami
npx --yes @celo/[email protected] mcp install --client all

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