@oracle-agent/operator

Oracle operator

Owner-local signer + key vault for Oracle.

Keys live on your machine (encrypted at rest). Nothing remote receives them. The policy-bounded signer daemon exposes six bounded surfaces: hl, poly, evm-swap, evm-bridge, btc, and sol. Each surface decodes its own envelope and fails closed on empty allowlists. Broader direct execution modules remain available only to trusted owner-controlled code; agent/model code must use the daemon client (signViaDaemon / signer-client).

Pairs with @oracle-agent/oracle (prepare-only public plane).

  your agent
      |
      v
 @oracle-agent/oracle     read / quote / prepare   (no keys)
      |
      | unsigned intent
      v
 @oracle-agent/operator   sign + submit locally    (YOUR encrypted key on YOUR box)
      |
      +-- hl-exec   Hyperliquid trade
      +-- evm-exec  EVM swap / mint / ape
      +-- btc-exec  Bitcoin PSBT sign + broadcast
      +-- sol-exec  Solana mint / buy / list
      +-- poly-exec Polymarket CLOB orders
      |
      v
   venue

Main / hardware wallet is optional (path A for cold high-value). Default agentic path is local operator key (path B).

Install

npm i @oracle-agent/oracle @oracle-agent/operator
# or: npm i @oracle-agent/oracle github:demi-hl/oracle-operator

Start in 5 steps

Source tree: operator 0.14.0 with oracle 0.5.0

Published npm: operator 0.13.7 with oracle 0.4.2 until this source release is published.

Step	What
1	npm i @oracle-agent/oracle@latest @oracle-agent/operator@latest
2	Encrypt keys on your box (npx oracle-vault encrypt …). Never paste keys into a chat.
3	Oracle prepares (no keys).
4	Operator signs with userInitiated: true after you approve.
5	Agent path: run npx oracle-signer (six bounded surfaces, capped). Direct ORACLE_AUTONOMOUS_TRADING=1 unlock is owner-code-only, not an equivalent agent path.

EVM default destinations = known DEX/bridge routers (not open ape). Open any-to is opt-in advanced only.

See SETUP.md for vault paths, daemon policy, and caps.

Quick start

The direct multi-chain API below is for trusted owner-controlled code, not the agent/model process.

mkdir -p ~/.config/oracle/keys && chmod 700 ~/.config/oracle/keys
# encrypt per-chain keys (same vault format)
npx oracle-vault encrypt ~/.config/oracle/keys/evm.key
npx oracle-vault encrypt ~/.config/oracle/keys/sol.key
npx oracle-vault encrypt ~/.config/oracle/keys/btc.wif

# signer process only — do NOT put passphrase in the agent env
export ORACLE_VAULT_PASSPHRASE='...'
export EVM_KEY_FILE=~/.config/oracle/keys/evm.key.vault.json
export SOL_KEY_FILE=~/.config/oracle/keys/sol.key.vault.json
export BTC_KEY_FILE=~/.config/oracle/keys/btc.wif.vault.json
export HL_KEY_FILE=$EVM_KEY_FILE   # HL uses the same secp256k1 key as EVM

import { data } from "@oracle-agent/oracle";
import {
  hlSignAndSubmit,
  evmSignAndSubmit,
  btcSignAndBroadcast,
  solSignAndSubmit,
} from "@oracle-agent/operator";

// HL trade
const hl = await data.call("hl-perps", "prepareOrder", { /* ... */ });
await hlSignAndSubmit(hl, { keyFile: process.env.HL_KEY_FILE, userInitiated: true });

// EVM mint/swap (prepared tx from oracle)
const evm = await data.call("uniswap-v3", "prepareExactIn", { /* ... */ });
await evmSignAndSubmit(evm, {
  keyFile: process.env.EVM_KEY_FILE,
  rpcUrl: process.env.EVM_RPC_URL,
  userInitiated: true,
});

// Bitcoin PSBT (satflow etc)
const btc = await data.call("satflow", "preparePurchase", { /* ... */ });
await btcSignAndBroadcast(btc, {
  keyFile: process.env.BTC_KEY_FILE,
  userInitiated: true,
});

// Solana mint/buy
const sol = await data.call("magiceden-sol", "prepareMint", { /* ... */ });
await solSignAndSubmit(sol, {
  keyFile: process.env.SOL_KEY_FILE,
  rpcUrl: process.env.SOLANA_RPC_URL,
  userInitiated: true,
});

Prepared intents carry a versioned integrity and freshness checksum from @oracle-agent/oracle. The checksum detects mutation and binds preparedAt plus expiresAt; it is not proof of issuer identity. Direct exec functions are for trusted owner-controlled code. The signer daemon independently applies its own surface allowlist, per-action caps, and durable daily budget.

Direct exec calls require userInitiated: true or autonomous: true with ORACLE_AUTONOMOUS_TRADING=1. Bare direct calls are refused.

Full setup: SETUP.md. Threat model: SECURITY.md.

What ships

Module	Role
key-vault	scrypt + AES-256-GCM encrypted key material at rest
oracle-vault CLI	encrypt / rekey / inspect
hl-exec	Hyperliquid sign-and-submit
evm-exec	EVM sign-and-submit prepared txs
btc-exec	Bitcoin PSBT sign + Esplora broadcast
sol-exec	Solana sign-and-submit prepared txs
vault-admin	decrypt/readKeyMaterial — signer process only, not agent root

Hardening (0.6)

• Signer daemon (npx oracle-signer) keeps passphrases and key paths out of the agent process.
• Policy-bounded surfaces are hl, poly, evm-swap, evm-bridge, btc, and sol. Each is a bounded surface, not generic chain authority: evm-swap accepts only decoded Uniswap-v3 swap envelopes, evm-bridge only LI.FI calls whose BridgeData decodes to an allowlisted destination chain and signer-owned receiver, btc only PSBTs with full nonWitnessUtxo input proof, and sol only self-contained transfer messages (address lookup tables and the delegation primitives Approve / ApproveChecked / SetAuthority / Burn / CloseAccount are refused). All six ship enabled by default and fail closed on an unconfigured install — empty allowlists and unset caps refuse before any key access. Narrow the set with ORACLE_SIGNER_SURFACES.
• Mandatory signer caps use ORACLE_MAX_NOTIONAL_USD and ORACLE_MAX_DAILY_NOTIONAL_USD; optional HL ceilings use ORACLE_MAX_LEVERAGE and ORACLE_MAX_ORDER_SIZE.
• Environment-pinned client uses only ORACLE_SIGNER_URL and ORACLE_SIGNER_TOKEN; caller overrides are refused.
• Agent call: signViaDaemon({ surface, prepared }).

Hard rules

• Keys stay local. Do not deploy this as a multi-tenant or public API.
• Do not merge into @oracle-agent/oracle. That package stays prepare-only.
• Model is untrusted. Model code must use signer-client, never direct exec or vault-admin.
• Hot key = limited wallet. Use a dedicated operator wallet, not life savings.
• Checksums are not authorization. Daemon policy is the signing boundary.
• HL withdrawals, transfers, margin updates, and approveAgent are refused. EVM, BTC, and Solana daemon execution is allowed only through their bounded surfaces (evm-swap, evm-bridge, btc, sol), each of which decodes and validates its own envelope and refuses while its allowlists are empty. The broader direct APIs stay owner-process only.

License

Apache-2.0. The Oracle name and marks are reserved.