Build an AI trading agent

An AI agent is a hosted agent whose brain is a model: you write the strategy in plain words, and on every tick a model on Orbio's gateway reads it with the agent's market view and decides. Orblivion checks every answer before anything trades, and Orblivion's own Orbio credits pay for the model by default, so you need no LLM key. This guide's script creates the agent on paper first, then goes live inside a session you sign, and switches it off. It comes in Python and TypeScript, and it uses only the published SDKs (orblivion 0.1.1 or later, @orblivion/sdk 0.1.1 or later).

Last updated: 12 October 2026

What it is#

The agent runs on Orblivion's servers, so your computer can be off. Every 15 minutes (its interval_s, 900 seconds):

1. Orblivion builds what the model sees: your strategy, the agent's tokens with their bid, ask and reference price, its book, its last few fills, its recent price history and the notes it left itself last tick.
2. The model answers with its reasoning, at most max_orders orders, and new notes.
3. Orblivion checks the answer field by field. An answer that breaks any rule trades nothing that tick.
4. Each order then goes through the agent's limits, the market guards and the risk terms, as any brain's orders do, and is filled on paper or traded live.

You edit one file, strategy.txt. It starts as Orblivion's "trend" template:

Follow the trend on my pairs. Buy a token when its reference price has risen over the last several ticks and the spread is tight; sell it when the trend turns down, or when the position is 3% below the price you bought at (write your entry prices in your notes).
Keep at least 40% of the book in USDG. Trade small: about a quarter of the per-trade limit, the full limit only when the trend is strong and steady. If nothing changed, hold.

Lines that start with # are notes for you and aren't sent. The rest goes to the model as your words, after Orblivion's fixed rules, which it can't change: 1 to 1,500 characters, at most 40 lines. options lists the other templates (mean_reversion_stop, dca_timing).

Who pays for the model#

With funding: "orblivion", the default, Orblivion pays from its own Orbio credits: a daily pool sized from what Orblivion's Orbio account earns and holds, always keeping 30 more days of it in reserve, shared fairly. Each wallet gets one share a day, whatever its agents:

• The credits pay only for the cheap models, and only for an agent that thinks every 15 minutes or slower. options lists the server's models, which ones the credits pay for, and an estimate a day. The script's default model, anthropic/claude-haiku-5.5, is one of them in Orblivion's default settings; the server estimates it at about $0.06 a day at one tick every 15 minutes, and up to $0.12 if every answer used the whole output allowance.
• budget_usd_day (default $0.25) is the agent's own cap on its model calls in a UTC day.
• Without a share, or once the share, the day's pool or the budget is used up, the agent keeps ticking but doesn't call the model, so it doesn't trade, until 00:00 UTC. The script sets fallback_own: false: it never spends your own Orbio balance. To let it continue on your agent's CREDIT, sign in with Orbio once and set fallback_own: true (or funding: "own").
• A live share follows the fees: the default agent's $0.06 a day needs about $0.88 of fees over 14 days behind it, about $350 of ETH and USDG trades at 0.25%. The pool is also split fairly between wallets, so a share can be smaller.
• options shows where your wallet stands: the trial, a live share, the trades and fees behind it, and today's pool. A new wallet that owns no Orbio agent has no share yet: its agents tick without thinking until it has traded through Orblivion, for example with the starter bot.

Each decision in the agent's log says which model ran, what it cost and who paid; watch and status print them, and GET /api/v1/hosted/<id>/spend lists every call.

What the model can and can't do#

