Docs

Budgets

A budget is a token account the agent pays from and does not own. Here is every thing that can happen to one, and what the agent’s next payment does afterwards.

The model

A budget is three things on chain.

PartWhat it is
The budgetAn account of the Breaker program holding the terms: the limit, the period, the expiry, whether it is on, and the running totals.
The budget accountA token account that holds the money. The budget owns it. No wallet key and no agent key does.
The allowanceThe amount the agent key is approved to move out of the budget account. It lives in the token account itself, as the standard token delegate.

Every control in the panel comes down to setting that allowance. A payment is an ordinary token transfer signed by the agent key as the account’s delegate: the token program lowers the allowance by the amount and refuses any transfer above it. The Breaker program is never in the path of a payment, so a payment costs what a token transfer costs and settles as fast.

what the key can pay next  =  the smaller of
    the allowance          (the limit, less what was spent since the period started or the last reset)
    the balance            (what the budget account holds)

Limit and period

The limit is the allowance granted for one period. A period is an hour, a day or a week. The first one starts at the moment the budget opens, and every later one starts exactly one period length after the last, so a budget opened at 14:20 with a day period always turns over at 14:20.

Funding and the limit are separate. A budget may hold a month of money behind a daily limit, or less than one period’s limit. The key can never move more than the account holds.

AfterThe next payment
A payment of 0.42Succeeds if 0.42 or more remains; what remains is lower by 0.42.
Change with a higher limitThe new limit applies at once, less what was spent since the period started or since your last reset. The period does not restart.
Change with a lower limitThe same sum. If more was already spent than the new limit, nothing remains until the roll.
Change of the periodThe new length is measured from the current period’s start.

Trip

A budget trips when a price is above what remains. The SDK reads the budget before it signs, so it throws BudgetTripped with the time the budget resets and sends nothing. A payment built some other way meets the same wall one layer down: the token program refuses a delegate transfer above the allowance, and no money moves.

A smaller payment that still fits what remains goes through. The panel shows a budget tripped when nothing remains, or when the agent has just been refused a price above what remains in this period.

Roll

At the end of a period the budget rolls. One roll transaction records the closed period’s spend, moves the period forward, and approves the full limit again. Breaker’s keeper sends it for every budget at its boundary, timed by the chain’s own clock. The instruction takes no signer, so anyone may send it once the period has ended.

CaseWhat the roll does
The period endedCloses it with its spend, starts the next, grants the full limit if the budget is on.
Several periods passedMoves straight to the current one. The grid of periods stays fixed to the moment the budget opened.
The budget is offCloses the period and grants nothing. The limit is waiting when you switch on.
The budget is past its expiryCloses the period at the expiry and revokes the key.

Each closed period is kept with its start, its end and what it spent. The budget’s page shows them as columns against the limit.

Reset

Reset grants the full limit now, in the middle of a period. The period keeps its end, so the next roll comes when it would have. Use it to lift a trip you have looked at and accept: the agent gets one more limit’s worth of room in this period, and the period’s spend goes on counting from where it was.

Switch

Switch off revokes the agent key in one transaction. It holds from the next slot: the account has no delegate, so the agent’s next payment cannot be built into anything the chain accepts, and the SDK throws BudgetOff. The money stays where it is.

A budget with channels open asks each to close in the same transaction.

Switch on approves what remained when you switched off: the limit less what the key had spent since the period started or since your last reset. Switching off and on again is never a way to a fresh limit.

Switch all off

Switch all off, on the panel, switches off every budget that is on. Each budget is one instruction, packed into as few transactions as they fit, and your wallet signs them together.

Expiry

A budget may carry an expiry. From that time the SDK throws BudgetExpired, the keeper’s roll revokes the key instead of renewing it, and the panel shows the budget expired. Reset and Switch on are closed to an expired budget.

Change with a later expiry, or with none, brings it back: the key is approved again for what remained.

Rotate

Rotate key replaces the agent key. A token account has one delegate, so approving the new key removes the old one in the same instruction. The new key is approved for what remains, and the old key can pay nothing from that transaction on. An agent still holding the old key gets BudgetOff.

The budget’s address comes from the key it opened with and never changes, so its account, its money, its ledger and its address in your agent’s configuration all stay where they are. Only the key in the agent’s environment is replaced.

If a key may have leaked, rotate. The money never moved to the key, so there is nothing to recover. If the budget has a session open, switch it off first: a session keeps the key that opened it as its voucher signer until the channel closes.

Fund and withdraw

Fund moves an amount from your wallet to the budget account, less the fee. Withdraw moves any amount back to your wallet at any time, with no fee, whatever state the budget is in. Neither changes the allowance.

If the balance is below a price, the SDK throws InsufficientBalance and sends nothing. Fund the budget and the same call goes through.

Reserve and draw

