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.

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.

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 <target> for Claude Code, Claude Desktop, Codex, ChatGPT, Cursor, VS Code, or Copilot, or install it as an Agent Plugin. 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 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 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

Install the public CLI and authenticate a model provider as shown above.
Run oracle chain list, then oracle chain use <name>.
Use reads, research, quotes, simulations, and unsigned preparation.
Review every prepared artifact in the wallet that will sign it.
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:

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:

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.

See SETUP.md for clean installation and troubleshooting, docs/locals-only-fee-waiver.md for the 0% holder fee, and 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:

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.
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.
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.

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 and Bitcoin L1 lanes. 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. 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:

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.

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.

122 provider modules in the read/quote catalog, covering 220 unique protocols/venues across EVM, Solana, and Bitcoin (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
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 + HIP-4 outcomes), Polymarket (read + local CLOB prepare)
NFT	OpenSea, Satflow, Magic Eden (Solana); additive owner-local P2 catalog
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

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:

npm i -g @oracle-agent/oracle

Desktop betas: https://oracle.demi.la/downloads/

Or from source, if you want to run the suite:

git clone https://github.com/demi-hl/oracle.git
cd oracle
npm install
npm test

→ 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.
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:

npm run start:data
npm run health

Run the public console (wallet connect, grant editor, receipts):

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:

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, 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 8-lane mesh for Hermes:

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, stable-agent, protocol-builder, plus _template for your own. Details in 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.

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:

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:

oracle-route prepare base <tokenIn> <tokenOut> <yourWallet>

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:

oracle-route prepare-bridge arbitrum base <yourWallet>

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.

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:

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:

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. 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 — 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.