Docs
Recipes
Working code for the things agents do with a budget. Each one uses only what the SDK page documents.
One agent, every request
Hand agent.fetch to whatever makes the agent’s requests. Free endpoints pass through untouched; paid ones are paid from the budget.
import { breaker } from '@breaker/sdk'
const agent = breaker({ budget: process.env.BREAKER_BUDGET, key: process.env.BREAKER_AGENT_KEY })
const tools = {
search: (q) => agent.fetch(`https://api.example.com/search?q=${encodeURIComponent(q)}`).then((r) => r.json()),
page: (url) => agent.fetch(`https://api.example.com/fetch?url=${encodeURIComponent(url)}`).then((r) => r.text()),
}
A budget per agent
Give each agent its own budget and key. Each then has its own limit, its own switch and its own ledger, and one agent reaching its limit leaves the others paying.
const research = breaker({ budget: process.env.RESEARCH_BUDGET, key: process.env.RESEARCH_KEY })
const support = breaker({ budget: process.env.SUPPORT_BUDGET, key: process.env.SUPPORT_KEY })
Check before a job
status() is one read of the chain. Use it to decide whether a job fits before starting it.
const { state, remaining, balance, periodEnd } = await agent.status()
const room = BigInt(remaining) < BigInt(balance) ? BigInt(remaining) : BigInt(balance)
if (state !== 'live' || room < jobCost) {
return { ok: false, retryAt: periodEnd }
}
Plan inside what remains
const { remaining, periodEnd } = await agent.status()
const calls = Number(BigInt(remaining) / pricePerCall)
// do at most that many now, the rest after periodEnd
Cap a single payment
maxPayment is the most one call may cost, in base units. A price above it throws PaymentTooLarge before anything is signed, whatever the budget holds.
import { breaker, PaymentTooLarge } from '@breaker/sdk'
const agent = breaker({ budget, key, maxPayment: '20000' }) // 0.02 USDC a call
try {
await agent.fetch(url)
} catch (e) {
if (e instanceof PaymentTooLarge) console.log(`asked ${e.price}, cap ${e.maxPayment}`)
else throw e
}
Handle a trip
BudgetTripped carries what remains, the price that was asked and the time the budget resets. Tell the agent, so it can choose something cheaper or stop.
import { BudgetTripped } from '@breaker/sdk'
try {
return await agent.fetch(url)
} catch (e) {
if (!(e instanceof BudgetTripped)) throw e
return { error: 'budget', remaining: e.remaining, price: e.price, resetsAt: e.resetsAt }
}
Wait for the roll
For work that can wait, sleep until the period turns over and go again.
async function paid(url) {
for (;;) {
try {
return await agent.fetch(url)
} catch (e) {
if (!(e instanceof BudgetTripped)) throw e
await new Promise((r) => setTimeout(r, new Date(e.resetsAt) - Date.now() + 2_000))
}
}
}
Tell the owner what happened
Each error names its cause, so one handler can say what the owner should press.
import { BudgetExpired, BudgetOff, BudgetTripped, InsufficientBalance, PaymentTooLarge } from '@breaker/sdk'
function explain(e) {
if (e instanceof BudgetTripped) return `At the limit until ${e.resetsAt}. Reset to lift it now.`
if (e instanceof InsufficientBalance) return `The budget holds ${e.balance}; this costs ${e.price}. Fund it.`
if (e instanceof BudgetOff) return 'Switched off, or the key was replaced. Switch on, or update the key.'
if (e instanceof BudgetExpired) return `Expired at ${e.expiredAt}. Change the expiry.`
if (e instanceof PaymentTooLarge) return `This call costs ${e.price}, above the cap of ${e.maxPayment}.`
throw e
}
Send a body
fetch takes what fetch takes. The request is sent again with the payment attached, with the same method, headers and body.
const res = await agent.fetch('https://api.example.com/inference', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ model: 'small', input: text }),
})
Use your own RPC
Pass rpcUrl and every read goes through it. Networks and tokens has what the SDK uses without one.
const agent = breaker({ budget, key, rpcUrl: process.env.SOLANA_RPC_URL })
Read a key from a file
import { readFileSync } from 'node:fs'
const agent = breaker({ budget, key: readFileSync('agent.json', 'utf8') })
Watch a budget from a script
The panel’s stream is open to a browser or any EventSource client. Each event says a payment settled or a budget changed. Live events has every event and its fields.
const events = new EventSource(`https://api.breaker.to/v1/panels/${panel}/events`)
events.addEventListener('payment', (e) => console.log('paid', JSON.parse(e.data)))
events.addEventListener('budget', (e) => console.log('changed', JSON.parse(e.data)))