The reserve is your panel’s own account for a mint. Fund reserve on the panel moves an amount from your wallet into it, less the fee; Withdraw beside it moves any amount back, with no fee. No agent key can pay from the reserve.

A budget with Draw from the reserve on fills itself from the reserve. Each time its allowance is approved, on the roll, a reset, Switch on or a change, the same transaction moves from the reserve what brings the budget account’s balance up to what its key may now pay. The budget holds what its limit calls for, and the rest of your money waits in one place.

The budgetDraws whenTakes
Opened from the reserveIt opens, in the same transaction.Its first limit.
At the rollThe keeper rolls it.What the spent period used.
On Reset, Switch on or ChangeYou sign the control.What the new allowance calls for.

Opening a budget from the reserve moves no money from your wallet. Turning the setting on or off is one transaction on the budget’s page; off, the budget keeps its balance and you fund it yourself. When the reserve holds less than a budget calls for, the budget takes what is there and draws the rest on its next approval.

Channels

A service that sells by the stream is paid through a payment channel the budget opens: one per metered call, or one per service for a session (x402 has both). The deposit leaves the budget account for the channel, and it counts against the period’s limit as a payment does: the allowance falls by it and the period’s spend rises by it, at the moment the channel opens. A top-up counts the same way.

When the channel is distributed, the service is paid what it settled and the rest comes back to the budget account. If the deposit was counted in the current period, the part that came back is taken off the period’s spend and goes back to the allowance in the same instruction.

AfterThe allowanceThe deposit
A channel opens for 6.00 with 10.00 remaining4.00 remains.6.00 sits in the channel.
The service settles 2.00 and the channel is distributed8.00 remains: the 4.00 unspent comes back.2.00 to the service, 4.00 to the budget account.
The same, after the rollThe full limit, from the roll.4.00 to the budget account as balance. The closed period keeps the whole deposit as its spend.
The same, after a ResetWhat comes back never takes the spend below where it stood at the reset.All of the unspent part to the budget account.

What each control does to an open channel

ControlIts open channels
Switch offThe same transaction asks each one to close. After the channel’s grace it is sealed and distributed, and what it did not pay comes back. Until then the service can still be paid from it, up to its deposit, which was already counted.
Switch all offThe same, for every budget it switches off.
ExpiryThe keeper asks each one to close, then seals and distributes it after its grace.
Rotate keyThey stay open. A session channel keeps the key that opened it as the signer of its vouchers. To cut an old key off a session too, switch off first, then rotate.
WithdrawMoves only what the budget account holds. A deposit comes back to the account when its channel is distributed.
Close budgetRefused while a channel is open. Switch the budget off; once its channels have closed, close it.

While a budget is off or expired, anyone may ask its channels to close, and anyone may seal and distribute a channel once its grace has passed: every step returns money to the budget account and nowhere else. A budget’s open channels and what their deposits still hold are in the API as channels.

Lines

Add line names a service the budget may pay and caps what it takes each period. With any line set, the agent key holds no delegation and pays only the services named, by session or metered call, each within its line and the budget’s limit together. Lines has what each control does on a budget with lines.

Close

Close budget revokes the key, returns the whole balance to your wallet, closes the budget account and the budget, and returns the rent of both. The budget’s payments and periods stay in your ledger. A budget with a channel open cannot close until the channel has.

States

The panel showsIt meansThe next payment
LiveThe key can pay up to what remains this period.Succeeds within what remains and the balance.
TrippedNothing remains of this period’s limit, or the agent was just refused a price above what remains.Fails with BudgetTripped until the roll or a reset.
OffYou switched it off. The key is revoked.Fails with BudgetOff until you switch it on.
ExpiredPast its expiry.Fails with BudgetExpired until you change the expiry.
ClosedThe money is back with you.Fails. There is no account to pay from.

Every control at a glance

What each one leaves approved to the agent key.

ControlThe allowance afterFee
New budgetThe limit.On the funding
A paymentWhat it was, less the price.None
A channel opened or topped upWhat it was, less the deposit.None
A channel distributedWhat it was, plus the unspent deposit if it was counted this period.None
FundUnchanged.On the amount
WithdrawUnchanged.None
Fund reserveUnchanged.On the amount
Draw from the reserveUnchanged. The balance rises to meet it.None
ChangeThe new limit less what was spent since the period started or since your last reset.None
ResetThe limit.None
Switch offNothing. The delegate is removed, and open channels are asked to close.None
Switch onThe limit less what was spent since the period started or since your last reset.None
Rotate keyWhat remained, approved to the new key.None
The rollThe limit, if the budget is on and not expired.None
Add lineNothing: the first line revokes the delegation, and the key pays only through lines.None
Remove lineThe last one taken away approves what remains.None
Close budgetNothing. The account is closed.None

The instruction behind each control is on the Program page.