Orblivion starter bot (Python)
==============================

A trading bot you run on your own computer. It trades through Orblivion on Robinhood Chain, and you change one file:
strategy.py. The full guide: https://orblivion.com/docs/starter-bot.html

Files
  strategy.py       YOUR LOGIC: decide(market, book, state) returns the orders to place. The only file to edit.
  config.toml       the settings: tokens, how often, dry run, session or direct mode, limits, the session's caps
  bot.py            the loop: prices and balances -> decide -> limits -> trade (or dry run) -> log
  setup_wallet.py   one-time setup (keys, funding, the session), status, and the off switches (revoke, reset-code)

Needs Python 3.10 or later.

Quick start
  pip install "orblivion>=0.1.1"
  python setup_wallet.py          make the keys, fund them, grant the session (anything sent asks for SEND)
  python bot.py                   a dry run: it decides, checks and logs, and sends nothing
  ... read bot-log.jsonl, then set dry_run = false in config.toml ...
  python bot.py                   live

Stop it with Ctrl+C, or create a file named STOP in this folder.
End the session at any time: python setup_wallet.py revoke

The off switches
  python setup_wallet.py revoke       ends the session: the wallet's own transactions disable the session's
                                      delegation and set its approvals back to 0, then Orblivion stops co-signing.
                                      session.json keeps the session's revocation record (no secret), so revoke builds
                                      those transactions here and sends them straight to Robinhood Chain, even when
                                      Orblivion doesn't answer, then reads them back. That needs an SDK with
                                      Grant.revocation_record (pip install -U orblivion); with an older one revoke
                                      takes its on-chain steps from Orblivion's answer.
  python setup_wallet.py revoke --chain-only
                                      the same transactions from session.json alone, with nothing asked of Orblivion,
                                      and the chain's answer read from it alone: for when Orblivion's answer disagrees
                                      with session.json.
  python setup_wallet.py reset-code   the emergency switch: makes the wallet a plain account again (its code removed by
                                      its own transaction, straight to Robinhood Chain). No session can move anything
                                      from it after that. It doesn't revoke the session or reset the approvals: setting
                                      the code again brings the session back until it expires, so revoke as well.

How it keeps you safe
  - dry_run = true is the default. A dry run asks Orblivion for a quote (session mode) or a plan (direct mode):
    nothing is co-signed, signed or sent, and none of the session's limits are used.
  - The bot's own limits ([limits]) cut every order: per trade, per rolling 24 hours (bot-ledger.json), at most what
    the wallet holds, and nothing under $1.
  - In session mode (the default) the bot holds only the executor key. The wallet signed a session that lets it trade
    only these tokens, only up to the [session] caps, until it expires. Orblivion's co-signer and the chain enforce
    those caps on every trade, whatever the bot does.
  - Every trade is checked by the SDK before anything is signed: the route, the minimum output, the fee, the recipient.

The keys live in ~/.orblivion-bot (config.toml: key_dir), outside this folder, and are never printed. Anyone with
wallet.json controls the wallet: don't share or commit it, and use a wallet that holds only what the bot trades.

Session mode sets a plain wallet's code to MetaMask's EIP7702StatelessDeleGator (EIP-7702), which sessions run on.
The key stays the owner, and the wallet works as before; an authorization to address 0 undoes it.

What the bot writes here
  bot-log.jsonl     every tick, decision, order, dry run, trade and error, one JSON line each
  bot-ledger.json   what it spent in the last 24 hours (dry runs and live trades apart)
  bot-state.json    the strategy's state, kept between runs

This is example code, not financial advice. You bear the outcome of every trade it makes:
https://orblivion.com/docs/terms.html
MIT License: ../LICENSE.txt