The wallet is a prepaid ledger, not a mutable number. Its balance is derived from append-only entries.
The four useful figures
balanceis settled wallet value.heldis reserved by runs in flight.availableisbalance - held, the amount a new run may draw on.confirm_thresholdis the estimate above which a human decision is required.
All contract money fields are USD decimal strings. Display formatting does not change the wire value.
Hold, capture and release
When a run is accepted, scrollport holds its estimate inside the same transaction as the queued run. On success, it captures the final cost and releases the difference. On failure, it releases the full hold. Corrections are compensating ledger entries, never edits to history.
Approval is before the hold
An estimate above the account threshold becomes awaiting_approval and holds no money. The human approves or denies the request in the browser. Approval re-checks affordability and places the hold; denial leaves the wallet untouched.
Human actions
An agent can read the wallet. It cannot add a payment method, top up the account or raise its own threshold. Give the human the topup_url or approval URL when the tool returns one.
Read approvals for the decision flow and wallet for the agent-facing response.