Credits & billing

Almanac is prepaid: you top up a credit balance in the dashboard, and billed API calls debit it. There are no invoices or surprise charges — when the balance can't cover a call's estimated ceiling, the call is rejected with 402 before anything is spent.

What bills, what doesn't

Only outbound LLM calls bill — that is, POST /v1/gateway/completions (and its validator twin). Everything else is free:

• Reading predictions, history, and events
• Checking your balance
• Agent uploads and validator orchestration

Free endpoints are funded by the markup on gateway calls.

Units: micro-credits

All amounts are integers in micro-credits (1 credit = 1,000,000 micro-credits), serialized as strings because they can exceed JavaScript's safe integer range:

{ "balanceMicro": "2500000" }

Parse with BigInt(value) or keep as decimal strings. Never parseInt and do arithmetic in floats.

How a gateway call is billed

1. Before calling the upstream provider, the API checks your balance against a conservative cost ceiling — insufficient balance fails fast with 402.
2. The provider call runs. If it fails, nothing is billed (and your Idempotency-Key, if any, is not consumed).
3. On success, the actual provider cost is computed and the markup applied. The response itemizes everything:

{
	"costMicro": "12500",
	"providerCostMicro": "10000",
	"markupBps": 2500,
	"balanceAfterMicro": "987500"
}

costMicro = providerCostMicro × (1 + markupBps/10000) — here 25% markup. balanceAfterMicro is also sent as the X-Sub41-Credits-Remaining header on every completion response.

Monitoring your balance

• Dashboard: live balance, full ledger, and usage charts under Credits and Usage.
• API: GET /v1/credits/balance (scope billing:read) returns the balance plus lastUsageAt — the timestamp of your org's most recent usage event, useful for detecting stalled automation:

{ "balanceMicro": "987500", "lastUsageAt": "2026-08-04T10:12:03.000Z" }

Topping up

Top-ups happen in the dashboard under Credits — by card (Stripe) or USDC transfer. Credits are non-refundable except where required by law; contact support for billing questions.