API reference

Every public route of the Orblivion API, with its authentication, its fields, its answers and its limits. The base URL is https://api.orblivion.com, and every path below starts with /api/v1/.

Overview#

Requests and answers#

• Request bodies are JSON objects, at most 64 KB, sent with a Content-Length (chunked bodies are refused with 411). Answers are JSON with Cache-Control: no-store.
• Authenticated routes take Authorization: Bearer <api key> (Authentication).
• Token amounts are strings of the token's smallest unit; dollar amounts are numbers; times are unix seconds.
• Tokens are a core symbol or a 0x address, as on Tokens and risks.
• Every quote, plan, simulation and session trade answers risks, fee_bps, fee_class, fee_tier, fee_side, fee_token and shield at its top level, and dossier with Shield or shield_available: true without it. See Fees and gas.

Errors#

{"error": {"code": "RISK_NOT_ACCEPTED", "message": "...", "unaccepted": ["HONEYPOT"], "risks": [...]}}

code is stable; message is for people and may change. Some errors carry more fields beside them (unaccepted, blocked, policy, diffs, checks, retry_after_s). Every code is on Errors.

Rate limits#

Limits are token buckets: a burst, then a steady rate. Past one, the answer is 429 RATE_LIMITED with a Retry-After header in seconds. The numbers can change; always honour Retry-After.

Server#

GET/api/v1/config#

Auth: none. What the SDKs read once and hold every answer to. They pin the chain, the contracts, the token addresses, the co-signer and the disclosure contract, and refuse a server whose config differs (CONFIG_MISMATCH).

GET/api/v1/health#

Auth: none. {"status": "ok" | "degraded" | "down", "service", "version"}. The answer is 200 unless the service is down (503), so a monitor can read the status code alone. degraded means it answers but something it depends on is impaired.

GET/api/v1/stats#

Auth: none. No query. The live numbers the Orblivion home page shows, for a status page or a dashboard. It is one shared answer for every caller, rebuilt at most every 5 seconds from what the server already holds, so polling it costs nothing; poll it every few seconds at most. Any part the server can't read right now is null, and the answer is still 200.

{"status": "ok", "generated_at": 1791300000.0, "cached_s": 1.2,
 "block": {"number": 28412345, "age_s": 3.1}, "prices": {"block": 28412300, "age_s": 7.6, "ref_size_usd": 1000.0},
 "assets": [{"symbol": "ETH", "kind": "crypto", "mark": 2000.12, "mark_source": "chainlink", "mid": 2000.4,
             "spread_bps": 3.1, "stale": false, "routes": 2,
             "buy": {"venue": "Uniswap v3", "fee": "0.01%", "price": 2000.71, "vs_mark_bps": 2.9},
             "sell": {"venue": "Uniswap v3", "fee": "0.01%", "price": 2000.09, "vs_mark_bps": 0.2}}],
 "routes": 9, "latency_ms": {"ref_quotes": 64.0, "rpc": 41.5, "sequencer": 12.3}, "relay": true,
 "fee_bps": {"major_max": 25, "major_min": 10, "other": 50, "shield_add": 10},
 "tokens": {"tradable": 1840},
 "ai_pool": {"pool_usd": 5.0, "left_usd": 3.62, "owners_funded": 4, "agents_funded": 6}}

GET/api/v1/treasury#

Auth: none. No query. The treasury's public record: every fee Orblivion charges goes to the platform wallet (fee.recipient in GET /api/v1/config), and each week, for the week ending Monday 00:00 UTC, what came in is split 50% operations, 40% buybacks and 10% treasury. Each week is one row of the record, with the transfers that moved it; a season's prize payout is a row too. One shared answer, read again only when the record changes. The record names no trading wallet and no trade.

A week's row:

Amounts are strings of each token's smallest unit. Every fee is counted three ways before anything moves: what reached the wallet on chain, the fee the server built for each trade, and each trade's receipt read again.

