# Oracle ## Quickstart (standalone CLI) ```bash curl -fsSL https://oracle.demi.la/install.sh | bash # preferred # or: npm i -g @oracle-agent/oracle # Node >= 20.19 oracle --version oracle setup model # choose OAuth or API-key access oracle # native Oracle chat oracle doctor # verify local posture ``` `oracle setup model` offers Anthropic, OpenAI Codex, and Grok OAuth plus secure API-key setup for OpenRouter, OpenAI, Anthropic, xAI, DeepSeek, Gemini, Kimi, Mistral, Nous Portal, Qwen, GLM, and custom OpenAI-compatible providers. `oracle auth status` reports providers without printing credentials. Linux, Windows, and macOS apps are in beta. The CLI, source, and desktop beta are public to everyone. Locals Only holders receive a 0% Oracle integrator fee; the NFT does not gate product access. The package also installs `oracle-investigate`, a bounded report-only forensic CLI: ```bash oracle-investigate --help oracle-investigate capabilities oracle-investigate wallet --family evm --address 0xabc... --chain-id 8453 --limit 20 oracle-investigate wallet --family evm --address 0xabc... --chain-id 8453 --include-opensea oracle-investigate analyze --input ./components.json oracle-investigate overlap --input ./opensea-snapshots.json ``` Every successful investigator command emits one JSON document. It has no signer, prepare, broadcast, arbitrary RPC URL, provider URL, key argument, fetch, transport, or clock option. OpenSea v2 enrichment reads only `OPENSEA_API_KEY`, only after the valueless `--include-opensea` opt-in, and never paginates. Offline `overlap` accepts strict bounded snapshots and performs no fetch. Unsupported or incomplete coverage stays explicit as `NOT_REQUESTED`, `UNAVAILABLE`, `PARTIAL`, or `UNKNOWN`. Hyperliquid core perpetual orders use a 2 bps builder fee; HIP-3 and HIP-4 use 1 bps. The private operator configuration, approval flow, wire units, and holder waiver are documented in [Hyperliquid builder code](docs/hyperliquid-builder-code.md). **Oracle is a self-custody multichain agent control plane.** It reads, quotes, prepares, arms, signs, and broadcasts under owner policy. Specialist agent profiles, real protocol intents, self-custody by default, receipts or it didn't happen. Oracle runs its own agent loop. `oracle chat` starts the Oracle-native agent directly — no external agent runtime required. Any MCP-capable harness can drive it instead: run `oracle mcp install ` for Claude Code, Claude Desktop, Codex, ChatGPT, Cursor, VS Code, or Copilot, or install it as an [Agent Plugin](https://agent-plugins.org/). In that direction the harness calls Oracle as a tool and Oracle's native loop stays in charge. Run `oracle harness detect` to see what is installed and how to wire it. Oracle is listed in the [official MCP registry](https://registry.modelcontextprotocol.io) as `io.github.demi-hl/oracle`; any registry-aware client can launch it with `npx -y -p @oracle-agent/oracle oracle-data-mcp` (stdio). [Hermes](https://github.com/NousResearch/hermes-agent) is one such harness, and also remains available as a legacy delegate that takes over the model loop entirely: `ORACLE_CHAT_BACKEND=hermes oracle chat`. Oracle can run standalone model auth directly with API keys or Claude, Codex, and Grok OAuth. OAuth credentials use the OS keychain when available, with a private `0600` local fallback when keychain storage is unavailable. Wallet-sign and the local `oracle signer` are both first-class. The signer stays off until the owner initializes an encrypted vault and sealed policy. Every sign needs one-use confirmation. Autonomous trading additionally requires `ORACLE_AUTONOMOUS_TRADING=1`. Never paste a seed, key, passphrase, or signer token into Oracle chat or argv. The private `@oracle-agent/agent` package is not included here. --- ## Start safely 1. Install the public CLI and authenticate a model provider as shown above. 2. Run `oracle chain list`, then `oracle chain use `. 3. Use reads, research, quotes, simulations, and unsigned preparation. 4. Review every prepared artifact in the wallet that will sign it. 5. Treat only a confirmed transaction hash plus receipt as execution. Hermes is optional. To add its isolated runtime, specialist profiles, and local read plane later: ```bash oracle bootstrap oracle init --apply # writes profiles + local HMAC attestation config; no wallet key oracle data serve # loopback only: 127.0.0.1:8787 oracle doctor ``` Library users can prepare directly: ```js import { data } from "@oracle-agent/oracle"; const prepared = await data.call("hl-perps", "prepareOrder", { /* coin, side, size, owner wallet address */ }); // Oracle stops here. The user's wallet reviews, signs, and submits. ``` Hosts that need a prepare-only task turn can import `createTaskAdapter` and its shared request/result types from `@oracle-agent/oracle/task`. The entrypoint advertises only `oracle_cli` and `trade_lifecycle`; the host injects both its model provider and read/prepare CLI runner. It does not install an HTTP route or UI. See [docs/task-adapter.md](docs/task-adapter.md). See [SETUP.md](SETUP.md) for clean installation and troubleshooting, [docs/locals-only-fee-waiver.md](docs/locals-only-fee-waiver.md) for the 0% holder fee, and [docs/buzz-integration.md](docs/buzz-integration.md) for the Buzz HTTP contract. --- ## What Oracle is Most "AI crypto agent" projects give a model a hot wallet and hope. Oracle does the opposite: the model *proposes*, the owner *authorizes*, and the policy layer decides what may even be asked. Three properties define it: 1. **Self-custody by default.** Hosted/keyless Oracle never accepts your private key. Those surfaces build unsigned transactions and typed-data intents; your wallet signs them. A self-host install may import a key into the encrypted local vault and arm execution through `oracle signer`. 2. **Bound grants.** A grant is a signed, scoped permission: max value, chain, venue, destination allowlist, plus either a TTL or an explicit trigger condition such as `mint-opens`. Oracle canonicalizes it, renders it for review, and refuses to prepare anything outside it. Runtime enforcement is the wallet's or smart account's job, or the optional local signer's sealed policy when that signer is explicitly enabled. 3. **Receipts or it didn't happen.** A claim without a transaction hash, a receipt is not a result. If a transport cannot verify a balance delta, the receipt must say `balanceDeltaVerified: false`. Default posture is `DISARMED`. ### Context and lifecycle governance Oracle includes the two organization-scale governance layers directly in the public self-hosted package: - `@oracle-agent/oracle/context-graph`: tenant/domain-scoped nodes and edges with mandatory caller-asserted provenance explicitly marked `unverified`, evidence hashes, freshness TTLs, stale exclusion, trusted domain assignments and RBAC, immutable revision history, private atomic storage, and a hash chain that detects corruption and un-rehashed edits. The local hash chain is not an external anti-rollback anchor against a same-UID writer. - `@oracle-agent/oracle/agent-lifecycle`: inventory for agents, tools, workflows, first-class expiring credentials, and external credential references, with last-use/eval health, credential expiry, inactivity retirement, regression quarantine, and owner-reviewed reactivation. Use `oracle context --help` and `oracle lifecycle --help`, or import the APIs. These are local governance surfaces: they add no public HTTP endpoint, expose no credential-value field, reject recognized secret-shaped input, and grant no signing authority. Public self-hosted and operator/admin installations use the same capabilities, safety checks, and execution flow; operator fee configuration is the product-rate difference, not a capability fork. ## Why it's different The differentiators are **policy, custody, and receipts** — not a smarter chat loop. | | Typical agent | Oracle | |---|---|---| | Custody | house wallet holds keys | user signs, no house custody | | Authority | prompt-level "be careful" | signed grant: chain, spend, targets, TTL — enforced by your wallet, not by us | | Destinations | whatever the model emits | reviewed per-chain allowlist, fail-closed | | Slippage | fixed % | live guard recomputed per leg, hard 100 bps cap | | Proof | model says "done" | hash + verified successful on-chain receipt, with `balanceDeltaVerified` true only when snapshots prove the expected delta | | Surface | swap only | swaps, bridges, perps, vaults, yield, NFTs, intents | ## Architecture ``` you | Task | oracle <- routes, never authorizes custody | +------+------+------+------+------+------+------+ | | | | | | | | poly hyper robin solana bitcoin stable protocol market liquid hood builder ``` Each lane is a Hermes **profile**: its own system prompt, skills, memory, and sessions. The `oracle` lane routes intent to the right specialist. Adding a lane is adding a directory. Three planes, and the boundary between them is mechanically enforced: - **Data plane** (public) — read/quote across chains and protocols. No keys. - **Policy plane** (public) — destination allowlists, slippage guards, route and vault attestations, grant schema. Holds no keys; constrains what a signer may be asked to do. - **Exec plane** (self-hosted, optional) — signing and broadcast live only in an explicitly initialized loopback local signer using the user's keys, or in separately operated owner infrastructure. Hosted/keyless Oracle has no active signer. The local-signer module ships policy-bound and grants no holder privilege. `test/custody-boundary.test.mjs` walks the import graph and fails if any public module reaches wallet key material or a house signer. The split is a test, not a promise. ## Coverage ### Universal NFT lifecycle readiness The public package exposes one canonical NFT lifecycle vocabulary—`mint`, `buy`, `list`, `cancel_listing`, and `send`—for deterministic route discovery. The lifecycle module is `ROUTE_ONLY`: an advertised operation is not itself an unsigned transaction or an execution-readiness claim. Concrete provider adapters separately return reviewed unsigned artifacts where implemented. The same capabilities and safety checks apply to public and admin callers. Admin configuration may set other product fees, but these NFT routes and preparations charge zero Oracle fee by default. Current readiness is deliberately adapter-specific: - EVM has OpenSea SeaDrop mint, listing, and cancellation preparation plus exact ERC-721/ERC-1155 safe-transfer preparation. OpenSea buy and sweep preparation are disabled until canonical Seaport target and calldata decoding is shipped; read-only best-listing discovery remains available. Other EVM launchpad routes retain their own declared tiers. - Solana has the separate Magic Eden buy/list/mint provider plus exact, verified Metaplex NFT/Core transfer preparation. The generic universal Solana mint adapter is `RESEARCH_ONLY` and fails closed until canonical serialized-message decoding exists. Marketplace listing cancellation is not currently exposed. - Ordinals has Satflow buy/list, reviewed inscription mint planning, and exact PSBT transfer-plan preparation. Marketplace listing cancellation is not currently exposed. Concrete public data-plane preparation routes stop at unsigned reviewed artifacts; lifecycle route discovery stops earlier at `ROUTE_ONLY`. Solana and Ordinals transfers are prepare-stage plans, and adapter capability tiers must be checked per route. This is not a claim of universal signing, broadcasting, or end-to-end execution readiness. **11 EVM chains** built in: Ethereum, Optimism, BNB, Polygon, Stable, HyperEVM, Abstract, Robinhood Chain, Base, Arbitrum, Avalanche. Plus Solana, Bitcoin L1, and a read-only Canton Coin (CC) lane. Solana covers Jupiter quote/prepare, SPL account research, live simulation of the prepared swap, and Magic Eden NFT reads with unsigned buy/list/mint tickets. Bitcoin covers Esplora fee/UTXO reads, Ordinals/runes research, Satflow PSBT intents, and inscription PSBT preparation. Canton is not EVM: Oracle reads Canton Coin via Scan and explains onboarding; quote/prepare stay fail-closed. Hyperliquid adds HyperCore HYPE staking: validator reads plus EIP-712 stake, delegate, undelegate, and unstake preparation. User wallets sign. **Any other EVM chain is config, not code:** ```js import { registerCustomChain } from "@oracle-agent/oracle/scanner"; registerCustomChain({ key: "mychain", chainId: 7777, name: "My Chain", rpcEnv: ["MYCHAIN_RPC_URL"], nativeCurrency: { symbol: "MYC", decimals: 18 }, }); ``` That chain immediately has block reads, balances, on-chain token resolution, log scanning, and structural risk checks. See [`docs/adding-a-chain.md`](docs/adding-a-chain.md). ```bash oracle-scan chains # coverage matrix oracle-scan token base 0x8335...2913 # on-chain identity oracle-scan pools base 0x4200...0006 # pools ranked by liquidity oracle-scan risk base 0x8335...2913 # structural checks + sell simulation oracle-scan sell base 0x8335...2913 # round trip: can you actually exit? ``` All 11 built-in EVM chains currently report the full 10-capability scanner matrix, including live quote, sell simulation, and unsigned preparation where the selected provider supports that operation. Capability coverage is not a claim that every protocol supports every action; unsupported paths still fail closed. Every venue address was verified **functionally, not by codesize** — a re-runnable prober (`scripts/verify-v3-venues.mjs`) asks each candidate to price a pair with a known answer. This matters: the canonical QuoterV2 address also has bytecode on Base, but does not price that chain's pairs. A codesize check would have allowlisted the wrong contract. **138 provider modules** and **605 operations** in the read/quote catalog, covering **221 unique protocols/venues** across EVM, Solana, Bitcoin, and Canton (115 EVM + cross-chain, 98 Solana venues backed by 101 verified Jupiter program IDs, 6 Bitcoin surfaces). One module can cover many protocols: the Jupiter module alone routes 98 Solana venues, so provider-module count and protocol count are different numbers. | Class | Providers | |---|---| | Chain / explorer | EVM JSON-RPC, Blockscout, Solana RPC, Bitcoin Esplora, Canton Scan (CC) | | Market data | DexScreener, GeckoTerminal, DeFiLlama | | DEX / aggregator | Uniswap V3/V4, Aerodrome, Curve, Balancer, LI.FI, ParaSwap, Odos, 0x, 1inch, HyperEVM DEXes | | Solana | Jupiter (98 venue labels, 101 verified program IDs) | | Intents | CoW Protocol, RFQ | | Perps / lending / yield | GMX v2, Morpho, Pendle | | Bridges | Across, Hop, Relay | | Venues | Hyperliquid (core perps + HIP-3 builder dexs, including EntropyIO `io` + HIP-4 outcomes), Polymarket (read + local CLOB prepare) | | NFT | OpenSea, Satflow, Magic Eden (Solana); additive owner-local P2 catalog; opt-in held-NFT pump alerts | | Alerts | Opt-in, one-recipient monitoring for eligible OpenSea-held collection floors through Telegram, Discord, or WhatsApp | | Bitcoin | mempool/Esplora, Ordinals, Runes, UniSat, Best-in-Slot, Satflow | Every provider and every scanner capability declares an honest tier — `read-only`, `quote-only`, `prepare`, or `intent`. **API coverage is not execution support**, and the catalog says which is which. A chain with no verified venue is fail-closed for routing value: read and research work, moving money does not. That is a safe default, not a gap. ## Capability pack Oracle's default pack is deliberately broad but disarmed: - **Trader** — best-execution route comparison, quote/prepare, simulation, and receipt checks; no set-and-forget custody. - **Builder** - chain-family fungible-token and NFT-collection launch plans, protocol, gacha, DEX, and launchpad scaffolds with unsigned deploy/admin actions. Unsupported chain adapters fail closed instead of pretending one deploy fits all. - **Analyzer** — token, contract, venue, portfolio, market, and risk research with evidence labels. `/balance` or plain `balance` runs one deterministic snapshot across every configured EVM chain plus Solana, Bitcoin, Hyperliquid, and discoverable NFTs. Profile-local observations power history and SVG value graphs; unavailable values stay null instead of becoming fake zeroes. - **On-chain scanner** — chain-config scanners for tokens, pools, launches, risk, exits, and smart-wallet boards. - **Meme-token sniper** — fast launch/liquidity monitoring across configured chains, guarded by identity checks, sell-sim/reverse-route proof, caps, and unsigned user-wallet tickets. - **Per-chain graphs + Telegram cards** — charted scanner alerts, route cards, meme-launch cards, Hyperliquid HIP-3/HIP-4 cards, and Polymarket cards. User API-key actions activate only when self-hosted keys are configured. - **NFT mint gas-war limits** — public mint bots enforce chain-bound gas caps, per-unit fee caps, and optional priority-fee caps before returning unsigned mint transactions. Import `validateNftMintGasWar` from the package root or `@oracle-agent/oracle/nft-gas-war`. - **Cross-chain RFQ + tokenized assets** — RFQ/intent venues are compared across supported chains where configured, and tokenized Robinhood-style assets can be bought only after exact contract, venue, route, and sellability checks. - **Solana** — SPL accounts, Jupiter quotes, unsigned swap transactions, and simulation. - **Bitcoin** — L1 reads, Ordinals/runes, Satflow PSBT intents, and inscription PSBT preparation. Every money-moving path stays prepare/simulate first. Signing and broadcast are wallet/grant actions, not model authority. Meme-token sniping defaults to fast scan + prepared ticket; blind broadcast requires a separate capped local signer loop and explicit opt-in. NFT mint bots must also honor gas-war caps before any wallet-signable transaction is returned. RFQ and tokenized-asset routes are capability-labeled per chain; unconfigured venues stay unavailable instead of faked. ## Install ```bash curl -fsSL https://oracle.demi.la/install.sh | bash oracle setup model oracle chat ``` Requires Node `20.19.0` or newer (the curl installer checks). npm still works: ```bash npm i -g @oracle-agent/oracle ``` Desktop betas: https://oracle.demi.la/downloads/ Or from source, if you want to run the suite: ```bash git clone https://github.com/demi-hl/oracle.git cd oracle npm install npm test ``` **→ [SETUP.md](./SETUP.md) covers public data credentials and the separate owner-local source lane.** The short version: - Reads and quotes need **no keys**. - Hosted/keyless Oracle exposes no cloud signer, key vault, or broadcast path. - User wallets authorize prepared actions outside the public data plane, or the self-host local signer executes them under local policy. - The npm package includes an optional self-hosted loopback signer for the user's own keys. It stays inert until local initialization and sealed policy setup. Private Administrator modules remain separate and are not published on npm. - The documented `oracle signer` path permits built-in bounded native EVM transfers, recognized approvals, decoded EVM swaps and bridges, EVM NFT mint envelopes, Bitcoin PSBTs, and Solana messages under the user's encrypted local vault and sealed policy. `hl` and `poly` are not public local-signer families. ### Action vocabulary and execution planes Oracle keeps capability and authorization separate: - Public Oracle reads, quotes, simulates, and prepares artifacts. Self-host installs can execute supported artifacts through the local signer. - **Path A:** owner/main, browser, smart-account, hardware, or protocol-native wallets sign the prepared artifact. This is the default self-custody path. - **Path B:** the optional public local signer may sign on the same host after explicit init, sealed policy, and loopback start. Private Administrator modules remain unpublished and are not a holder install. - The optional local signer decodes and binds bounded native EVM transfers, recognized approvals, strict EVM swap/bridge calldata, EVM NFT mint envelopes, Bitcoin PSBTs, and Solana messages. It refuses while required allowlists, local keys, RPC URLs, simulation, signed-byte verification, receipt binding, or ledger accounting are missing. - Ordinary EVM preparation remains user-wallet signed unless a trusted owner-controlled direct-exec process is explicitly installed and armed. - `ORACLE_AUTONOMOUS_TRADING=1` is direct execution for trusted owner-controlled local code only. It is never model/agent authority and should not be framed as equivalent to the `oracle-signer` agent-process path. - `ORACLE_AUTONOMOUS_MINT=1` is a separate switch for fail-closed NFT mint one-shots only. It does not unlock swaps, bridges, or perps. Trading does not imply mint. - `ORACLE_PINNED_SESSION_LIVE=1` cannot arm an on-chain session module. The merge fuse `PINNED_SESSION_MODULE_LIVE` stays off until every desk chain is pinned or explicit-unsupported and a privileged review issues GO. Default is off. Setting the env var alone is a refuse, not an enable. The optional session vault is per-user: they supply owner + recovery; Oracle prepares unsigned deploy/initialize; their wallet signs. No house recovery default. Native-only execute: user names EOA pay targets. Contracts and routers are refused. After they opt in, `prepareOptInVaultSpend` builds unsigned vault.execute (agent signs). Skip = Oracle unchanged. 7702 is not seed-theft protection. - A deployment may separately install a same-host, owner-gated EVM executor. Oracle must verify that executor before describing bounded EVM execution as available. Missing deployment capability means "unavailable here," not "Oracle can never execute EVM." - `watch`, `watch this`, and `ping me` always create `active: true, actionMode: alert_only`. - `arm` creates `active: true, actionMode: execute` only for one exact owner-authorized action. It is never inferred from a watch. The package exports this binding as `@oracle-agent/oracle/action-semantics`. Legacy watch stores can migrate `status: watching|armed` with `migrateLegacyWatchRecord()`; because it is specifically a watch-store migration, both statuses become `alert_only`, never execution authority. Run the read-only data plane: ```bash npm run start:data npm run health ``` Run the public console (wallet connect, grant editor, receipts): ```bash npm run start:public # http://127.0.0.1:8799/ ``` This is an unauthenticated loopback development server, not a holder gate or a public deployment. Keep it off LAN/tailnet/public interfaces and place a tested admission gateway in front of any hosted beta. ## Model providers Oracle is a library. Drive it with Claude, GPT, Gemini, Grok, a local model, or a plain script — the tools are ordinary functions plus an MCP server: ```bash npx oracle-data # local read plane on 127.0.0.1:8787 npx oracle-data-mcp # MCP stdio server (any MCP client); needs oracle-data up ``` Per-profile routing is worth setting up under a multi-profile harness such as [Hermes](https://hermes-agent.nousresearch.com/docs), because a trading stack is several workloads with opposite needs and **per-profile routing** gives each its own model, tools, and key scope: cheap wide context for research, a fast model for execution where latency is money, the strongest model for risk review, something small for unattended crons. The research profile can hold no signing key at all. Oracle's native loop covers the single-agent case on its own. Oracle's own pre-release audit ran four model lineages — Grok 4.5, Opus 5, Fable 5, GPT-5.6 — and **each found a critical bug the others missed**. One model reviewing its own work would have shipped three of them. ## Agent profiles Oracle ships an installable 9-lane mesh for Hermes: ```bash oracle-init # dry run -- shows exactly what it would do oracle-init --apply # create profiles, install SOULs + skills, wire MCP config npx oracle-data # keep running — MCP tools call the local read plane on :8787 oracle # premium boxed TTY on the same oracle profile as messaging oracle model # choose provider/model; persona stays oracle oracle chain use hyperliquid oracle setup # telegram / discord / slack messaging ``` Terminal and configured messaging channels are untrusted proposers into the same Hermes `oracle` profile. They cannot self-confirm or directly invoke the optional signer. Signing stays in the user wallet or in the explicitly enabled, loopback-only public local signer after independent local confirmation and sealed-policy checks. Private Administrator execution remains separate. Lanes: `oracle` (router), `polymarket-agent`, `hyperliquid-agent`, `robinhood-agent`, `solana-agent`, `bitcoin-agent`, `canton-agent`, `stable-agent`, `protocol-builder`, plus `_template` for your own. Details in [`docs/profiles.md`](docs/profiles.md). Every model lane remains unable to authorize signing. It may only read, simulate, and prepare; local key initialization arms user-initiated actions, while Disarm is globally dominant. An existing `SOUL.md` is never overwritten without `--force`, and `--force` writes a timestamped backup first. Oracle does not issue its own model credential. Standalone chat uses the OAuth login or API key the user configured; a delegate harness uses whichever provider that installation already supports. **What you get where:** Oracle's read plane is an MCP server, so any MCP client can call it, and the native loop brings its own memory, skills, scheduler, and bounded tools. The multi-lane *mesh* in the diagram above — per-lane memory, skills, sessions, and a separate model choice per specialist — is profile machinery from a multi-profile harness such as Hermes. Use Oracle from any agent, or on its own; add a profile mesh only if you want that topology. ## Teams A team is a compiled, hash-pinned pipeline of specialist agents that turns public evidence into an operator handoff. It never signs and never broadcasts. ```js import { TEAM_TEMPLATES, compileTeamDefinition } from "@oracle-agent/oracle"; const compiled = compileTeamDefinition(TEAM_TEMPLATES[0], { nowMs: Date.now() }); compiled.team.agents.map((a) => a.role); // scanner -> sentiment -> strategy -> risk -> executor ``` Seven templates ship in the box (`hyperliquid-alpha`, `perp-market-breadth`, `perp-technical-strategy`, `basket-relative-value`, `wallet-watch`, `evm-launch-radar`, `nft-mint-guard`) across six modes: `draft`, `shadow`, `confirm`, `armed`, `autonomous`, `halted`. The shape is enforced at compile time. A definition is refused if the executor is not the terminal agent, if any non-executor holds executor tools, if the policy omits wallet confirmation or a kill switch, if the chain allowlist is unbounded, if the policy has already expired, or if `autonomous` is requested without an explicit opt-in. Secret-like values and DAG cycles are rejected outright. Compilation is deterministic: key insertion order does not change the `teamHash`, so the same team is the same identity across machines. Every handoff reports `executionAllowed: false`, `backendSigner: false`, `signingReady: false`, and `broadcastReady: false`. Teams are a library surface. They run in the **Oracle desktop app** — the CLI stays a single-agent shell. Drive them from the desktop, your own harness, or a service. Full reference in [`docs/teams.md`](docs/teams.md). ## Best-execution routing The highest quote is not the cheapest swap. Oracle ranks on **net received after gas and fees**, comparing every available source in parallel: ```bash oracle-route swap base 0x4200...0006 0x8335...2913 # WETH -> USDC oracle-route bridge arbitrum base # ETH across chains ``` ``` source net out gross cost * paraswap 1,903.880867 1,903.893053 $0.01 cow 1,903.693798 1,903.693798 gasless (solver) lifi 1,894.432632 1,899.20966 $4.78 ``` Sources: **LI.FI, CoW, ParaSwap, 0x, 1inch** for swaps · **LI.FI, Relay, Across** for bridges. 0x and 1inch activate when their API key is present; the rest need none. Why net matters: - **Gas is part of the price.** A route quoting 0.2% more but costing $14 more in gas loses on a $500 swap and wins on a $50k one. The crossover depends on trade size, so any fixed preference is wrong on one side of it. - **Intents can beat AMMs.** CoW's solver pays the gas, so a slightly lower gross quote often wins on net — the case naive ranking always gets backwards. - **Sources disagree about what they mean.** Some report gas in USD, some in native wei, some not at all. Oracle normalizes, and marks what was measured. **Unknown cost is never scored as zero.** A source that does not report gas is ranked on gross and flagged, because scoring an unknown as free is how the worst route wins a comparison. When the top two routes measure cost differently, Oracle quotes **no spread at all** rather than a number that compares different things. Then prepare the winner in one step: ```bash oracle-route prepare base ``` You get back an **unsigned transaction** (LI.FI, ParaSwap, 0x) or **EIP-712 typed data** for an off-chain order (CoW). `artifactKind` says which — they need different wallet actions, and one is not broadcast at all. Prepare **re-quotes** and reports `driftBps` against the comparison, because a minimum computed from a stale quote is not a minimum. Bridges prepare too: ```bash oracle-route prepare-bridge arbitrum base ``` Bridge artifacts are always a **list** of transactions — some routes need an approval and a deposit signed in order, and signing only the first leaves funds approved but not bridged. Both chains are reported, and a transaction whose chain does not match the origin is refused. Oracle states plainly that **bridging is not atomic**: the origin transaction confirming does not mean funds arrived. Routing never signs. `taker` must be the real wallet; placeholder addresses are rejected, since quoting is anonymous but preparing is not. Signing happens in the user's wallet or in a separately operated source-only execution lane. Individual source failures degrade the comparison by one source instead of breaking it — verified in practice when Odos sunset their public API mid-development (HTTP 410); the router kept ranking and the provider was marked `unavailable`. ## On-chain equities — Crossbook (HIP-3 / Arcus / RH / Solana / TON) Tokenized equities span multiple venues. Oracle ranks them the same way as swaps: net of known costs, with unknown costs never scored as free. ```bash oracle equities venues oracle equities quote NVDA --size 1000 oracle equities quote SPY --size 500 --json oracle equities prepare NVDA --recipient 0xYourWallet # or: oracle-equities quote NVDA --size 1000 ``` Import surface: `@oracle-agent/oracle/equities` (`bestEquityRoute`, `equityVenues`, `prepareEquityRoute`). MCP tools: `equity_venues`, `equity_quote`, `equity_prepare`. Only Robinhood-chain Uniswap is prepare-tier in v1. HIP-3, Arcus, Solana xStocks, and TON ston.fi are quote-only discovery. `bestPreparable` is separate from the overall winner so a quote-only mid is never presented as actionable. ## Examples These run from a **repo clone**, not from the installed npm package: they import `../src/` directly, and the published tarball ships the bundled `dist/` instead of `src/`. Clone the repo, `npm install`, then: ```bash node examples/add-a-chain.mjs # register an unseen chain, no code node examples/research-a-token.mjs # honest token research on live data node examples/oracle-pack-template.mjs # skeleton for a safe Oracle protocol pack ``` ## MCP Oracle exposes its read plane over the Model Context Protocol, so any MCP client (Hermes, Claude Code, others) can use it: ```bash oracle-data-mcp ``` ## Security - Hosted/keyless Oracle cannot hold keys. Self-host imports write only to the local encrypted vault. - The router can propose, simulate, explain, and draft. It cannot authorize. - Public default modules may not import house-signer or executor code (enforced by test). The optional `./local-signer` export is the self-host path. - Destination allowlists are per-chain and fail-closed: an empty allowlist refuses everything rather than allowing everything. - Report vulnerabilities per [SECURITY.md](SECURITY.md). Please do not open a public issue for a live exploit. ## What Oracle is not - Not an autonomous trader. There is no "set and forget." - Not custodial. If a design needs your key on our server, that design is wrong. - Not a guarantee. Crypto execution carries real risk; read the code you run. ## License [Business Source License 1.1](LICENSE) — source-available, not open source. You may read, modify, self-host, and use Oracle freely for internal use, evaluation, research, and personal use. What you may not do is offer Oracle, or substantially its functionality, to third parties as a competing product or hosted service without a commercial license. Each version converts to **Apache-2.0** on its Change Date (four years after release). Versions `0.1.0` through `0.11.0` were published under Apache-2.0 and remain under those terms. The **Oracle** name and marks are reserved; please don't imply endorsement by an official deployment when shipping a fork. For commercial licensing, contact the maintainer.