Budgets & refunds
Every Dr. Nib run holds its own budget in USDC. The rules are simple and absolute:
- Cap first. You set the cap at configure time. Nothing executes until you approve the plan against it.
- Draw per stage. Search, fetch, scoring, writing — each stage draws its cost plus a 1% platform fee. The fee is taken as money moves, never up front. Agent purchases (tips, paid unlocks, x402 calls) draw the same way with their transaction hashes on the record.
- Never overspend. If the next stage would pass the cap, the run pauses with the balance intact. Raise the cap or end the run — your call.
- Remainder returns. When a run completes, fails, or is ended, whatever is unspent is refunded immediately. There is no holding period.
Estimates are shown before you approve, and the run pauses instead of guessing when a plan has no estimate yet.
The ledger
The budget ledger is append-only and is the only source of truth for a balance:
| Kind | Meaning |
|---|---|
deposit | the cap (raises record only the delta, so the cap can never silently move) |
spend | stages and agent purchases (txRef carries the onchain hash when there is one) |
fee | the 1% platform cut on every draw |
refund | the remainder, written once at settle |
Nothing is ever edited or deleted. Balance = deposited − spent − fee − refunded, always.
Raising the cap
Out of budget mid-run? Raise it (raise-only, always) and a paused run continues from the same stage — finished stages are never charged twice. The approve step also refuses a plan whose estimate exceeds the balance, so a run can’t start already broke.
Audit
reconcile_run (MCP) checks both directions: every ledger-claimed transaction must resolve to a mined Transfer, and every agent-wallet outflow — EOA and spender-mandate alike — must resolve to a ledger row. Gateway deposits (still the agent’s money) are reported separately so they never read as missing.
Onchain escrow (optional)
By default the budget is an offchain allowance. For real-money guarantees, fund an onchain escrow at review: the full cap locks in a contract, and the remainder returns to your wallet automatically at settle.