buy-x402

Buy x402

Purchase access to remote x402-gated services.

Not sure which command? Use go. It probes the URL, reads the 402 to detect what's being sold, and dispatches with the right path, method, streaming mode, and timeout:

# Agent or chat-inference offer — one paid round of work, streamed:
python3 ${OBOL_SKILLS_DIR:-/data/.hermes/obol-skills}/buy-x402/scripts/buy.py go <url> --message 'your task'

# Plain HTTP offer — one paid request:
python3 ${OBOL_SKILLS_DIR:-/data/.hermes/obol-skills}/buy-x402/scripts/buy.py go <url>

go never creates persistent state; for a pre-authorized inference pool it points you at buy. The expert flows underneath, picked by usage shape:

• pay <url> — single-shot. Probe the URL, sign one payment authorization, attach X-PAYMENT, send the request, return the response. Stateless. Use for type:http services and any one-off purchase. Max loss = price of one request. Settlement normally lands only after the request succeeds — but a facilitator can submit the settle tx on-chain and then fail the request. When that happens the failure report prints ⚠️ SETTLEMENT MAY HAVE COMPLETED ON-CHAIN with the tx hash: verify with balance --chain <X> before retrying (mechanism: docs/observability.md, "Verify settlement against the chain"). Applies to pay-agent too.
• pay-agent <url> — single-shot paid streaming agent call. Same payment shape as pay (one auth, X-PAYMENT, max-loss = price), but POSTs to <url>/v1/chat/completions with stream: true and forwards every SSE event verbatim to stdout as it arrives. No --model: a type:agent offer runs its own model (the request model field is ignored), so you only send a prompt. Use this for type:agent ServiceOffers when the calling agent wants to consume the response itself (memory, tool-call traces, partial results) instead of routing it through LiteLLM as a paid alias. Default HTTP read timeout is 1 hour — agent calls can legitimately run for many minutes; override with --timeout <seconds>.
• buy <name> — pre-authorize a budget. Sign N authorizations up front (the buyer pays nothing yet), declare them in a PurchaseRequest CR, let the x402-buyer sidecar redeem them transparently as the agent calls the model through LiteLLM at paid/<remote-model>. Use for long-running paid inference. Max loss = N × price (only as vouchers are spent); runtime path holds zero signer access.
• buy <name> --model <id> --set-default — same as buy above, then adopt paid/<remote-model> as the agent's own primary model, in-pod, by itself: an atomic hermes config set model.default that Hermes re-reads per request (effective next chat turn, no restart, no host-side obol model prefer/obol model sync). Refuses if the model isn't selectable in LiteLLM. Pair with --auto-refill so the primary model doesn't brick when the pre-authorized budget runs out.

Both flows auto-detect the token + transfer method from the seller's 402 response. Currently supported: USDC via EIP-3009 (Base Sepolia, Base Mainnet, Ethereum Mainnet) and OBOL via Permit2 (Ethereum Mainnet).

Multi-currency offers (pick what you pay with). A seller can advertise several payment options (e.g. 1 USDC on Base OR 10 OBOL on Ethereum) in the 402 accepts[] array. probe lists them all. For go, pay, pay-agent, and buy, choose one with --token <SYMBOL> (e.g. go <url> --token OBOL --max-price 10 — the 10 OBOL quote is above the default 1-token per-call ceiling, see below), --network <chain>, and/or --payment-option <N> (the 1-based index from probe). With a single option the choice is automatic. With several and no selector: a TTY prompts; non-interactive runs auto-select the first option the wallet can afford (announced loudly, with the full option list, before any signing). --token/--network also act as a guard — if the filter matches no advertised option, it aborts rather than paying the wrong asset.