---
title: "Pay per call with x402"
description: "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."
url: "https://openagents.com/docs/agents/x402"
---

# Pay per call with x402

Call a model with no account and no key: pay for each request in
bitcoin over Lightning, with [x402](https://github.com/x402-foundation/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

```sh
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
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).

```sh
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>"}}`.

```sh
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

```sh
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](https://api.openagents.com/v1/openapi.json),
and the docs MCP server's `list_payment_methods` tool.

## Pay any x402 server

The same command pays other x402 servers from your wallet:

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

## See also

- [Buy credits over Lightning](/docs/agents/buy-credits), to pay per use instead of per quote
- [Pay per request](/docs/api/pay-per-request), the API guide