Docs

Lines

A line names one service a budget may pay and caps what that service takes each period. With any line set, the agent key pays the services named and nothing else.

What a line holds

PartWhat it is
The serviceIts payout address: the payTo its x402 offers name, where a channel pays out.
The capThe most the service may take in one period, in the mint’s base units. Above zero.
Spent this periodWhat the service has taken since the period started. A new period starts it at zero, with no transaction.

The lines sit inside the budget’s limit, not beside it. A payment has to fit both: what remains of the budget’s limit, and what remains of that service’s line. Caps need not add up to the limit; the limit still holds over all of them together.

What the key can do on lines

The first line puts the budget on lines, and the panel shows On lines beside its state. In the same transaction the agent key’s delegation is revoked, and while the budget has a line it is never approved again: the program grants it nothing. A budget on lines pays only through payment channels, which the program opens as the budget account’s owner, and only to a service with a line.

The agent triesOn lines
A metered call (upto) or a session (batch-settlement) to a service with a linePaid, the deposit charged to the line and to the budget.
The same, past what the line may still take this periodRefused. The SDK throws LineTripped; the program refuses with LineOverCap.
A channel to a service with no lineRefused. The SDK throws NoLine; the program refuses with NoLine.
An exact payment, to anyoneRefused. The SDK throws NoLine, and a transfer built by hand fails in the token program: the key holds no delegation.

So a budget on lines pays services that sell by upto or batch-settlement through Breaker’s facilitator (https://facilitator.breaker.to). A service that sells only by exact cannot be paid from it.

A leaked key

A key handed to someone else, with a funded wallet of their own, trying every way out of the budget:

Limit 1.00Moves to the holderMoves at all
A budget not on lines1.00, by exact, to any address1.00
A budget on lines, one line of 0.2000.20, all of it to the named service

Measured with dev/leak.mjs: an exact transfer to the holder’s own account, a channel paying the holder, and a channel to the named service past its line, each refused; a channel to the named service, settled and sealed by the holder as payee and voucher signer, paid 0.20 to that service.

A payment on lines

  1. The SDK reads the budget and sees the Lines account. It takes only streamed offers, and reads the line of the offer’s payTo.
  2. A deposit is sized to fit what remains of the budget’s limit and of the line, and the balance. For a session the SDK deposits up to sessionCalls calls within that room.
  3. The agent key signs open_channel or top_up_channel naming the service as the channel’s one recipient at the full share. The program charges the deposit to the line and to the budget, or refuses.
  4. When the channel is distributed, what the service was not paid comes back to the budget account, and goes back to the line as it goes back to the budget: only what that line was charged for, in the same period.
import { breaker, NoLine, LineTripped } from '@breaker/sdk'

const agent = breaker({ budget, key })
try {
  return await agent.fetch(url)
} catch (e) {
  if (e instanceof NoLine) return skip(e.service)               // not a service this budget pays
  if (e instanceof LineTripped) return retryAt(e.resetsAt)      // this service's line is spent for the period
  throw e
}

status() carries lined: true on a budget on lines, and its remaining is the budget’s limit less this period’s spend since the last reset.

Each control on lines

ControlOn a budget with lines
Add lineAdds a line, or sets a new cap on a service that has one. The first line needs the budget to have no channel open, and revokes the key’s delegation.
Remove lineRemoves the line; that service can no longer be paid. Removing the last one takes the budget off lines and approves the key for what remains of the limit.
ChangeThe new limit holds over the lines. The key stays without delegation.
ResetThe budget’s full limit, now. Each line keeps its spend for the period.
Switch offAs on any budget: open channels are asked to close, and nothing new can open.
Switch onPayments through the lines resume; the key stays without delegation.
Rotate keyThe new key pays through the same lines.
The rollA fresh limit; each line starts the period at zero the first time it is charged.
Draw from the reserveFills the balance up to what remains of the limit.
Close budgetRemoves every line in the same transaction, then closes. A budget with a channel open still cannot close.

Lines start on a budget with no channel open, so every channel of a budget on lines is charged to its line. Switch the budget off and let its channels close before the first line.

What it costs

A line and the budget’s Lines marker are small accounts whose rent the owner pays when the line is added. Each line’s rent comes back when it is removed, and the marker’s with the last line. No Breaker fee.

The instructions and accounts are on the Program page; the builds and the budget’s lines on the API page.