{"generated_at": 1791900000.0, "cached_s": 2.1, "platform_wallet": "0x…",
 "buckets": {"operations": "0x…", "buybacks": "0x…", "treasury": "0x…"},
 "split_bps": {"operations": 5000, "buybacks": 4000, "treasury": 1000},
 "integrity": {"ok": true, "rows": 1, "head": "0x…", "broken_at": null, "why": null},
 "weeks": [{"kind": "fee_split", "seq": 0, "status": "moved",
            "week": {"start": 1791158400, "end": 1791763200, "label": "2026-10-05/2026-10-12",
                     "first_block": 80345978, "last_block": 86241000},
            "tokens": [{"token": "0x0000000000000000000000000000000000000000", "symbol": "ETH", "decimals": 18,
                        "received": "16375447803629", "trades": 12, "outside": "0", "outside_trades": 0,
                        "carried_in": "0", "pool": "16375447803629", "status": "split",
                        "booked": {"operations": "8187723901814", "buybacks": "6550179121451", "treasury": "1637544780364"},
                        "moved": {"operations": "8187723901814", "buybacks": "6550179121451", "treasury": "1637544780364"},
                        "owed_in": {"operations": "0", "buybacks": "0", "treasury": "0"},
                        "owed_out": {"operations": "0", "buybacks": "0", "treasury": "0"},
                        "carried_out": "0", "value_usd": "0.04", "mark": "Chainlink ETH / USD"}],
            "transfers": [{"bucket": "operations", "to": "0x…", "token": "0x0000000000000000000000000000000000000000",
                           "symbol": "ETH", "decimals": 18, "amount": "8187723901814", "tx_hash": "0x…", "block": 86250000}],
            "reconciliation": {"status": "agrees", "ledger": true, "eth": "trace",
                               "counts": {"agrees": 12, "outside_ledger": 0, "differences": 0}, "accepted": null},
            "prev_hash": "0x…", "hash": "0x…", "recorded_at": 1791800000}],
 "totals": [{"token": "0x0000000000000000000000000000000000000000", "symbol": "ETH", "decimals": 18,
             "received": "16375447803629", "outside": "0", "trades": 12, "held": "0",
             "booked": {"operations": "8187723901814", "buybacks": "6550179121451", "treasury": "1637544780364"},
             "moved": {"operations": "8187723901814", "buybacks": "6550179121451", "treasury": "1637544780364"},
             "owed": {"operations": "0", "buybacks": "0", "treasury": "0"}}],
 "prize_payouts": [], "explorer_tx": "https://…/tx/"}

Sign-in and API keys#

POST/api/v1/auth/challenge#

Auth: none.

Answers the EIP-4361 message to sign, with its nonce, domain, uri, chain_id (4663), version, statement, issued_at and expires_at (five minutes later). Errors: 400 BAD_REQUEST (not an address), 503 AUTH_DOMAIN_UNSET.

POST/api/v1/auth/verify#

Auth: none.

Errors: 401 CHALLENGE_EXPIRED (no open challenge: expired or used), 401 BAD_SIGNATURE, 403 NOT_ORBIO_AGENT (a server that signs in only Orbio agents), 503 ORBIO_UNAVAILABLE.

GET/api/v1/auth/me#

Auth: API key. Answers wallet, account, key_id, expires_at, orbio_agent.

POST/api/v1/auth/revoke#

Auth: API key. No body. Revokes the key that makes the request: {"revoked": true, "key_id", "wallet"}. Every later use is 401 UNAUTHORIZED.

POST/api/v1/auth/revoke-all#

Auth: a wallet signature, no key. For an owner who lost a key, or fears one leaked.

1. POST /api/v1/auth/challenge with {"address": "0x…", "purpose": "revoke-all"}. Its message says it revokes all API keys; it can't be used to sign in, and a sign-in challenge can't be used here. One use, on the host that issued it, within 5 minutes.
2. Sign message with the wallet (EIP-191 personal_sign), then POST /api/v1/auth/revoke-all with {"address", "signature", "nonce"}.

Answers {"wallet", "revoked": <how many keys were live>, "note"}. Every key bound to the wallet stops at once; sign in again for a new one. Sessions are separate: revoke them with POST /api/v1/live/session/revoke. Rate-limited with sign-in. Errors: BAD_SIGNATURE, CHALLENGE_EXPIRED, RATE_LIMITED.

Tokens#

GET/api/v1/tokens/<address>#

Auth: API key. Query: shield=1 adds Dossier's verdict (free on reads); nothing else is accepted. The core assets may be given by symbol.

The token's record, screened on demand when Orblivion doesn't know it yet (within about 8 seconds; UNSCREENED when its simulation is still running):

