Pay per call with x402

Call a model with no account and no key: pay for each request in bitcoin over Lightning, with x402. Bitcoin only: there is no card, stablecoin, or other chain.

Paying per request is off on this API right now; use an API key.

Step 1: send the request with no key

curl -si https://api.openagents.com/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model": "google/gemini-3.8-flash", "input": "Say hello.", "max_output_tokens": 200}'

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi...
Cache-Control: no-store
x-request-id: req_...

{"error": {"type": "payment_required", "code": "payment_required",
  "message": "This request costs up to 3 sats ($0.0021). ...", "param": null},
 "x402Version": 2, "docs": "https://openagents.com/docs/api/for-agents",
 "methods": [{"id": "...", "name": "...", "protocol": "x402", "rail": "lightning",
              "challenge": "PAYMENT-REQUIRED", "credential": "PAYMENT-SIGNATURE", "receipt": "PAYMENT-RESPONSE", "...": "..."}],
 "price_sats": 3, "price_msat": "3000", "price_usd": "0.0021"}

The price is the most this request could cost, in whole sats. Set max_output_tokens to lower it.

Step 2: pay the invoice

PAYMENT-REQUIRED is base64 JSON. accepts[0] is the payment terms and accepts[0].extra.invoice is the Lightning invoice. Pay it with any Lightning wallet and keep the preimage (hex).

echo "$PAYMENT_REQUIRED" | base64 -d | jq '.accepts[0]'

Step 3: send the same request with the proof

Send the same body, byte for byte, with a PAYMENT-SIGNATURE header: base64 of {"x402Version": 2, "accepted": <accepts[0]>, "payload": {"preimage": "<hex>"}}.

PROOF=$(jq -cn --argjson accepted "$ACCEPTED" --arg preimage "$PREIMAGE" \
  '{x402Version: 2, accepted: $accepted, payload: {preimage: $preimage}}' | base64)
curl -s https://api.openagents.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: $PROOF" \
  -d '{"model": "google/gemini-3.8-flash", "input": "Say hello.", "max_output_tokens": 200}'

The answer is the model's, with these headers:

Header	Meaning
`PAYMENT-RESPONSE`	The payment was accepted
`x-openagents-receipt`	Our receipt id
`x-openagents-cost-usd`	What the answer actually cost

When the API takes the Payment scheme, the same 402 also has a WWW-Authenticate: Payment challenge for the same invoice; send Authorization: Payment <credential> instead, and the answer has Payment-Receipt.

Do all three steps with the command

openagents inference google/gemini-3.8-flash "Say hello." --pay x402 --max-msat 10000

It pays from your OpenAgents wallet and refuses an invoice above --max-msat (10,000 msat is 10 sats). --max-fee-msat caps the routing fee. It can't be used with a key.

Rules

Rule	Detail
One proof, one answer	A preimage pays once, for the request it was issued for
No answer, no charge	If no provider answers, send the same request and proof again
No refund of the unused part	You pay the quoted price; use a key with credit to pay only what each answer costs
What needs a key	Stored responses (`store`, `previous_response_id`), hosted tools such as web search, and the WebSocket
Errors	`402 payment_required` with no proof; `402 payment_refused` with a proof we can't accept, with `reason`

The ways to pay are also listed by the API itself: the methods field of every 402, x-payment-info in the OpenAPI description, and the docs MCP server's list_payment_methods tool.

Pay any x402 server

The same command pays other x402 servers from your wallet:

openagents x402 fetch https://example.com/paid --max-msat 5000