Billing: credit balance and top-up.
surplusBps. Provider decimal costs round up to micro-USD, the configured surplus is applied, and the result rounds up again before it enters the ledger.
Account and balance
A credit account can beactive, frozen, or closed. Its summary separates:
Ledger entries
The append-only ledger uses:
Positive entries create lots. Consumption uses the earliest expiry first, then creation and identifier order. Active holds take priority over expiry. An expiry job debits only the unused remainder.
Metered operation
1
Create an idempotent operation
The service hashes the request inputs and resolves the operation identity.
2
Reserve
The estimate is held across available lots. Insufficient balance returns HTTP 402 with required and available amounts.
3
Issue a lease
The worker receives a signed operation token and an active budget lease.
4
Authorize each call
Before every paid provider call, the worker asks the lease to authorize the next amount.
5
Record cost
Provider usage becomes an idempotent cost event under the operation.
6
Seal and settle
The manifest is sealed, actual cost is debited, and unused holds return to the lots.
Reservations and leases
Reservation and lease lifetimes come from versioned pricing configuration. Heartbeats extend an active lease within that contract. Expiry sweeps revoke abandoned leases and reconcile their operation. If a lease cannot be extended or cannot authorize the next call, the worker stops before making that call. This is the zero-stop rule.Top-up
The current top-up endpoint is explicitly a mock. It is session-only, requirescredits:topup, accepts a positive integer micro-USD amount, and uses an idempotency key. The Billing UI offers $25 by default to an authorized owner.
Do not describe this endpoint as a production payment processor.
Usage ledger
Usage combines ledger entries with operation manifests. The API defaults to 100 records and capslimit at 500. The current UI requests up to 500 and paginates 25 rows at a time in the browser.
Use the operation identifier to reconcile:
Expiry behavior
A hold can temporarily protect a lot from expiring. Settlement returns unused funds to their original lots, where normal expiry applies. ChecknextExpiryAt before launching a large operation against short-lived grants.