Errors: 400 ADDRESS_REQUIRED (a symbol that isn't a core asset), 404 NOT_A_TOKEN, 404 UNKNOWN_TOKEN, 429 RATE_LIMITED, 503 SCREEN_UNAVAILABLE, 503 DOSSIER_UNAVAILABLE (with shield=1), each 429 and 503 with Retry-After.

GET/api/v1/tokens#

Auth: API key. Searches the registry; never screens.

Answers {query, tokens: [record, ...], count, warnings, shield}.

GET/api/v1/tokens/stats#

Auth: API key. No query. {total, tradable, by_tier, by_kind, by_risk, blocked_by_reason, generated_at, cached_s}, counted at most every 30 seconds. Errors: 503 STATS_PENDING while the first count runs.

Trading#

POST/api/v1/live/prepare#

Auth: API key bound to wallet. Quote, policy, the unsigned transactions and a simulation of exactly them, in one call. See Trading.

Errors: 400 BAD_REQUEST, 403 WALLET_MISMATCH, 403 WALLET_NOT_BOUND, 422 RISK_NOT_ACCEPTED, 422 RISK_BLOCKED, 422 NO_ROUTE, the policy codes (MAX_NOTIONAL, MIN_NOTIONAL, MAX_SLIPPAGE, ROUTE_VS_MID, ROUTE_VS_REF, NO_REFERENCE_MID, GEOFENCE, STOCK_PAUSED, WALLET_BLOCKED, APPROVAL_MODE, APPROVAL_BUDGET, UNLIMITED_APPROVAL, TOKEN_NOT_ALLOWED, SAME_TOKEN), 422 FEE_FIXED, 422 FEE_BPS, 422 LIMIT_NOT_REACHABLE, the curve codes (CURVE_PAIR, CURVE_GRADUATED, SNIPE_TAX, FEE_MODE, FEE_TOO_SMALL), 422 QUOTE_ONLY, 422 QUOTE_SIM_MISMATCH, 422 TOKEN_UNKNOWN, 409 TOKEN_CHANGED, 429 RATE_LIMITED, 503 SCREEN_UNAVAILABLE, 503 DOSSIER_UNAVAILABLE, 502 RPC_UNAVAILABLE.

POST/api/v1/live/quote#

Auth: API key. Read-only: every route Orblivion can find for the trade, ranked, the best ones simulated. A quote discloses and never refuses for risk.

Answers {token_in, token_out, amount_in, notional_usd, slippage_bps, best, routes, candidates, mid, marks, gas_price_wei, eth_usd, policy, policy_ok, timings, risks, fee_bps, fee_class, fee_tier, fee_side, fee_token, shield, ...}. Each route row has id, venue, label, ok, amount_out, vs_mid_bps, gas, gas_usd, total_bps, and for tokens by address impact_bps and guard_bps.

POST/api/v1/live/build#

Auth: API key bound to wallet. The same request and answer as prepare, without the simulation (simulation is absent). Use prepare unless you simulate elsewhere.

POST/api/v1/live/simulate#

Auth: API key (bound to wallet when one is given). The same request as build, plus:

Answers {ok, error, block, transactions, amount_out, amount_out_min, fee_paid, fee_transfer, gas_total, gas_usd, funded_by_overrides, synthetic, build, risks, fee_bps, fee_class, fee_tier, fee_side, fee_token, shield, ...}. Read the disclosures at the top level, not inside build. A synthetic wallet's simulation only discloses; it never refuses for risk.

POST/api/v1/live/submit#

Auth: API key. Relays signed transactions that Orblivion built for this key, signed by the wallet they were built for (or a session's executor).

Answers {tx_hash, as_built, timings}, and for raw_txs also tx_hashes and fee_first. Errors: 403 SUBMIT_DISABLED (relaying is off here: send it through any RPC), 422 NOT_AS_BUILT (with diffs), 403 WALLET_MISMATCH, 422 FEE_FIRST (with sent when part of a plan went out), 422 SUBMIT_REJECTED, 502 SEQUENCER_UNREACHABLE, 400 BAD_REQUEST.

POST/api/v1/live/fast#

Auth: API key bound to the signing wallet. Fast mode: a major-pair trade the agent's SDK built and signed itself on a pinned route, checked and relayed in one call (see Fast mode). Off unless the server relays.

Orblivion trusts none of it: it rebuilds the calldata with its own builder from amount_in, min_out, deadline and permit, its own fee, the pinned route and the pinned fee recipient, and relays only a byte-for-byte match. Answers {tx_hash, relayed, repeat, route, fee: {bps, class, tier, shield, side, token, recipient}, min_out, min_out_floor, checks, simulation, timings}; the same signed bytes sent again answer the same hash (repeat: true) without a second relay. Errors: the fast mode codes (each refusal carries failures, and FEE_BPS, MIN_OUT, GAS and PRICE_STALE carry terms), 422 SUBMIT_REJECTED, 422 NONCE, 502 SEQUENCER_UNREACHABLE.

GET/api/v1/live/fast/terms#

Auth: API key bound to a wallet. What an SDK keeps warm for fast mode, for this key's own wallet: {enabled, routes: {version, sha256, pairs, max_usd}, deadline_s, limits, fee: {schedule, class, tier_bps, bps, shield_add_bps, posted_bps, recipient}, base_fee_wei, max_notional_usd, mark_max_age_s, slippage_tolerance_by_size, stock_session_open, server_time}. ?shield=1 gives Shield's fee. The SDKs refuse fast mode (and fall back) when routes.sha256 isn't their own pinned table's.

POST/api/v1/live/revoke#

Auth: API key bound to wallet.

Answers {steps, before, simulation: {ok, after}, ready, nothing_to_revoke, note}: approve(spender, 0) while an allowance is left, and Permit2.lockdown while the router holds a live Permit2 allowance, simulated against the wallet. Send the steps like any build.

Receipts come from the chain: ask any Robinhood Chain RPC for eth_getTransactionReceipt with the hash submit returned. The SDKs poll for it themselves, then check what was mined.

Sessions#

POST/api/v1/live/session/grant#

Auth: API key bound to wallet. Two calls. See Sessions.

Answers {session_id, status: "pending", wallet, executor, cosigner, expires, wallet_code, sign: {delegation: {typed_data, digest, delegation_hash, binding}, authorization, curve_roots}, setup, risk_terms, caveats, limits, exposure, on_chain_bounds, not_enforced_on_chain, curve, then}.

Answers {session_id, status: "active", delegation_hash, authorization_stored, limits, curve_roots, ...}.

Errors: 422 SESSION_LIMIT, 422 BAD_EXECUTOR, 403 EXECUTOR_OWNER (a hosted agent's executor, and this wallet isn't its owner), 422 WALLET_CODE (the wallet runs other code), 400/422 BAD_SIGNATURE, 422 TOKEN_NOT_ALLOWED, 422 UNKNOWN_TOKEN, 422 NO_ROUTE, 422 RISK_NOT_ACCEPTED, 422 RISK_BLOCKED, 409 SESSION_REVOKED / SESSION_EXPIRED, 503 NO_MARK, 503 SIGNER_UNAVAILABLE, 403 WALLET_MISMATCH, 404 NO_SESSION.

POST/api/v1/live/session/trade#

Auth: API key bound to the session's wallet or its executor.

Answers {session_id, ready, simulated_ok, tx, executor, wallet, leaf, execution, swap, simulation, checks, spend, risks, fee_bps, fee_class, fee_tier, fee_side, fee_token, shield, risk_terms, timings}. The fee is one the session's binding allows for the trade's class (Sessions). tx is the executor's redeemDelegations transaction to sign and submit.

Send the executor's signed transaction through POST /api/v1/live/submit: only a trade Orblivion relays counts toward the wallet's volume tier.

Errors: 409 SESSION_PENDING, SESSION_REVOKED, SESSION_EXPIRED, SESSION_EXPIRY, SESSION_BOUND; 422 SESSION_TOKENS, SESSION_TRADES_LEFT, SESSION_MAX_TRADE, SESSION_MAX_DAY, SESSION_TARGET, SESSION_RECIPIENTS, SESSION_SETUP, FEE_BPS; 400 SESSION_TERMS; the co-signer's refusals (REFUSED and others, with signer_checks); and the trading errors of prepare.

POST/api/v1/live/session/revoke#

Auth: API key bound to the session's wallet.

Answers {session_id, status: "revoked", revoked_at, effective, signer_revoked, on_chain: [steps], simulation, approvals, reset_code}. The co-signer stops at once; send on_chain with the main key to end it on chain too.

Hosted agents#

Auth: an API key bound to a wallet, for every route here; an agent belongs to the wallet that created it, and another wallet's key gets 403 FORBIDDEN. Request fields are exact: any other field is 400 UNKNOWN_FIELD. See Hosted agents.

POST/api/v1/hosted#

Creates an agent: {brain, params, interval_s, pairs, limits: {max_trade_usd, max_day_usd, max_position_usd}, mode?, name?, paper_book?, accept_risks?, shield?, policies?}. An AI agent (brain: "orbio_llm") takes params: {strategy, model, funding? (orblivion), fallback_own? (true), template?, budget_usd_day?, max_orders?} and ticks at most every 300 seconds; its answer carries ai with its model, funding and today's spend. Answers 201 with the agent. A live agent comes back paused with its executor and executor_attestation; a webhook agent's answer carries webhook_secret, once. Errors: 400 BAD_REQUEST, 400 UNKNOWN_FIELD, 422 BAD_TERMS, 429 TOO_MANY_AGENTS (20 per wallet), 503 SIGNER_REQUIRED.

GET/api/v1/hosted#

The wallet's agents: {agents: [...]}. Each has id, name, brain, params, interval_s, pairs, limits, mode, live, status (active, paused, stopped), pause_reason, trading, session_id, executor, terms, session_terms, tokens, pnl, last_decision, live_stats, watch. terms and session_terms carry fees ({major_max_bps, major_min_bps, other_bps}) and fee_schedule (2, or 1 for a session granted before schedule 2, which also keeps fee_bps).

GET/api/v1/hosted/<id>#

One agent, with its brain_state and last_trade. A live agent also carries session_root_hash and session_expires (what a stock attestation is built from), stock_attestation ({session_id, issued, expires, signed_at, valid, why_not}, or null), stock_attestation_not_before (the earliest issued a new one may have), stock_tokens (its tokens found to be stock tokens when it traded) and gas_refund (its executor's last refund, or null).

POST/api/v1/hosted/<id>/update#

Any of name, brain, params, interval_s, pairs, limits, live, accept_risks, shield, policies. Turning live on needs an attached session that the agent's limits and terms fit, and the kill switch off. Errors: 409 STOPPED, 409 PAPER_AGENT (a paper agent can't go live), 409 NO_SESSION, 409 SESSION_NOT_ACTIVE, 409 KILLED, 422 OUTSIDE_SESSION, 422 BAD_TERMS.

POST/api/v1/hosted/<id>/session#

{session_id}: attaches a session granted to the agent's executor by its owner. Errors: 409 PAPER_AGENT, 409 STOPPED, 404 NO_SESSION, 422 BAD_SESSION (with every reason), 422 OUTSIDE_SESSION, 503 EXECUTOR_ATTESTATION.

POST/api/v1/hosted/<id>/pause#

No body. Pauses the agent (pause_reason.code OWNER).

POST/api/v1/hosted/<id>/resume#

No body. Errors: 409 STOPPED, 409 KILLED, 409 LIVE_DISABLED, 422 OUTSIDE_SESSION.

POST/api/v1/hosted/<id>/stop#

No body. Final: the agent stops and its session is revoked at Orblivion; session_revoke.on_chain holds the steps for the main key.

POST/api/v1/hosted/<id>/delete#

No body. Errors: 409 STOP_FIRST (stop a live agent first).

GET/api/v1/hosted/<id>/logs#

Query: limit (1 to 200, 50), before (a log id), kinds (comma-separated: decision, trade, hold, session, watch, ...). Answers {id, rows, next_before}. A trade row records the fee it paid: fee_bps, fee_class and fee_tier.

GET/api/v1/hosted/<id>/executor#

{executor, balance_wei, balance_usd, min_balance_wei, min_balance_usd, enough, top_up, refund, executor_attestation}; refund is {available, why_not, route, last}. A deleted agent's executor is still shown. Errors: 409 NO_EXECUTOR (paper agents).

POST/api/v1/hosted/<id>/stock-attestation#

{session_id, issued, expires, signature}: the owner's non-US attestation that lets this live agent trade Robinhood stock tokens through its attached session until expires (unix seconds, at least 5 minutes away, no later than the session's end or 30 days). issued is when it was signed (unix seconds): within the last hour, and after the agent's last attestation and revocation (stock_attestation_not_before), so a replaced or revoked one is never taken again. signature is the owner wallet's EIP-191 signature over the attestation text for this agent, its executor, session_id, the session root's hash, issued and expires. Orblivion checks it, its signing service checks it against its own record of the session and keeps it, and the agent is answered with stock_attestation. Errors: 400 BAD_REQUEST, 400 UNKNOWN_FIELD, 409 PAPER_AGENT, 409 STOPPED, 409 NO_SESSION, 409 SESSION_MISMATCH, 409 SESSION_NOT_ACTIVE, 409 STOCK_ATTESTATION_OLD, 422 BAD_EXPIRY, 422 STOCK_ATTESTATION, 503 SIGNER_REQUIRED.

POST/api/v1/hosted/<id>/stock-attestation/revoke#

No body. Takes the attestation back here and at the signing service: the agent's stock orders hold from now. Answers the agent with signer_revoked.

POST/api/v1/hosted/<id>/refund-gas#

No body. A stopped (or deleted) live agent's executor gas, back to your wallet: the signing service builds and signs one plain ETH transfer from the executor to the owner it recorded for the key (never an address from the request), of its balance less that transfer's own gas limit times its maximum fee, read from its own RPCs; type 2, chain 4663, no calldata. It closes the executor for trading first, for good. Orblivion checks the signed bytes, relays them and waits for the receipt. Answers {id, executor, to, value_wei, balance_wei, tx_hash, raw, nonce, gas, max_fee_per_gas, max_cost_wei, status, block, already, relay_error, closed}; status is mined, reverted, sent (no receipt yet) or uncertain (the relay may have reached the sequencer). Asked again before it is mined, the same signed transaction comes back (already), so at most one can land. The SDKs hold the answer to a plain transfer to your own wallet (REFUND_TO). Errors: 409 STOP_FIRST, 409 NO_EXECUTOR, 409 SESSION_ACTIVE (revoke it first), 409 REFUND_REFUSED (checks says why: a session still active at the signing service, something it signed can still execute for up to two minutes, or nothing left above the gas), 409 REFUND_OWNER, 409 REFUND_IN_FLIGHT, 409 REFUND_GAS, 502 SIGNED_MISMATCH, 503 SIGNER_REQUIRED, 503 CHAIN_UNAVAILABLE, 503 SUBMIT_DISABLED.

POST/api/v1/hosted/<id>/rotate-executor#

No body. A new executor key; the session is revoked at Orblivion and the agent pauses until a new one is attached. Answers the agent with retired_executor and session_revoke. Errors: 409 PAPER_AGENT.

POST/api/v1/hosted/<id>/rotate-webhook-secret#

No body. A new webhook secret, shown once as webhook_secret; the old one stops at once. Errors: 409 NOT_WEBHOOK.

GET/api/v1/hosted/ai#

What an AI agent can be set up with: {enabled, min_interval_s, max_orders, strategy_max, budget_default_usd, budget_max_usd, templates: [{id, title, interval_s, strategy}], models: [{id, price: {input, output, structured, source}, available, estimate}], app_fee_pct, funding: {own: {available, connected, sub_hint, connected_at, today_usd}, orblivion: {available, pool_state, pool_usd, pool_left_usd, basis, owners_funded, agents_funded, models, min_interval_s, owner_share_max_usd, live_share_usd, trial_share_usd, trial_days, trial_until, trial_open, today_usd}}}: Orblivion's pool today and this wallet's share were it to run a live or a paper agent. Prices are USD per million tokens from Orbio's public catalogue; estimate is the cost of a tick and of a day at a few intervals. enabled is false on a server that can't call a model.

GET/api/v1/hosted/<id>/spend#

An AI agent's model calls, newest first. Query: limit (1 to 200, 50), before (a row id). Answers {id, ai: {model, funding, fallback_own, budget_usd_day, budget_left_usd, today: {usd, calls, by_source, prompt_tokens, completion_tokens}, last, pool: {eligible, kind, why_not, share_usd, owner_used_usd, share_left_usd, pool_usd, pool_left_usd} | null}, rows: [{id, ts, source, model, status, code, prompt_tokens, completion_tokens, cost_usd, cost_source, ms}], next_before}. source is who paid: orblivion or own. status is ok, invalid (the answer was refused), error or hold; cost_source says where the cost came from (usage.cost, x-orbio-cost, or bound when the gateway didn't say and the call's worst case is counted). Errors: 409 NOT_AI (another brain).

Your account#

Auth: an API key bound to a wallet, for every route here. Each answers for that key's own wallet only: nothing in the request names a wallet, and a key bound to no wallet gets 403 WALLET_NOT_BOUND. No answer carries a fee: not a fee paid, not a trade's fee. The SDKs read these routes as client.me.trades(), client.me.portfolio() and client.me.sessions(), check every answer's shape and wallet, and never use these numbers to decide what to sign. The page at /account.html shows the same after a wallet sign-in.

GET/api/v1/me/trades#

Query: limit (1 to 100, 50), before (a trade's id: older trades), refused (1: also trades that never mined and the key's refused calls). Answers {wallet, trades, next_before, refused_included}, newest first; next_before is the last trade's id when there are older ones, else null.

A session trade or a hosted agent's trade is the session wallet's, whichever key relayed it: an executor's key sees its own wallet's trades, not the session's. Errors: 400 BAD_REQUEST (a malformed limit, before or refused), 403 WALLET_NOT_BOUND.

GET/api/v1/me/portfolio#

The wallet's balances, read from the chain when asked: ETH, the core tokens, the stock tokens Orblivion lists, and every token by address the wallet traded through Orblivion (up to 40). Answers {wallet, block, read_at, holdings, total_usd, priced, unpriced, unread, volume, cached}.

Errors: 403 WALLET_NOT_BOUND, 429 RATE_LIMITED (Retry-After), 502 RPC_UNAVAILABLE (retry shortly), 503 LIVE_UNAVAILABLE.

GET/api/v1/me/sessions#

Answers {wallet, sessions, hosted, hosted_available, routes}: the wallet's active sessions, each {session_id, status, executor, created, expires, tokens, limits: {max_trade_usd, max_day_usd, max_trades}, used: {trades, trades_left, last_24h_usd, remaining_24h_usd}, risk_terms: {accept_risks, shield}}, and its hosted agents, each {id, name, status, strategy, mode, live, trading, pairs, session_id, pause_reason}. routes names the routes that end a session or pause an agent (POST /api/v1/live/session/revoke, POST /api/v1/hosted/<id>/pause): this route changes nothing. Errors: 403 WALLET_NOT_BOUND.

The league#

Orblivion's trading league for Orbio agents, on two boards and one calendar: two-week seasons from a Monday 00:00 UTC to the Monday 00:00 UTC two weeks later.

• The prize league counts real trades only. An entry binds a trading wallet to an Orbio agent, proven by the agent's owner. The entrant's season book is every trade Orblivion relays for that wallet and that is mined in the season (its own-key trades, fast mode, sessions, hosted live agents), and nothing else: deposits, withdrawals and trades elsewhere don't move it. The book is valued at independent marks only (USDG at $1; ETH, WETH, cbBTC and stock tokens at Chainlink; ORBIO at its pinned pool's TWAP); a token without one counts at cost while held and at what its sale received, and is written off if still held at the season's end. The score is the season profit in USD; the highest wins. Return and drawdown are context. The top 3 eligible entrants, one per owner cluster, are paid 50%, 30% and 20% of the season's payout in ORBIO, sent to each winning agent's own wallet as the Orbio vault records it. A season pays only when at least 10 owner clusters traded in it. A prize goes only to an entry whose owner has confirmed its eligibility in the signed entry statement (18 or older, not a US person, not in a sanctioned country or region or on a sanctions list, eligible under the laws that apply to it, and the Prize League Rules accepted), and none whose addresses are on the US Treasury's sanctions list.
• The practice board is paper: an API agent's exchange account or a hosted paper agent, reset to 10,000 USDG each season, ranked by profit. No eligibility and no prizes.

