Oracle documentation

Install, configure, and operate Oracle as a self-custody multichain agent control plane. Start with reads and quotes, prepare exact artifacts, and keep authorization separate from model output.

Reads, research, quotes, simulations, and unsigned preparation do not require a wallet key.
Never paste a seed phrase, private key, passphrase, or API credential into chat.
An action is complete only with a transaction hash and a successful receipt.

Oracle 0.36.1Node 20.19+Public self-host

Install

Oracle runs on Linux, macOS, and Windows. The installer uses a user-local directory and does not require a global npm install.

terminal

curl -fsSL https://oracle.demi.la/install.sh | bash
oracle --version
oracle setup model
oracle

Oracle 0.36.1 requires Node.js 20.19.0 or newer. If you prefer npm, install @oracle-agent/oracle globally.

npm

npm i -g @oracle-agent/oracle
oracle --version

Start keyless

Reads, research, quotes, simulations, and unsigned preparation do not require a wallet key. Never paste a seed phrase, private key, passphrase, or API credential into chat.

What Oracle is

Oracle is a standalone agent loop and a Model Context Protocol server for multichain work. It can research tokens and contracts, compare routes, simulate, prepare transactions and typed data, inspect portfolios, and verify receipts.

Data planeReads, market data, chain state, quotes, and capability health. No wallet keys.

Policy planeAllowlisted destinations, value caps, slippage limits, expiry, and exact artifact binding.

Execution planeUser wallet by default. Optional self-hosted local signer only after explicit initialization and policy.

Hosted and keyless Oracle prepares unsigned artifacts. A user wallet can review and sign them. An optional self-hosted local signer can sign supported artifacts only under local policy and explicit authority.

Quick links

Start hereGetting startedInstall, select a model, choose a chain, and verify the local posture. User guideUsing OracleChat, read, quote, prepare, sign, and verify without collapsing the lifecycle. IntegrationsMCP connectorsConnect Claude, Codex, ChatGPT, Cursor, VS Code, and generic MCP clients. Web toolsBrowser and webSearch, fetch, browse public pages, use a granted Chrome tab, and connect xurl safely. Core conceptSecurity and executionUnderstand grants, confirmation, local signing, autonomous opt-in, and receipts.

Safe defaults

Oracle starts disarmed.
Unknown data stays unknown. Missing values do not become zero.
Route rankings use net received when gas and fees are measurable.
Prepare is not sign. Sign is not broadcast.
An action is complete only with a transaction hash and a successful receipt.

0.36.0 and 0.36.1 published

0.36.0 and 0.36.1 are published on npm, as recorded in CHANGELOG 0.36.1; neither label proves deployment on another surface. Source: CHANGELOG (CHANGELOG.md, this source tree).

Public data and connectors

Hyperliquid public market contexts, books and candles are available to the local Teams scanner. HyperTracker provides paid BYO-token cohorts, liquidation risk, wallet profiles, closed trades, biggest positions and freshness.

Hypedexer provides keyed public-market REST health, hip3Dexs and recentLiquidations, not its separate 91-tool hosted MCP.

Every Hypedexer call, including health, spends one request; no retries, pagination, filters or cursors; limits are 2 MiB, 10,000 rows and 10-second default/15-second maximum timeout. Unknown freshness/completeness stays unknown. Sources: catalog (packages/oracle/src/data/catalog.mjs, revision 12f21dd5), CHANGELOG (CHANGELOG.md, this source tree).

Hosted HyperTracker and Hypedexer need their respective ORACLE_HYPERTRACKER_HOSTED_ENABLED=1 / ORACLE_HYPEDEXER_HOSTED_ENABLED=1 flag, configured REST credentials and canonical hypertracker / hypedexer server-credential opt-in. The Hypedexer MCP key is separate. Sources: HyperTracker provider (packages/oracle/src/data/providers/hypertracker.mjs, revision 12f21dd5), Hypedexer provider (packages/oracle/src/data/providers/hypedexer.mjs, revision 12f21dd5).

Pear public health, baskets and symbolMap reads are hidden unless ORACLE_TEAMS_PEAR=1. Teams adds no Pear private trading; Pear execution, if any, happens through the owner's own Pear connection. Jupiter quotes and prepares unsigned Solana swaps; signing remains separate. Sources: catalog (packages/oracle/src/data/catalog.mjs, revision 12f21dd5), Teams schema (packages/oracle/src/teams/schema.mjs, revision 12f21dd5).

Teams and hedges stay shadow-only in this guide

Keep Teams in shadow-only mode here. Shadow and confirm modes never execute; Pear templates refuse armed/autonomous modes.

Separate owner-armed local execution paths exist for bounded Hyperliquid orders, EVM token snipes, NFT mints and Solana swaps, requiring explicit local authority and execution limits. Their presence does not authorize a shadow run. Sources: Teams behavior (packages/oracle/docs/teams.md, revision 12f21dd5), CHANGELOG (CHANGELOG.md, this source tree).

TxFlow and RISEx provide keyless health, markets, fundingSnapshot and book; TxFlow adds fees and RISEx adds fundingHistory. Hosted reads need the respective ORACLE_TXFLOW_HOSTED_ENABLED / ORACLE_RISEX_HOSTED_ENABLED flag. Funding is decimal/hour with raw values retained; unknown or stale ranking inputs are excluded. Sources: catalog (packages/oracle/src/data/catalog.mjs, revision 12f21dd5), CHANGELOG (CHANGELOG.md, this source tree).

The TxFlow/RISEx hedge scaffolding ships off and shadow-only, with empty execution allowlists and no account or key. Its modules and signer surface are not wired to any shipped Oracle command, server or signer: there is no live hedge entry point in 0.36.x.

Its arm gate lists prerequisites; satisfying these prerequisites does not by itself enable execution. They include an exact owner grant, coin/total notional caps, maximum loss, leverage at most 3x, expiry, a signer handle and ORACLE_AUTONOMOUS_TRADING=1.

They also include confirmed venue facts and fees, fresh market/account reads, a trusted clock, chosen margin mode, liquidation thresholds and kill-switch policy, a perps-only RISEx session key and persistent nonce/consumed-hedge-ID stores, among others.

The arm gate's coin scope is BTC/ETH/SOL. Unknown facts block arming; a read flag is not execution authority. Sources: arm gate (packages/oracle/src/perp-hedge/arm-gate.mjs, revision 12f21dd5), signer surface proposal (packages/oracle/src/perp-hedge/policy.mjs, revision 12f21dd5), CHANGELOG (CHANGELOG.md, this source tree).

MCP and 0.36.1 fixes

MCP results redact secret-bearing keys before serialization and suppress HTML cards when redaction changes the result. Card-render failure logs are redacted and size-capped; programmer errors are not swallowed. Source: CHANGELOG (CHANGELOG.md, this source tree).

0.36.1 changes isolate home/config and attestation-secret test readers, stabilize session/wallet/pairing/account/snapshot fixtures, bound degraded card/MCP diagnostics and pin lint policy/dependencies.

Hedge guards share process-wide rate budgets, enforce exact minimum sizes and live price bands, and require durable monotonic TxFlow nonces; allowlists remain empty.

Split-chat chunks retain distinct lowercase hexadecimal identities for identical module bytes. Lifecycle/evaluator tests verify environment scrubbing before exact socket-preload injection.

Local-control profile provisioning and signer/kill-lock reconciliation are deferred to 0.36.2. Source: CHANGELOG (CHANGELOG.md, this source tree) 0.36.1.