HTTP API reference

The Olbos API is the x402-metered seller that the SDK and MCP server wrap. Most users never call it directly — but it's fully documented here for direct integration, debugging, and audit.

Base URL: your instance (e.g. https://api.olbos.tech). All bodies are JSON. Amounts are atomic USDC (6 decimals) as strings unless noted.

Authentication

• Metered writes are paid via x402 (the rail handles the 402 handshake). On the dev rail, an x-dev-payer: <label> header identifies the payer.
• Reads, in hosted mode (OLBOS_REQUIRE_AUTH=1), require a wallet session via headers x-olbos-wallet, x-olbos-expires, x-olbos-session (see Security — owner auth). In open mode, reads are unauthenticated.
• Break-glass (kill/unkill/revoke) requires an ed25519 signature of the action message in the body ({ ts, signature }), or the dev token on the dev rail.

Health

GET /healthz

Liveness + readiness. 200 with { ok, rail, venues, rpc } when healthy; 503 when RPC is unreachable or the engine has zero venues. Cached 10s.

Reads (free)

GET /v1/opportunities

Ranked venues with full scoring: venue, headlineApyBps, costBps, riskBps, netApyBps, utilizationBps, tvlUsd, index.

GET /v1/strategies

The caller's strategies. Hosted mode: only the signed-in owner's (else 401). Open mode: all, or filtered by ?owner=<pubkey>. Each row: strategyId, policy, owner, deployedAt.

GET /v1/strategies/:id/positions

walletLiquid + per-venue positions + killSwitchActive. Tenant-gated in hosted mode.

GET /v1/strategies/:id/risk-status

policy, totalManaged, and per-venue exposures (value, shareBps, capBps) + killSwitchActive. Tenant-gated.

GET /v1/strategies/:id/audit-log

The strategy's events. ?tail=N for recent history, ?after=N for incremental polling. Tenant-isolated: tx.*/x402.* events are linked by correlation ID, so no cross-tenant leakage. Tenant-gated.

GET /v1/events (operator only)

Global event stream (?tail=N / ?after=N). Disabled (404) in hosted mode — tenants use their per-strategy audit log.

Metered writes (x402)

POST /v1/strategies

Deploy. Body: { template?, name?, policy?, owner? }. Cost 0.10 USDC. Creates the strategy and its custody (see below). Returns strategyId, policy, paymentRef, and custody (status: "active" | "pending", addresses, dailyCap, and — if pending — an activationTx for the owner to sign).

POST /v1/strategies/:id/fund

Fund. Body: { amount } (atomic USDC). The x402 payment is the deposit. Returns 409 custody pending if the strategy's custody activation hasn't landed.

POST /v1/strategies/:id/rebalance

Trigger one rebalance cycle. Cost 0.01 USDC. Returns { executed: <move count> }.

POST /v1/strategies/:id/withdrawals

Withdraw. Body: { amount }. Cost 0.01 USDC. Unwinds + initiates the owner-signed payout. Returns { liquid, unwindTx, payout } where payout.status is paid (dev/inline) or pending (with a payoutTx for the owner to sign).

Custody activation (owner-signed)

GET /v1/strategies/:id/custody

Custody status; if pending, a fresh activationTx to sign (blockhashes expire).

POST /v1/strategies/:id/custody

Submit the owner-signed activation. Body: { signedTx } (base64). Marks custody active.

Payout (owner-signed)

GET /v1/strategies/:id/payout?amount=N

Build a fresh owner-signable payout transaction.

POST /v1/strategies/:id/payout

Submit the owner-signed payout. Body: { amount, signedTx }.

Break-glass (owner-only)

POST /v1/strategies/:id/kill · POST /v1/strategies/:id/unkill

Halt / resume. Body: { ts, signature } (ed25519 over olbos:kill|unkill:<id>:<ts>, ±300s), or x-owner-token on the dev rail.

GET /v1/strategies/:id/custody/revoke

Build the owner-signable on-chain revoke transaction.

POST /v1/strategies/:id/custody/revoke

Submit the owner-signed revoke. Body: { signedTx }. Removes the engine's role on-chain — terminal.

Operator

POST /v1/admin/set-apy (localnet only)

The mock-venue demo lever. 404 when there are no mock venues (i.e. on mainnet).

Rate limits

Token buckets: ~300/min reads, ~30/min writes per key, with burst. Exceed → 429.

Next: Events · Agents.