How it works

This is the end-to-end life of a treasury — every step from an agent's first call to capital earning yield, and back out again. Each step links to the deeper doc.

1. Deploy — a treasury and its custody are born together

The agent calls deployStrategy({ template: "balanced" }). Behind that one call:

1. Payment. The call is metered at 0.10 USDC over x402. The agent's SDK auto-signs the payment; the PayAI facilitator sponsors the gas, so the settlement is gasless. (See Payments.)
2. Custody, phase 1 — init. Olbos creates a per-strategy Swig smart account. The owner is root from birth — on the Swig program, role 0 (root) can never be removed or altered, so there is no instant where the engine outranks the owner. The engine pays the account's rent; it holds no role yet.
3. Custody, phase 2 — activate. Delegation requires the root's consent, so the engine builds a transaction granting itself a narrow role and the owner signs it. In the common case the paying wallet is the owner, so the SDK signs this invisibly with the same key — one logical call, two signatures, zero extra UX. (See Custody.)

The engine's role is scoped, on-chain, to exactly:

• approved venue programs only (programLimit) — it can compose instructions for Kamino/Marginfi and nothing else;
• a USDC spend cap per 24h (tokenRecurringLimit) — bounded even under full compromise;
• the venues' receipt mints — so it can unwind positions;
• and deliberately not the SPL token program — so it cannot transfer funds to anyone, the owner included.

The agent gets back a strategyId and the custody details (swig address, the wallet PDA that holds assets, the daily cap).

2. Fund — the payment is the deposit

The agent calls fund(strategyId, usdc(5000)). The x402 settlement transfers 5,000 USDC, and that settled transfer is the deposit — there is no "send-money-then-notify" race. The funds land in the strategy's Swig wallet PDA (not the engine's wallet — funds are never commingled). The engine credits the amount and the autonomy loop puts it to work. (See Payments — payment-as-deposit.)

3. Allocate — the engine plans, gates, simulates, executes

Each cycle (manual trigger, or the autonomous watch loop):

1. Read truth. On-chain balances are the source of truth for positions; the event log is the source of truth for decisions.
2. Score venues. net APY = headline − cost − risk haircut. High utilization and thin TVL are penalized or excluded. (See Strategies — scoring.)
3. Plan. Greedily fill the highest-net-APY venues up to the per-venue cap, keeping the liquidity buffer idle. Diff current vs target into surpluses and deficits.
4. Gate every move through four filters: the risk gate (a pure function — caps, buffer, allowlist), the minimum-improvement threshold, the dust floor, and the break-even gate (a move must recoup its own gas within the policy's horizon). A move that fails any gate doesn't happen, and the rejection is logged.
5. Simulate first. Every transaction is simulated against live state before it's sent. Nothing that fails simulation is ever broadcast.
6. Execute with at-most-once semantics. Each move gets a deterministic intent ID (a content hash). A crashed-and-restarted engine consults the log and never double-executes.

Every step — sampled APYs, proposed moves, gate passes and blocks, simulations, confirmations — is appended to the event log, which is what the dashboard narrates.

4. Observe — the owner watches through glass

The owner opens the dashboard, connects their wallet, and signs a free message to prove ownership. They see only their own treasuries: AUM, blended APY, live allocation, exposure vs caps, and a plain-English feed of every decision the engine made. The dashboard is read-only by design — except the one break-glass below. (See Dashboard, Security — multi-tenancy.)

5. Withdraw — the exit pays out to the owner

The agent calls withdraw(strategyId, usdc(1200)). The engine unwinds the lowest-yield positions first (cheapest capital to free), honoring the risk policy. Then the payout leg: because the engine has no transfer power, the USDC leaves the Swig under the owner's root authority — the engine builds and fee-pays the transfer, the owner's key signs it (the SDK does this invisibly), and the funds land in the owner's wallet. (See Custody — payouts.)

6. Break-glass — fire the engine, two ways

The owner can stop everything:

• Kill switch — a wallet-signed message halts all activity. The engine refuses every action until cleared. The dashboard's hold-to-seal ring is this.
• On-chain revoke — the terminal option: remove the engine's role from the Swig on-chain. After this only the owner's key can touch the funds, and it works even if the Olbos API is down. That independence is the whole point of the architecture. (See Custody — break-glass.)

The invariant that ties it together

At no point in this lifecycle can the Olbos engine move funds to an address the owner didn't authorize. Deposits go into approved venues; withdrawals come back to the owner; the engine fee-pays but never directs value to itself. A fully compromised engine can, at worst, shuffle capital between approved lending venues within a daily cap — annoying, bounded, and never theft. This is verified by an on-chain rug test run against the live role.

Next: pick your path — Architecture · Custody · Strategies · Agents quickstart.