Running agents on Bonded

What you set up

As an operator you run one or more agents. For each agent you create a vault with a spending policy and fund it with the USDC it may spend. You post one bond of your own USDC, and from it you open credit lines to the merchants your agents buy from. Merchants read the bond's coverage on chain before they serve an agent on credit.

The app walks you through it in order under Set up credit. Each step is one transaction you sign in your wallet:

1. Create the operator
2. Create the vault
3. Fund the vault
4. Post the bond
5. Open the line
6. Allow the merchant

The setup covers your first agent. For another one, Add a vault for another agent under Vaults opens its vault, and Open another line asks which vault the line is for.

Before you start, have SOL for fees and USDC for the vault and the bond in the wallet you sign in with (see SOL and USDC), and the session key of your agent: the public key of the keypair your agent signs with. Its developer generates it (Agent developers › The session key).

Create the operator

Create the operator makes your operator account. The wallet that signs becomes its admin key: it alone can create vaults, change their policy, post and withdraw the bond and open lines.

Guardian (optional) names a second key that can freeze your vaults and do nothing else, so a monitoring service or a teammate can stop spending without holding your admin key. Leave it empty if you don't run one; you can freeze from the admin key at any time. The guardian signs in to the app with its own key and finds your vaults under Vaults you guard, each with Freeze the vault.

Create the vault

A vault belongs to one agent. Its policy is checked by the program on every payment the session key makes:

Create the vault opens the vault and its USDC account.

Fund the vault

Fund the vault moves USDC from your wallet into the vault. That balance is what the agent spends: float payments, tab settlements and escrow payments all come out of it. Add more later with Add USDC on the vault's record.

Post the bond

The bond is your own USDC, locked in a program account. It backs the credit lines you open: if a merchant settles a voucher and the vault can't pay it, the bond pays the merchant.

Post the bond moves the amount from your wallet's USDC account into the bond. Add to it later with Add to the bond.

The overview shows three figures for the bond:

• Bond: the USDC in it.
• Reserved by lines: the sum of the limits of your open lines.
• Coverage ratio: the bond, less any withdrawal you've requested, divided by the reserved limits. A line can be opened only while coverage stays at or above your operator's minimum; the program's floor is 33 %, and new operators start at 100 %.

During the beta a single bond holds at most $25,000, and all bonds together at most $250,000.

Open the line

A credit line lets one of your agents buy from one merchant on a tab, billed in arrears, up to a limit.

• Merchant: the merchant's wallet address. Ask the merchant for it; it's the address they sign in with.
• Limit (USDC): the most the agent can owe this merchant at once. Settled amounts free the limit again.
• Expires in (days): when the line closes. After that the merchant can't settle on it either, so its worker settles before then; renew the line to keep it open.

Open the line reserves the limit against your bond. The merchant sees the line under Lines to you as soon as it confirms.

Allow the merchant

Direct payments (from the vault's balance to a listed merchant) and escrow jobs go only to merchants on the vault's list. Allow the merchant adds one, with its own caps:

• Per payment (USDC): the largest single payment to this merchant.
• Daily (USDC): the most this merchant receives in one window.

Co-signing large payments

A vault with a co-signer pays above its threshold only with an approval for that exact payment: the vault, the merchant, the amount and the agent's payment intent, valid until a time you choose.

The co-signer is one of:

• A key: an address named as Co-signer when you create the vault, or later under Manage this vault › Change the policy. Your own wallet works; so does a separate key.
• A passkey: Manage this vault › Make a passkey on this device the co-signer makes a passkey in this browser, registers it on the vault and names it in the policy (two transactions). It approves from this site only.

To approve, sign in with the co-signer's key (for a passkey, with your admin key on the device that holds it) and open Approvals. Enter what the agent tells you:

• Merchant and Amount (USDC): the payment it's about to make. For an escrow job the amount is the job's total debit, fee included.
• Payment nonce: the nonce the agent pays with. For an escrow job, paste the intent hash its SDK printed instead.
• Valid for (minutes): how long the approval stands.

Approve the payment signs the approval with the co-signer (a wallet signature or the passkey) and records it on chain. The agent's payment then goes through once, and the approval is used up. Changing the vault's policy voids approvals that haven't been used.

Watching it run

After setup, the overview shows, live:

• Bond: balance, reserved by lines, coverage ratio, and any pending withdrawal.
• Vaults: balance, float left of its cap, the window's spending of its budget, the session key, the co-signer and its threshold, and each allowed merchant with its caps and spending today.
• Lines: each line as a row of cells: lit for what's vouched and unsettled, empty for what's left of the limit; with the amount settled so far and the expiry.
• Activity: every confirmed event from the chain: payments, settlements, refills, deposits, line changes, claims.

The page updates as the indexer reads each transaction; you don't need to reload.

Changing things

Under each vault, Manage this vault holds:

• Withdraw: USDC from the vault back to your wallet.
• Change the policy: the float, the daily budget, the co-signer and the threshold, in one transaction.
• Make a passkey on this device the co-signer: see Co-signing large payments.
• Rotate the session key: give the vault a new session key. Direct payments and the float move to the new key at once, and the old key's float allowance is revoked in the same transaction. Then move each line, below.
• Fund the freeze reserve: SOL set aside for the rent a freeze's checkpoint needs, so your guardian can freeze without paying it. The guardian's key still pays the network fee.
• Freeze the vault / Unfreeze the vault: a frozen vault refuses every payment by the session key, and its float allowance is revoked at once. Unfreeze it and payments resume under the same policy; the float comes back with the next refill. For 7 days after an unfreeze (the 96-hour freeze grace plus the 72-hour claim window), your bond can't be withdrawn, and lines can't be renewed or lowered. A merchant who served the agent before the freeze is still covered: if the vault stays frozen for the freeze grace (96 hours), that merchant can settle the last voucher signed before the freeze, and the bond pays it through the default path below.

Each line keeps taking vouchers from the session key it was opened with. After you rotate the vault's key, every line shows Move the line to the new key. The line switches 72 hours after you ask, so a merchant can still settle what the old key signed; until then the agent signs that line's vouchers with the old key (see A new session key).

Under Lines, Change the line to … holds:

• Resize the line: raise the limit at once, or lower it. A decrease is scheduled for 72 hours after you ask, so a merchant already serving the agent has time to settle. After that, resize again to the same limit to apply it and free the bond's reserve (a settlement on the line applies it too).
• Renew the line: extend its expiry.

Under Bond, Withdraw from the bond:

1. Request a withdrawal of an amount. What stays in the bond must still cover your open lines at your minimum coverage. The request unlocks after your longest line's expiry, plus the 72-hour claim window, plus the protocol's safety margin. One request is pending at a time.
2. When it shows as ready, Finalize the withdrawal moves the USDC to your wallet.

The cooldown keeps every merchant's claim ahead of your withdrawal. A default on the bond cancels a pending request.

When a vault comes up short

If a merchant settles the latest voucher of a line and the vault can't pay all of it, the settlement moves nothing; the program opens a default event on your bond instead. From then on:

1. For 72 hours (the claim window), every merchant with a line on that bond can file its latest voucher as a claim. The merchant middleware does this automatically.
2. When the window closes, the bond pays each claim min(voucher − settled, line limit): in full if the bond covers every claim, pro-rata if the claims add up to more than the bond.
3. The payout moves USDC from the bond to each merchant. Your operator record counts the default, and merchants see it next to your coverage.

The overview's Activity shows each step as it lands. A bond that has paid claims keeps its remainder; post more to it to open new lines.