Agents quickstart

Three ways to give an agent a treasury, smallest to largest: the MCP server (conversational), the SDK (programmatic), and the CLI wizard (human onboarding). All three are thin skins over the same API — pick by how your agent is built.

MCP — conversational treasury

For agents running in an MCP host (Claude Code, Claude Desktop, any MCP client). One command and the agent can manage a treasury by talking:

claude mcp add olbos \
  --env OLBOS_API=https://api.olbos.tech \
  --env OLBOS_PAYMENT=x402 \
  --env OLBOS_AGENT_KEYPAIR=/path/to/agent-keypair.json \
  --env OLBOS_RPC=https://api.mainnet-beta.solana.com \
  -- npx @olbos/mcp

The public mainnet RPC throttles aggressively — fine for trying things, but point OLBOS_RPC at a dedicated provider for anything real (see Operations).

Then: "you've got idle USDC — park it somewhere safe, nothing risky" becomes deploy_strategy({template: "conservative"}) → fund_strategy → capital working, all narrated and audited.

Tools

tool	cost	purpose
`get_opportunities`	free	venues ranked by net risk-adjusted APY
`deploy_strategy`	0.10 USDC	strategy + per-strategy Swig custody (owner = paying wallet)
`fund_strategy`	the amount	the x402 payment is the deposit
`get_positions`	free	liquid balance + per-venue positions
`get_risk_status`	free	exposure vs caps, total managed, kill state
`trigger_rebalance`	0.01 USDC	one cycle; no-op if nothing clears the gates
`withdraw`	0.01 USDC	unwind lowest-yield first + owner-signed payout
`get_audit_log`	free	every decision, payment, simulation, on-chain action

Owner sessions — the asymmetry

Break-glass tools are not registered in agent sessions — an agent cannot even see them. Start a separate session with the custody-root keypair to unlock them:

claude mcp add olbos-owner \
  --env OLBOS_API=https://api.olbos.tech \
  --env OLBOS_OWNER_KEYPAIR=/path/to/owner-keypair.json \
  -- npx @olbos/mcp

This adds kill_strategy, clear_kill_switch, and revoke_engine_custody (the on-chain terminal break-glass). Agents pay, owners sign.

SDK — five lines

For agents built in code:

import { Keypair } from "@solana/web3.js";
import { createOlbos, usdc } from "@olbos/sdk";

const olbos = createOlbos({
  baseUrl: "https://api.olbos.tech",
  payment: { mode: "x402", keypair: agentKeypair, network: "solana" },
});

const { strategyId } = await olbos.deployStrategy({ template: "balanced" });
await olbos.fund(strategyId, usdc(5000)); // the payment IS the deposit

The SDK hides the entire 402 dance and the custody activation signature — both are signed locally with the agent's keypair, transparently.

Full surface

// free reads
olbos.opportunities();
olbos.positions(strategyId);
olbos.riskStatus(strategyId);
olbos.auditLog(strategyId);

// metered (auto-paid in x402 mode)
olbos.deployStrategy({ template, name?, owner? });  // owner defaults to payer
olbos.fund(strategyId, usdc(amount));
olbos.rebalance(strategyId);
olbos.withdraw(strategyId, usdc(amount));           // unwind + payout to owner

// break-glass (owner sessions — needs ownerKeypair)
olbos.kill(strategyId);            // wallet-signed
olbos.unkill(strategyId);
olbos.revokeCustody(strategyId);   // ON-CHAIN: fire the engine entirely

Payment modes

// x402 (production): real payments, gasless via the facilitator
payment: { mode: "x402", keypair, network: "solana", rpcUrl?, maxPayment? }

// dev (localnet): no real USDC, a dev-payer label
payment: { mode: "dev", payer: "my-agent" }

maxPayment is a per-request safety cap (default 10 USDC) — an agent can't be made to overpay.

Custody: who is the owner?

By default the paying wallet is the owner (root of the strategy's Swig), and the SDK signs the custody activation invisibly. Pass an explicit owner to make a different wallet the root — useful when a human owner should control an agent's treasury. In that case the third-party owner signs the activation separately (the SDK only auto-signs when payer == owner).

CLI — the human onboarding wizard

For the one human moment — creating the agent identity and first strategy:

npx @olbos/cli init

The wizard creates (or reuses) the agent keypair, walks through picking a template, deploys, and hands back the strategyId. After that, the agent runs itself via SDK or MCP. (The CLI is the human's tool; the agent's tools are the SDK/MCP.)

The division of labor

The agent pays and drives (MCP/SDK) — deploy, fund, rebalance, withdraw.
The owner watches and vetoes (dashboard + break-glass) — never needs to drive the day-to-day.
The engine does the work — score, plan, gate, simulate, execute — and never holds authority to move funds out.

Next: Strategies · Payments · Dashboard.