Reconciliation

A one-dollar hold closes at 85 cents and returns 15 to the grant

The kernel holds 100 cents against the grant, the query uses 85 units, and the adapter captures 85. The same reconcile step decides every other outcome a held call can have.

The capture and the budget are separate facts. The adapter captures 85 cents on the rail, which unwinds the rest of the hold in one operation; the budget hold closes at actual_cost.min(charge.cost_charged), here min(85, 100), so the next call sees 15 cents of headroom. A zero observed cost calls release in place of capture, and an overspend never exceeds the authorized charge on the budget.

Three conditions close the hold at the full authorized charge. cross_currency_failed applies when the tool reports cost in another currency and no oracle rate resolves. payment_already_settled applies when the authorization was PrepaidFinal, which skips capture entirely. cost_overrun applies when the reported cost exceeds the authorized charge: the receipt records the reported amount while the budget keeps the authorized one. The currency failure and the overrun make no rail call and set settlement_status to Failed with the authorization id as payment_reference; a prepaid-final receipt settles from its authorization. A capture or release that errors records the same Failed status against the authorization id.

Quote, meter, and rail result keep separate records

A quote is an estimate, a meter is a measurement, and a rail result reports what the payment operation did. The receipt records each one where an auditor can trace it.

The quote and the usage evidence sit under the reserved governed_transaction key; the charge sits under financial. Read the recorded amount together with its settlement status and the original rail result, because the number alone proves no transfer. The worked call's receipt, the buyer's order-history query against your orders server under its USD 5.00 grant:

{
  "governed_transaction": {
    "intent_id": "intent-basalt-orders-001",
    "intent_hash": "[64 hex, GovernedTransactionIntent::binding_hash]",
    "purpose": "Basalt order-history lookup",
    "server_id": "orders",
    "tool_name": "sql",
    "metered_billing": {
      "settlementMode": "hold_capture",
      "quote": {
        "quoteId": "quote-orders-001",
        "provider": "orders",
        "billingUnit": "query-unit",
        "quotedUnits": 100,
        "quotedCost": { "units": 100, "currency": "USD" },
        "issuedAt": 1747776000
      },
      "usageEvidence": {
        "evidenceKind": "acp",
        "evidenceId": "[facilitator usage record id]",
        "observedUnits": 85
      }
    }
  },
  "financial": {
    "grant_index": 0,
    "cost_charged": 85,
    "currency": "USD",
    "budget_remaining": 415,
    "budget_total": 500,
    "delegation_depth": 0,
    "root_budget_holder": "[issuer public key, hex]",
    "payment_reference": "[facilitator transaction id]",
    "settlement_status": "settled"
  }
}

Cost metering observes compute time, data bytes transferred, and any per-call upstream API cost. Every amount is a MonetaryAmount of exactly units and currency in minor units, so a sub-cent rate is expressed through the unit count: 1,000 rows priced at 100 cents.

Seven rail answers fold into three receipt statuses

The kernel records what the rail reports. to_receipt_status maps the seven values of RailSettlementStatus onto the receipt's SettlementStatus.

Authorized, Captured, and Pending become Pending; Settled, Released, and Refunded become Settled; Failed stays Failed. A facilitator that answers captured where settled was expected leaves the receipt pending and its ledger entry asking for action. Because three cash flows read as Settled, keep the original rail status beside the receipt before classifying the money.

A settled status reports the rail. Whether a receipt proves spend is decided by is_authoritative_spend_receipt: it requires a mediated allow, a budget hold whose terminal mutation was a reconcile, a signed execution nonce (chio.execution_nonce.v1) that binds the exact call, and an admitted kernel key. The frozen receipt profile it pins is chio.mediated_spend.v1, and BudgetGuaranteeLevel records how strong the store behind the hold was.

Read more in Authoritative spend, which holds the full conjunction and the guarantee levels, and in Budgets and metering, which teaches the lifecycle against a grant's budget.

An unfinished payment closes with new evidence beside the original receipt

Delivery and money are separate facts, and each moves on its own axis. After an unknown outcome, only a co-signed MutuallyAgreedUnknown releases held money; for a known return with a capture pending, only a ContractualCaptureWaiver stops the capture.