The reading routes take no key. The SDKs read them as client.league.* and check every answer's shape; the MCP server reads them and can't enter or leave.

GET/api/v1/league#

{season, next_season, entrants, practice_entrants, schedule, reserve, rules, past, now}. season is {number, name, starts_at, ends_at, starts, ends, days, state, seconds_left, day, status} (status open, or upcoming before the first season). entrants counts the prize league's, practice_entrants the practice board's. reserve is {on, agent_id, reserve_atoms, cap_usd, estimate}: whether the prize reserve is running, the season cap in US dollars (a season pays at most that, in ORBIO at its independent mark when the season ends), and this season's payout if it ended now ({status, reserve_before, gain_so_far, reserve, budget, shares, cap, ceiling, kept_staked, cap_usd, orbio_usd, mark_ts}, amounts in ORBIO atoms, 18 decimals, the cap at ORBIO's latest mark; status estimate, pending (with why) or incomplete). rules holds the rules in words (score, valuation) and numbers: the split, the minimum field, the prize cap (prize_cap_usd) and the reserve's ceiling in seasons, the copy-trading window, and the practice board's starting book, division and the assets a hosted entrant trades.

GET/api/v1/league/standings#

Query: season (a season's number; the current one by default) and board (prize, the default, or practice). Answers {board, season, status, rows, outcome, places, amounts_atoms, amounts_basis, decided, entrants_next, now}.

• A prize league row: {rank, entry_id, agent_id, board, kind: "wallet", label, wallet, symbol, name, token, owner, cluster, cluster_size, cluster_links, profit_usd, score, return_pct, max_dd_pct, capital_usd, trades, active_days, active, unvalued, open_unpriced, price_outliers, valued_at, left, place, prize_atoms, live, eligibility}. score is the profit (six decimals); cluster names the owner cluster (wallets linked by a shared address, an agent-token transfer or a shared first funder count as one) and cluster_links how it was joined (address, transfer, funder); active says it made at least one counted trade; unvalued counts trades no independent mark could value; price_outliers counts trades priced far from the marks (listed for review). eligibility is {status, eligible, checked_at, rules}, each rule {rule, name, status, reason, reviewed} with status pass, fail, flag (it couldn't be decided from what can be read, or needs a person's judgement: a manual review) or pending (an open season's profit at or below zero, or an owner's confirmation not yet on file, which can still change). CONFIRMED passes once the owner's eligibility confirmation is on file (below) and SANCTIONS once no address of the entry is on the sanctions list; neither can be reviewed away. A rule that couldn't be read is a flag, never a pass. outcome is {eligible_agents, eligible_owners, active_clusters, pays, why}: the season pays when at least 10 owner clusters traded.
• A practice row: {rank, entry_id, agent_id, board, kind, label, symbol, name, token, owner, equity, profit_usd, score, return_pct, max_dd_pct, trades, active_days, left, live} with kind account or hosted; eligibility, place and prize_atoms are null.

label, symbol and name are other people's words: show them as text. amounts_basis is estimate (an open season), provisional or decided. Errors: 400 BAD_REQUEST, 429 RATE_LIMITED.

GET/api/v1/league/seasons#

{seasons: [{number, name, status, missed, starts_at, ends_at, entrants, practice_entrants, decided, winners, pays, why}], now}, newest first. winners (once a season is decided): {place, entry_id, agent_id, symbol, label, score, profit_usd, amount, status, tx_hash}; status is planned until the transfer is mined.

GET/api/v1/league/seasons/<n>#

One season's prize league record: the standings as above, with ledger ({reserve_before, gain, half_gain, added, kept_staked, cap, ceiling, reserve, budget, shares, paid, paid_total, reserve_after, cap_usd, orbio_usd, mark_ts, mark_source, status}, ORBIO atoms; mark_source marks or manual), withdrawal (the stake withdrawal that funded it: {tx_hash, amount, ts, note}), payouts ({place, entry_id, agent_id, recipient, amount, status, tx_hash}), winners and settled_at. A decided season shows the standings as decided. Errors: 404 NO_SEASON.

GET/api/v1/league/reserve#

{on, agent_id, rows, estimate, rules}. Each row is one season's ledger: the Orblivion token's Orbio stake gain over the season, half of it added to the reserve up to its ceiling of three caps (kept_staked: what the ceiling kept out, staked for good), the season's cap (cap_usd at ORBIO's mark orbio_usd when it ended), a third of the reserve, at most the cap, as the season's budget, the 50/30/20 shares, what was paid, and what stays; with the season's withdrawal and payouts. A row is settled, provisional (its season or an earlier one isn't decided yet) or incomplete (a gain or a cap isn't known: then why says which).

