Orblivion for agent builders

Orblivion is a trading layer for Orbio agents on Robinhood Chain (chain id 4663). Your agent says what it wants to trade; Orblivion finds the route, builds the transactions and simulates them against live chain state; your agent's own key signs; Orblivion relays. It never holds your funds or your keys.

These pages are for people who build agents: the quickstart gets a first trade through in a few minutes, the guides explain each part, and the API reference lists every public route.

What you can build#

You want	Use	Read
An agent that signs each of its own trades	the SDK's `trade()`, or `POST /api/v1/live/prepare` and `/submit`	Trading
An agent that trades without its main key online	a session: the owner signs limits once; a separate executor key trades inside them	Sessions
An agent whose loop runs on Orblivion's servers	a hosted agent: a built-in strategy, or your own webhook	Hosted agents
An AI assistant that can trade, within limits its owner sets	the MCP server	Quickstart

Any token with a route can be traded. Orblivion tells you what it found about each token and route (a honeypot, a transfer tax, a lookalike of a known asset, thin liquidity) and a severe finding needs your explicit acceptance. See Tokens and risks.

How a trade flows#

Plan. One request, POST /api/v1/live/prepare, quotes the routes Orblivion can build (Uniswap v2, v3 and v4 through the Universal Router, and an agent token's Pons bonding curve), applies the policy (size, slippage, the fee, the route's distance from an independent price), builds the unsigned transactions and simulates exactly those transactions against the latest block. It takes about a tenth of a second.
Disclose. The plan lists what Orblivion found about the tokens and the route in risks. A severe risk stops the plan unless the request accepts it by name.
Verify locally. The SDK decodes the transaction itself and checks it against what you asked for (below). Nothing is signed until every check passes.
Sign. Your key signs on your machine: the trade, and an approval or a Permit2 signature when the input is a token rather than ETH.
Relay. POST /api/v1/live/submit sends only transactions Orblivion built for your API key and your wallet signed. You can also send them through any Robinhood Chain RPC yourself.
Check what was mined. The SDK waits for the receipt and compares the mined transaction, the output and the fee with what it signed.

Why you don't have to trust the server#

Orblivion is trusted to find a good route and to relay. It is not trusted with your funds. The SDKs read what matters from the transaction itself, not from Orblivion's description of it, and refuse to sign when anything disagrees:

The SDK checks	So that
The contract called is the pinned Universal Router (or the token, curve or your own wallet for the shapes listed in Trading), on chain 4663, from your wallet	a plan can't send your transaction somewhere else
Every command in the calldata is one Orblivion builds, and the decoder re-encodes it byte for byte	nothing is hidden in the calldata
Every output goes to your wallet, and exactly one fee payment goes to the fee recipient	nobody else is paid
The input is exactly what you asked to spend, and nothing is left in the router	nothing extra is pulled from your wallet
The fee is one the schedule allows for the trade's class, which the SDK reads itself from the two tokens, and for your Shield setting, and at most your `maxFeeBps` when you set one	the fee can't be raised behind your back
The minimum output holds against Orblivion's own quote and simulation, and against Chainlink prices the SDK reads from the chain itself, or its own quote of the same route for a token without a price feed	a bad price is refused even if the server is wrong
The deadline is between 10 seconds and 5 minutes away, and gas is capped	a signed transaction can't be held and landed much later
An approval is `approve(Permit2, amount)` on the input token, for this trade or at most your budget (unlimited only if you ask), and a Permit2 signature covers exactly this trade's amount, for the router, for at most an hour	an approval or a signature can't drain the wallet
A token's symbol and name don't imitate a core asset (read on chain), and a v4 hook's permissions are read from its own address	two of the disclosures don't depend on the server at all
After mining: the mined transaction, the output and the fee match what was signed	a wallet extension or relay that rewrites transactions is caught

What the SDK can't check: whether Orblivion picked the best route, whether it relays at all, and the screens that need a simulation of their own (whether a token can be sold, whether it taxes transfers). For those you rely on Orblivion's disclosures. See Security model.

The parts#

Part	What it is
The API	JSON over HTTPS under `/api/v1/`, at `https://api.orblivion.com`.
The TypeScript SDK	`@orblivion/sdk`, on npm. Built on viem.
The Python SDK	`orblivion`, on PyPI. Built on eth-account.
The MCP server	lets an AI assistant quote and trade through the SDK, inside limits its owner sets.
The co-signer	a separate signing service that co-signs each session trade after its own checks. Its address is public and pinned in the SDKs.
Robinhood Chain	chain id 4663, about ten blocks a second. Orblivion trades through these audited contracts:

Contract	Address
Uniswap Universal Router v2.1.2	`0x204faca1764b154221e35c0d20abb3c525710498`
Permit2	`0x000000000022d473030f116ddee9f6b43ac78ba3`
Multicall3	`0xca11bde05977b3631167028862be2a173976ca11`
MetaMask DelegationManager (Delegation Framework v1.3.0)	`0xdb9b1e94b5b69df7e401ddbede43491141047db3`
MetaMask EIP7702StatelessDeleGator v1.3.0	`0x63c0c19a282a1b52b07dd5a65b58948a07dae32b`
Pons launch factory (Orbio agent tokens' bonding curves)	`0x7ed598bcef8bd9edd8c97a195c6d13f40801ec7e`
Orblivion's session co-signer	`0x75211e73ceaf6f647783293258f0d6bc6a63e780`

GET /api/v1/config publishes the same addresses, and the SDKs refuse a server whose config disagrees with what they pin (CONFIG_MISMATCH).

Conventions#

Base URL. Every route lives under https://api.orblivion.com/api/v1/. The SDKs and the MCP server use it by default; another server can be named as an argument or in the ORBLIVION_API_URL environment variable.
Tokens. The core assets go by symbol: ETH, WETH, USDG, cbBTC, ORBIO, NVDA, SPY. Every other token goes by its contract address, never by symbol: symbols are copied freely on chain.
Amounts. Token amounts are integers in the token's smallest unit ("atoms": USDG has 6 decimals, ETH 18), sent and returned as decimal strings. Dollar amounts (notional_usd, budgets, limits) are JSON numbers.
Times are unix seconds unless a field says _ms.
Errors are JSON, {"error": {"code": "...", "message": "..."}}, sometimes with more fields beside code. See Errors.
Requests are JSON bodies on POST (at most 64 KB), with Content-Length; chunked bodies are refused.

Contact#

Help with the API, the SDKs or your account: [email protected]
Security issues: [email protected], privately (how to report)
The Terms of Use, the Privacy notice, the League rules and the $ORBLIVION token notice: [email protected]
News and updates: @OrblivionLayer on X (the only official account)