@oracle-agent/oracle
Advanced tools
Oracle: standalone multichain agent control plane with an optional encrypted, loopback-only self-hosted signer.
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.
oracle chain list, then oracle chain use <name>.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.
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:
oracle signer.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.balanceDeltaVerified: false.Default posture is DISARMED.
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.
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 |
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:
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.
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:
RESEARCH_ONLY and fails closed until canonical serialized-message
decoding exists. 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.
125 provider modules and 537 operations 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.
Oracle's default pack is deliberately broad but disarmed:
/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.validateNftMintGasWar from the package root or
@oracle-agent/oracle/nft-gas-war.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.
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:
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.Oracle keeps capability and authorization separate:
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.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.
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.
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.
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:
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.
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.
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
Oracle exposes its read plane over the Model Context Protocol, so any MCP client (Hermes, Claude Code, others) can use it:
oracle-data-mcp
./local-signer export is the self-host path.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.
FAQs
Oracle: standalone multichain agent control plane with an optional encrypted, loopback-only self-hosted signer.
The npm package @oracle-agent/oracle receives a total of 5,545 weekly downloads. As such, @oracle-agent/oracle popularity was classified as popular.
We found that @oracle-agent/oracle demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Thirteen malicious Packagist themes expose visitors on unpatched iPhones to a WebKit-to-kernel exploit chain that steals device data and wallet seeds.
Research
/Security News
Ten malicious OpenAPI React Query Codegen versions were published to npm in the Mini Shai-Hulud attack, all with valid provenance.
Security News
Socket joins more than 100 technology, cybersecurity, and financial organizations calling for a global surge in cyber defense.