• Its answer is checked before anything trades. It must be one JSON object with exactly reasoning, orders and memory. Anything else (a malformed answer, one cut off at the model's output limit, a token outside the pairs, a size over the limit, too many orders) means no trade that tick, logged with its reason. So does a call that fails or times out.
• Token names are data. Whoever deployed a token chose its name and symbol, so they reach the model only as data, cleaned and quoted, after rules saying nothing in the data is an instruction.
• Every order passes the same checks as any brain's: the agent's limits (per trade, per day, the largest position in any token but USDG), the market guards, the policy and the risk terms. A live agent makes at most one trade a tick, inside its session's caps.
• Three failures in a row pause it. A failed call or a refused answer counts as a failure; a spent budget or share is a hold, and the agent keeps ticking.

Download#

Put each version in a folder of its own.

The code is under the MIT License (LICENSE.txt). Read it before you run it: it's short on purpose.

Quick start#

Python 3.10 or later, or Node.js 20 or later.

pip install "orblivion>=0.1.1"
python agent.py keys          # the wallet's key, in ~/.orblivion-ai-agent
python agent.py options       # templates, models, and who pays for this wallet
python agent.py paper         # the agent on paper, then watch it think

npm install
npm run keys                  # the wallet's key, in ~/.orblivion-ai-agent
npm run options               # templates, models, and who pays for this wallet
npm run paper                 # the agent on paper, then watch it think

1. Keys. keys makes the wallet's key in ~/.orblivion-ai-agent (key_dir), outside the script's folder. It is never printed. The Python and TypeScript versions share the folder.
2. Options. options lists the strategy templates, the models with an estimate a day, and who pays for this wallet's model calls (above).
3. Paper. paper creates the agent on paper from strategy.txt, then watches it for 30 minutes (paper 60 for an hour): each decision with its reasoning, its cost and who paid, each order and paper fill, and the day's spend. Ctrl+C stops watching, not the agent; watch picks it up again.

Going live#

python agent.py live          # after you type SEND

npm run live                  # after you type SEND

First send the wallet what the agent may trade (ETH and USDG on Robinhood Chain, 4663), plus about $4 of ETH for the setup and the executor's gas. live shows what it will do and waits for you to type SEND. Then:

1. It pauses the paper agent, so the two don't share the wallet's one share.
2. It creates the live agent. Orblivion answers with the agent's executor, a key its signing service made for this wallet and this agent and never lets out. The SDK checks the co-signer's attestation of it before the wallet signs anything (Hosted agents).
3. The wallet signs a session for that executor: ETH and USDG only, $10 a trade and $40 a day (the agent's limits), 100 trades, for 168 hours. Signing sends nothing.
4. It sends the session's setup from the wallet: on a plain wallet, its code set to MetaMask's EIP7702StatelessDeleGator (Sessions), and a Permit2 approval of at most $40 of USDG.
5. It sends the executor twice what Orblivion says it needs for gas (about ten trades' worth at the gas cap), never more than max_gas_usd ($3). The executor pays only this agent's gas.
6. It switches the agent on and watches it.

The off switch#

python agent.py off           # after you type SEND

npm run off                   # after you type SEND

off stops both agents (final), ends the live agent's session (Orblivion stops co-signing at once, then transactions from the wallet end it on chain and set its approvals back to 0: Revoking), and sends what is left of the executor's gas back to the wallet. Orblivion holds that refund until no trade signed before the stop can still land (at most about two minutes); the script waits and asks again.

agent.json keeps the live session's revocation record, so off builds the on-chain steps on your computer and sends them straight to Robinhood Chain, even when Orblivion doesn't answer (The revocation record). It marks the session off once the chain confirms it ended (for a session without a revocation record, once the steps Orblivion named read back done, which is Orblivion's word), so a later off sends again whatever is still needed. When only Orblivion's answer stands in the way (it names a root agent.json doesn't hold, and none your wallet signed), a rerun won't change that: off --chain-only ends the session from agent.json alone, asks Orblivion nothing, and marks it off once the chain confirms it; a later off stops the agent and gets the gas back. When Orblivion's answer carries a root your wallet signed that still reads live, agent.json is most likely an older session's record: off says so and asks before disabling that root too. If Orblivion can't be reached, off still ends the session on chain, and the gas refund waits for the next off: the executor's key is in Orblivion's signing service. That needs SDK 0.1.3 or later (Python and TypeScript); with an older SDK, off takes its on-chain steps from Orblivion's answer and says to update the SDK.

Keep in mind#

• It runs on Orblivion's servers. Closing the script doesn't stop the agent; off does. status shows both agents, today's model spend and the executor's gas.
• A model can be wrong. It can misread the market or your words. The limits are the backstop: keep them small, and watch it on paper first. Paper fills are simulated against live chain state; live trades pay gas and the session's fee, and prices move.
• The session's USDG budget is approved once, at one day's cap ($40), for the session's whole life. Once less than $1 of it is left, the agent pauses (SESSION_BUDGET): run off, then live for a new agent and session. Selling ETH needs no budget.
• A session lasts at most 30 days (session.hours, at most 720). When it ends, the agent stops trading: off, then live again.
• The key in ~/.orblivion-ai-agent controls the wallet. Never share or commit it, and use a wallet that holds only what the agent trades.
• Change the settings at the top of the script (SETTINGS): the pairs, the model, how often it thinks, the budget, the limits, the session. A faster agent or a bigger model isn't paid by Orblivion's credits.
• This is example code, not financial advice. You bear the outcome of every trade it makes. See the Terms of Use.