Metering without surprises

Two tables, one truth

Usage rows record what happened: user, key, model, inputTokens, outputTokens, priceUsd, costUsd, status, latencyMs, timestamp. CreditLedger rows record money movement: negative amounts for billed usage, zero-amount rows for fully free holder calls, positive amounts for topups.

The invoice for any period is a pure function of these two tables: sum priceUsd over Usage in range, reconcile against sum amountUsd over CreditLedger. Nothing is derived from config at read time, so a margin change tomorrow cannot rewrite yesterday.

Holder quota burns first

$HOODERAI holders unlock weekly free tokens: $100 of holdings opens 100M tokens/week, scaling linearly to $1000 = 1B/week, on any model. Tiers are detected onchain — balanceOf read via RPC, priced from the Pons launchpad — and locked against flash-loans with a 24-hour hold requirement.

When a call lands, the gateway checks the active tier first: free tokens cover as much of the call as the remaining quota allows, and only the remainder bills credits. A fully covered call writes priceUsd 0 with reason usage-holder-free. A partially covered call pro-rates: billed = price × (uncovered ÷ total). The response carries _hooder with freeTokensUsed and billedUsd so clients can display the split.

_hooder: { model, upstream, upstreamCost,
  freeTokensUsed, billedUsd, holderWeek,
  holderActive, holderReason }

Recomputing an invoice

Pick a user and a week. Sum Usage.priceUsd where status is ok. Separately sum CreditLedger.amountUsd with reason starting usage. The two sums match by construction — every billed call writes both rows in the same handler. Holder-free calls contribute 0 to both, so they never distort the reconciliation.

Upstream cost is stored separately (costUsd from inferhub usage.cost when present, else price ÷ 1+margin). Margin is therefore auditable per row: price − cost is the platform take on that exact call.