> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits and billing

> Follow the integer ledger from top-up through reservation, provider calls, and settlement.

<Frame caption="Billing: credit balance and top-up.">
  <img src="https://mintcdn.com/auto-gtm/iXt5uMxsbIiTmJfR/images/console-billing.png?fit=max&auto=format&n=iXt5uMxsbIiTmJfR&q=85&s=d5e42c69817110857b5d6677c17f7483" alt="Billing: credit balance and top-up." width="2880" height="1800" data-path="images/console-billing.png" />
</Frame>

All balances and charges use integer micro-USD. One US dollar is exactly 1,000,000 micro-USD. The pricing snapshot records a version and <code>surplusBps</code>. 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 be <code>active</code>, <code>frozen</code>, or <code>closed</code>. Its summary separates:

| Value       | Meaning                                    |
| ----------- | ------------------------------------------ |
| Posted      | Net amount committed to the ledger         |
| Held        | Amount reserved for active operations      |
| Available   | Spendable amount after holds               |
| Next expiry | Earliest future expiry among positive lots |

## Ledger entries

The append-only ledger uses:

| Type                    | Effect                               |
| ----------------------- | ------------------------------------ |
| <code>topup</code>      | Add purchased or mocked local credit |
| <code>grant</code>      | Add granted credit                   |
| <code>debit</code>      | Charge an operation                  |
| <code>refund</code>     | Return credit                        |
| <code>expiry</code>     | Remove unused expired credit         |
| <code>adjustment</code> | Record an authorized correction      |

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

<Steps>
  <Step title="Create an idempotent operation">
    The service hashes the request inputs and resolves the operation identity.
  </Step>

  <Step title="Reserve">
    The estimate is held across available lots. Insufficient balance returns HTTP 402 with required and available amounts.
  </Step>

  <Step title="Issue a lease">
    The worker receives a signed operation token and an active budget lease.
  </Step>

  <Step title="Authorize each call">
    Before every paid provider call, the worker asks the lease to authorize the next amount.
  </Step>

  <Step title="Record cost">
    Provider usage becomes an idempotent cost event under the operation.
  </Step>

  <Step title="Seal and settle">
    The manifest is sealed, actual cost is debited, and unused holds return to the lots.
  </Step>
</Steps>

## 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.

<Warning>
  A provider call already authorized and sent can still be charged even if the surrounding job is cancelled afterward.
</Warning>

## Top-up

The current top-up endpoint is explicitly a mock. It is session-only, requires <code>credits:topup</code>, 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 caps <code>limit</code> 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:

```text theme={null}
reservation -> lease authorizations -> cost events -> manifest -> debit
```

## Expiry behavior

A hold can temporarily protect a lot from expiring. Settlement returns unused funds to their original lots, where normal expiry applies. Check <code>nextExpiryAt</code> before launching a large operation against short-lived grants.