Billing & Sats Pricing
Exactly how per-query pricing works — sats ledger, live FX conversion, the FX buffer, per-component charges, and audit trails.
AI Gateway billing is designed so you can answer one question at any moment: what did this query cost me, exactly? Every charge is computed from the upstream usage report, itemized per component, and recorded with the FX rate used.
The sats ledger
Your AI balance is held in sats (GET /ai/balance). Topups add sats
(+5% Lightning bonus); queries deduct sats. There are no expirations and no
subscriptions.
How a query is priced
- Listed price (what you pay). Each model's listed price is the upstream provider's price plus the platform markup (a small percentage), stored in the catalog. You always see listed prices — never raw costs.
- Sats conversion at charge time. When a query settles, each billable component is converted from USD to sats at the current BTC/USD rate plus a small FX buffer (default 3%). The buffer absorbs BTC dips between your topup and your spend so volatility never eats your value — or ours.
- Charge = Σ components, rounded up to the whole sat. You never pay for failed calls.
Billable components
| Component | When it applies |
|---|---|
prompt | Input tokens (your message + history) |
completion | Output tokens (the model's reply; includes reasoning) |
input_cache_read | Cached prompt tokens (much cheaper — automatic) |
input_cache_write | Cache-write premium on supported models |
image | Input images on vision models |
web_search | Native provider web searches |
request | Flat per-request fee (some media models) |
web_search_fee | Our flat add-on when you enable web search |
platform_fee | Flat fee per query on :free models |
Long-context and time-of-day pricing overrides (some models reprice past a
prompt threshold or at peak hours) are evaluated automatically at request
time and flagged on your query record as overrideApplied.
The pre-flight check
Before dispatching, the gateway estimates the minimum your request could cost
(prompt estimate + max_tokens × output rate + add-ons) and requires that
balance. If it's not there you get a 402 immediately — with
required_sats, balance_sats and the topup link — and nothing is sent
upstream. Lower max_tokens lowers the requirement.
Audit trail
Every query writes a ledger row you can read back any time
(GET /ai/usage):
{
"model": "anthropic/claude-sonnet-5.5",
"tokensIn": 1200,
"tokensOut": 380,
"usageBreakdown": { "cache_read": 4000, "reasoning": 0, "web_searches": 1 },
"priceBreakdown": { "prompt": 4, "completion": 7, "cache_read": 1, "web_search_fee": 2 },
"costSats": 14,
"fxRate": 80423,
"status": "success"
}priceBreakdown shows the exact sats charged per component; fxRate is the
BTC/USD rate used for that charge. Aggregates are at
GET /ai/usage/summary.
Free-model fee
:free models cost nothing upstream but are provider rate-limited. A small
flat platform fee per query (default 2 sats) keeps the tier sustainable.
Web search fees still apply on free models (search costs the provider).
FX buffer, in one paragraph
The buffer (default 3%, operator-configurable) is added when converting your
listed USD price to sats. If BTC drops between your topup and your queries,
your sats still buy the same queries — the buffer absorbs the drift instead
of passing it to you or to the platform's OpenRouter bill. It's small,
visible in GET /ai/rate, and always included in the displayed sats price.