A hold on the operation blocks finalization, receipts, and delivery until it clears, and the co-signed successor still passes. Every finalizer reads the effective payment journal first. A signer that has rotated signs with its current key and binds its original identity. Each open case below closes on the evidence named in it:

• Zero cost under a reversible hold. Release the authorization and inspect the bound response. The release result and the reconciled zero-cost budget record close the case; no beneficiary payment is implied.
• Capture pending. Keep the authorization and transaction references and follow the provider's observation path until a terminal rail result links to the original capture and receipt.
• Terminal request timed out. Resolve the original operation with the provider before retrying under its idempotency contract. A missing HTTP response is an unknown outcome, and the kernel never dispatches an unknown outcome again.
• A settled operation needs reversal. Use the adapter's refund and confirm what it executed. For x402, a local terminal result is no proof of a remote refund.
• Receipt marked Failed. Investigate the loss record and choose a recovery action. New outcome evidence and an explicit reconciliation record close the case; the signed receipt stays as issued.
• Loss marked Reconciled or Ignored. Retain why attention was cleared and any supporting evidence. Either state clears the loss projection; Ignored records no recovered money.
• Observed cost contested. The dispute follows the claims path.

Settlements through the web3 module can stall on confirmations, a dispute window, or a chain reorganization. A watchdog job (chio.settlement-automation-job.v1) pins one dispatched settlement or bond by a state fingerprint and fires on a cron schedule. assess_watchdog_execution refuses an execution whose job, timing, fingerprint, or delay disagrees with the job, and every built job requires the operator's override. The operator's signer broadcasts whichever SettlementRecoveryAction the case needs.

Read more in On-chain settlement, which covers escrow states and finality.

Projections over receipts show open exposure and close the billing period

Across many settlements in flight, an operator needs one position per currency. chio trust exposure-ledger export projects the matching receipts into a signed chio.credit.exposure-ledger.v1 report. The positions below are the worked call plus one 60-cent capture still pending.

chio trust exposure-ledger export --capability cap-01a8…31f2 --json \
  | jq '.body.positions'

[
  {
    "currency": "USD",
    "governedMaxExposureUnits": 200,
    "reservedUnits": 100,
    "settledUnits": 85,
    "pendingUnits": 60,
    "failedUnits": 0,
    "provisionalLossUnits": 0,
    "recoveredUnits": 0,
    "quotedPremiumUnits": 0,
    "activeQuotedPremiumUnits": 0
  }
]

Each receipt adds its governed max_amount to governedMaxExposureUnits and files its financial amount into exactly one of settled, pending, or failed by its SettlementStatus; a NotApplicable receipt adds nothing. A Pending or Failed receipt whose reconciliation state is still Open or RetryScheduled carries action_required, which counts its governed amount in reservedUnits, and a failed one also in provisionalLossUnits.

A failed settlement that never recovers passes through the credit loss lifecycle: bond impairment, then a facility drawdown for the residual, then a reconciliation state of Reconciled or Ignored that takes the amount off the next report. Recoveries reach recoveredUnits only through that lifecycle. The web3 settlement module is off by default; credit is part of every build.

The billing export closes the period. create_billing_export turns caller-selected receipts into a chio.billing-export.v1 export with one flat BillingRecord per receipt. The worked call becomes a record with cost_units of 85 and currency of "USD"; the 15 cents returned to the grant never appear.

• Live monitoring. Run the exposure ledger against an anchor and watch pendingUnits against governedMaxExposureUnits, and reservedUnits as the backlog of receipts nobody has closed out.
• Periodic close. Build the billing export at the billing cadence from the receipts that period covers.
• Watchdog review. Inspect watchdog executions whose outcome is other than Executed; anything in ManualOverrideRequired is the action queue.
• Loss documentation. When a failed settlement becomes a confirmed loss, drive the bond impairment if one applies, then move the receipt's reconciliation state off Open.
• Facility review. Cross-check reconciled volume against the configured facility ceiling and rebalance if utilization stays high.

A successful export covers the receipts you passed. State which unresolved or excluded payments remain outside it, and keep the receipt, the authorization and transaction references, the original rail status, the budget adjustment, and any recovery record together for review.

Read more in Export billing records, the operator workflow, and in Audit APIs, which shows how an auditor reads these receipts.

Next: close a billing period