Skip to content
Download

Pay per request

You can call the API with no account and no key: pay for each request in bitcoin over Lightning. This uses x402, an open standard for paying for HTTP requests.

Beta.

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

How it works

  1. Send the request with no Authorization header.
  2. The answer is 402 Payment Required. Its body says the price, and its PAYMENT-REQUIRED header holds a Lightning invoice for exactly that request.
  3. Pay the invoice with any Lightning wallet. The wallet gives you a proof of payment (the preimage).
  4. Send the same request again, byte for byte, with the proof in a PAYMENT-SIGNATURE header. You get the answer, with a PAYMENT-RESPONSE header saying the payment was accepted.
curl -i 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...

{"error": {"type": "payment_required", "message": "This request costs up to 3 sats ($0.0021). ..."},
 "price_sats": 3, "price_usd": "0.0021", "x402Version": 2}

The PAYMENT-REQUIRED header is base64 JSON. Its accepts[0] is the payment terms; accepts[0].extra.invoice is the invoice. To send the proof, base64-encode {"x402Version": 2, "accepted": <accepts[0]>, "payload": {"preimage": "<hex>"}} as the PAYMENT-SIGNATURE header.

With the Payment scheme (MPP)

When the API takes it, the same 402 also carries a WWW-Authenticate: Payment challenge (method lightning, intent charge) for the same invoice. Clients that speak the Payment scheme, such as lnget and mppx, pay it and send the same request again with Authorization: Payment <credential>: the challenge echoed back and payload.preimage, as base64url JSON. The answer carries a Payment-Receipt header.

One invoice pays once. After it pays one request, the same preimage is refused whichever header carries it.

From the command line

The openagents command pays from your OpenAgents wallet and does all four steps:

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

--max-msat is the most you will pay, in millisatoshis (10000 is 10 sats). It refuses an invoice above it.

What you pay

  • The most the request could cost. We price the request before it runs: the model's price from the rate card, plus our margin, for the most input your request can hold and the most output it allows. Set max_output_tokens to lower the price.
  • Whole sats, rounded up, at the bitcoin price the rate card shows.
  • No refund of the unused part. The answer's actual cost is in its x-openagents-cost-usd header, but the payment covers the request as quoted. To pay only what each answer costs, use a key with credit instead.
  • No answer, no charge. If every provider fails before answering, or no provider can take the request, send the same request with the same PAYMENT-SIGNATURE again: the payment still counts.
  • One payment, one answer. A proof is used once, and only for the request it was issued for. A different body needs a new invoice.

What needs a key

A paid request covers one model turn and keeps nothing. Stored responses (store, previous_response_id), hosted tools such as web search, and the WebSocket need an API key.

The API's description

Every route is described in OpenAPI 3.1 at https://api.openagents.com/v1/openapi.json.