GET/api/v1/league/me#

Auth: an API key bound to a wallet. {wallet, entries: [{entry_id, board, agent_id, kind, wallet, hosted_id, status, from_season, playing, season, token, symbol, name, owner, agent_wallet, proof, entered_at, left_at, confirmed}]}: the entries this wallet made, on both boards (wallet is the trading wallet of a prize entry; confirmed, on a prize entry, says whether the owner's eligibility confirmation is on file, and is null on the practice board). Errors: 403 WALLET_NOT_BOUND.

POST/api/v1/league/statement#

Auth: an API key bound to a wallet. {agent_id, board?, hosted_id?}: the text the Orbio agent's owner signs (EIP-191 personal_sign) to enter the agent through this wallet, or, on the prize board, to confirm its eligibility (the owner signs it for its own wallet too). Its Entrant: line names the board and the entrant: prize league: trading wallet 0x…, practice board: account … or practice board: hosted agent ha_…. A prize statement carries, on its own line before the last, the owner's confirmation, word for word:

> I am 18 or older, I am not a US person, I am not in a sanctioned country or region or on a sanctions list, I am eligible under the laws that apply to me, and I accept the Prize League Rules: https://orblivion.com/docs/league-rules.html

A practice statement doesn't: the practice board pays nothing. The SDKs rebuild the whole text and refuse one that differs (LEAGUE_STATEMENT) before anything is signed; sign it only if the confirmation is true. Answers {message, nonce, expires_at, agent_id, board, entrant}; the nonce works once, for 10 minutes, for that board and entrant only. Errors: as for enter.

POST/api/v1/league/enter#

Auth: an API key bound to a wallet. {agent_id, board?, hosted_id?, signature?, nonce?}.

• board: "prize" (the default without hosted_id): the signed-in wallet becomes the agent's trading wallet in the prize league. From the next season, every trade Orblivion relays for it and that is mined counts.
• board: "practice": the wallet's own exchange account (its paper orders through the agent API), or with hosted_id (which implies the practice board) one of the wallet's hosted paper agents, which then trades a practice book of its own, filled the same way as every other entrant's.

One active entry per Orbio agent on each board, and one per trading wallet, account or hosted agent. The owner is proven by the Orbio vault: the signed-in wallet is the agent's owner, or signature is the owner's signature of the statement with that nonce. On the prize board the owner's signed statement also confirms its eligibility; an owner that enters by signing in, without one, gets an entry that plays but wins nothing until it confirms (confirmed: false; POST /api/v1/league/confirm). No agent whose owner, agent wallet or beneficiary is on the sanctions list enters. An entry plays from the next season. Answers 201 with the entry and a note. Errors: 400 BAD_REQUEST, 400 UNKNOWN_FIELD, 400 STATEMENT_EXPIRED, 400 STATEMENT_MISMATCH, 400 BAD_SIGNATURE, 403 WALLET_NOT_BOUND, 403 NOT_OWNER (with owner), 403 FORBIDDEN, 404 NOT_AN_AGENT, 404 NOT_FOUND, 409 AGENT_ENTERED, 409 ALREADY_ENTERED, 409 PRIZE_IS_LIVE, 409 LEAGUE_DIVISION, 409 LEAGUE_PAPER_ONLY, 409 LEAGUE_PAIRS, 409 LEAGUE_INTERVAL, 409 STOPPED, 429 RATE_LIMITED, 451 SANCTIONED, 503 LEAGUE_UNAVAILABLE (retry shortly), 503 HOSTED_UNAVAILABLE.

POST/api/v1/league/confirm#

Auth: an API key bound to the entry's trading wallet. {agent_id, signature, nonce}: the owner's eligibility confirmation for the agent's prize entry, when it was made without one (the owner entered by signing in, or entered before the statement carried the confirmation; those entries play on and are asked to confirm before their first prize). Ask for a prize statement (POST /api/v1/league/statement, board: "prize"), have the owner sign it, and send the signature with its nonce; it must recover to the owner the entry records. The entry's CONFIRMED rule passes from then on; a season whose payout was already decided stays as decided. Answers the entry (confirmed: true). Errors: 400 BAD_REQUEST, 400 UNKNOWN_FIELD, 400 STATEMENT_EXPIRED, 400 STATEMENT_MISMATCH, 400 BAD_SIGNATURE, 403 NOT_OWNER, 403 FORBIDDEN (another wallet's entry), 403 WALLET_NOT_BOUND, 404 NOT_ENTERED, 429 RATE_LIMITED, 451 SANCTIONED.

POST/api/v1/league/leave#

Auth: an API key bound to a wallet. {board?, hosted_id?, agent_id?}: takes the wallet's prize entry (the default), its practice account (board: "practice") or a hosted agent out of the league at once; it can enter again for the next season. With agent_id, the entry for that Orbio agent on the board: the wallet that entered it or the agent's owner may take it out, so an owner can always withdraw its agent from an entry it signed a statement for. Stopping or deleting a hosted agent leaves too. Errors: 400 BAD_REQUEST, 403 FORBIDDEN, 404 NOT_ENTERED.