Spend governance & API keys

Wallet-issued keys with per-key budgets, enforcement, and audit trails. Govern an agent fleet without trusting it.

Spending on Omnious never requires an API key: the payment signature is the credential. What a key gives you is governance. It tags which app or agent a request came from, lets that app read its own usage without hand-signing queries, and, when you attach a budget, becomes the leash on an agent you have handed money to.

Wallet-issued keys

Keys are minted self-service from the developers surface of the web app (the API tab) or via createApiKey in the SDK. Your wallet is the identity: one fixed EIP-712 signature is the management credential for creating, listing, re-budgeting, and revoking keys. The bearer key value is shown exactly once at creation; the router stores only a SHA-256 hash, so a leaked database leaks no keys. The key rides requests as an x-api-key header alongside the payment signature.

The crucial asymmetry: a key cannot spend. A leaked key can read that wallet's usage aggregates and inflate a request counter, nothing more, because spending always requires a payment signature from the wallet itself.

Per-key budgets and enforcement

A key may carry a budget: a USDC cap over a rolling daily, weekly, or monthly window. Once the key's attributed spend reaches the cap, requests carrying that key are refused with 403 key_budget_exhausted, and every keyed response reports x-key-budget-remainingso an agent can see its own runway. Requests without the key are untouched; the wallet can always spend. The gate contains a runaway agent that was given the key, not an adversary holding the wallet's signer. Enforcement happens at admission on billed actuals, so one in-flight request can overshoot by at most its own charge before the gate closes.

The audit trail

Every request carrying a key is attributed to it individually, and GET /v1/keys/:id/receiptspages through that key's history, newest first. Each row resolves through /v1/receipts/:id to the signed usage record, hashed into the hourly on-chain anchor. Per-agent accounting is not a report you assemble later; it is the settlement layer read back.

Client-side spend caps in the SDK

new OmniousClient({
  spendCaps: { perQueryUsd: 0.05, perHourUsd: 1, perDayUsd: 5 },
});

These bind before any money moves: the cap is checked against the 402's worst case before anything is signed, and a query that would blow a window is refused with an OmniousError of code spend_cap, no payment made. The router additionally enforces routing.max_price_usdc per request server-side, in-auction. Three layers, then: a client refusal before signing, a server refusal before quoting above your cap, and the key budget on attributed actuals.

Why this matters for agent fleets

An autonomous agent with a wallet is an unbounded liability; an agent with a budgeted key is a bounded one. Give each agent its own key and cap, and it can spend only what its key allows, while every unit it does spend lands in a signed, anchored record you can audit per agent. You govern the fleet without trusting any member of it.