Billing & Credits

Prepaid credits, the 3% top-up fee, usage at provider cost, cache pricing, budget caps, and cost visibility per response.

Xantly billing is prepaid and usage-based. There are no subscriptions, tiers, or seats: you top up a credit balance, and every request draws it down at the exact price the upstream provider charges. Optional budget caps let you bound spend per month.

How pricing works

What	Price
Top-up	Any amount from $5 to $10,000, plus a 3% platform fee charged upfront (pay $103, receive $100 in credits)
Routed usage	Exact provider cost, the same per-token price the provider charges, no markup
Cache and memory hits	Flat $0.25 per million tokens served, on every cache layer, instead of the provider price

The 3% top-up fee is the only platform fee on routed usage. It is shown transparently at checkout before you pay. $100 of credits buys exactly $100 of provider usage.

Credit balance

All usage is drawn from your organization's prepaid credit balance:

Credits are denominated in USD cents (credit_balance_cents)
Top up any amount from $5 to $10,000 from the billing dashboard
Credits are consumed post-request, once actual token usage is known
Every top-up, usage debit, and refund appears in the append-only credit ledger

Auto-recharge

Optionally, set a balance threshold and a recharge amount in the dashboard. When your balance drops below the threshold, Xantly automatically tops up your chosen amount using your saved card, with the same 3% fee applied. Auto-recharge is off unless you enable it, and you can turn it off at any time.

Monthly budget limits

In addition to the credit balance, you can set a monthly spend cap in USD from the dashboard:

Budget type	Applies to
`monthly_budget_usd`	All requests (general)
`voice_monthly_budget_usd`	Voice API requests (`/v1/voice/*`)
`maker_monthly_budget_usd`	Reliability/maker API requests

If a category budget is not set, the general monthly_budget_usd applies as a fallback. If no budget is set at all, only your credit balance bounds spend. Budget caps are a safety net, not a fee: they simply stop requests once the cap is reached.

402 Payment Required

When your credit balance is exhausted, or a request would exceed a monthly budget cap, the gateway returns 402 Payment Required:

{
  "error": {
    "message": "Credit balance exhausted. Add credits to continue.",
    "type": "billing_error",
    "code": "insufficient_credits",
    "top_up_url": "https://app.xantly.com/dashboard/billing",
    "suggested_amounts": [10, 25, 50, 100]
  }
}

Field	Description
`error.code`	`"insufficient_credits"` for an exhausted balance; `"budget_cap_reached"` for an organization monthly spend cap; `"api_key_budget_exceeded"` for a per-key cap
`error.top_up_url`	Dashboard URL to add credits
`error.suggested_amounts`	Suggested top-up amounts in USD (you can top up any amount from $5 to $10,000)

Soft-limit warning headers

When you approach a configured monthly budget cap (90% or more used), responses include warning headers:

Header	Value	Description
`x-budget-warning`	e.g. `"94%"`	Percentage of your budget cap consumed this month
`x-budget-remaining`	e.g. `"3000"`	Remaining headroom before the cap

Use these headers in production to alert your team or trigger a top-up before requests start failing.

response = httpx.post("https://api.xantly.com/v1/chat/completions", ...)

warning = response.headers.get("x-budget-warning")
remaining = response.headers.get("x-budget-remaining")

if warning:
    print(f"Warning: {warning} of budget used, {remaining} remaining")

Cost visibility per response

Every response includes cost fields in xantly_metadata:

Field	Description
`cost_usd`	Actual cost for this request in USD (provider price for routed calls, $0.25/1M for cache hits)
`baseline_cost_usd`	What the same request would cost on a fixed frontier-model baseline
`savings_usd`	Cost saved vs. that baseline
`savings_pct`	Savings as a percentage of baseline
`cost_attribution`	`"xantly"` (platform keys) or `"byok"` (your own API key)

Best practices

Set a monthly budget cap in the dashboard as a safety net against runaway usage.
Enable auto-recharge if uptime matters: your balance refills before requests start failing.
Monitor x-budget-warning headers in production, add alerting at 80% so you can act before the cap.
Enable caching (xantly.enable_cache: true, default): cache hits are billed at a flat $0.25 per million tokens instead of the provider price.
Use BYOK for provider-billed workloads: routing through your own API keys means the provider bills you directly and your Xantly credits are not consumed.

Next steps

Rate Limits, RPM and TPM rate limits (separate from billing)
Bring Your Own Key, Route requests through your own provider keys
Chat Completions, xantly_metadata.cost_usd and savings fields