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.
| Part | What it is |
|---|---|
| The budget | An account of the Breaker program holding the terms: the limit, the period, the expiry, whether it is on, and the running totals. |
| The budget account | A token account that holds the money. The budget owns it. No wallet key and no agent key does. |
| The allowance | The 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.
| After | The next payment |
|---|---|
| A payment of 0.42 | Succeeds if 0.42 or more remains; what remains is lower by 0.42. |
| Change with a higher limit | The 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 limit | The same sum. If more was already spent than the new limit, nothing remains until the roll. |
| Change of the period | The 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.
| Case | What the roll does |
|---|---|
| The period ended | Closes it with its spend, starts the next, grants the full limit if the budget is on. |
| Several periods passed | Moves straight to the current one. The grid of periods stays fixed to the moment the budget opened. |
| The budget is off | Closes the period and grants nothing. The limit is waiting when you switch on. |
| The budget is past its expiry | Closes 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 budget | Draws when | Takes |
|---|---|---|
| Opened from the reserve | It opens, in the same transaction. | Its first limit. |
| At the roll | The keeper rolls it. | What the spent period used. |
| On Reset, Switch on or Change | You 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.
| After | The allowance | The deposit |
|---|---|---|
| A channel opens for 6.00 with 10.00 remaining | 4.00 remains. | 6.00 sits in the channel. |
| The service settles 2.00 and the channel is distributed | 8.00 remains: the 4.00 unspent comes back. | 2.00 to the service, 4.00 to the budget account. |
| The same, after the roll | The 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 Reset | What 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
| Control | Its open channels |
|---|---|
| Switch off | The 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 off | The same, for every budget it switches off. |
| Expiry | The keeper asks each one to close, then seals and distributes it after its grace. |
| Rotate key | They 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. |
| Withdraw | Moves only what the budget account holds. A deposit comes back to the account when its channel is distributed. |
| Close budget | Refused 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 shows | It means | The next payment |
|---|---|---|
| Live | The key can pay up to what remains this period. | Succeeds within what remains and the balance. |
| Tripped | Nothing 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. |
| Off | You switched it off. The key is revoked. | Fails with BudgetOff until you switch it on. |
| Expired | Past its expiry. | Fails with BudgetExpired until you change the expiry. |
| Closed | The 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.
| Control | The allowance after | Fee |
|---|---|---|
| New budget | The limit. | On the funding |
| A payment | What it was, less the price. | None |
| A channel opened or topped up | What it was, less the deposit. | None |
| A channel distributed | What it was, plus the unspent deposit if it was counted this period. | None |
| Fund | Unchanged. | On the amount |
| Withdraw | Unchanged. | None |
| Fund reserve | Unchanged. | On the amount |
| Draw from the reserve | Unchanged. The balance rises to meet it. | None |
| Change | The new limit less what was spent since the period started or since your last reset. | None |
| Reset | The limit. | None |
| Switch off | Nothing. The delegate is removed, and open channels are asked to close. | None |
| Switch on | The limit less what was spent since the period started or since your last reset. | None |
| Rotate key | What remained, approved to the new key. | None |
| The roll | The limit, if the budget is on and not expired. | None |
| Add line | Nothing: the first line revokes the delegation, and the key pays only through lines. | None |
| Remove line | The last one taken away approves what remains. | None |
| Close budget | Nothing. The account is closed. | None |
The instruction behind each control is on the Program page.