@oracle-agent/oracle 0.1.0

package/docs/architecture.md

@@ -0,0 +1,135 @@
+# Architecture
+
+Three planes. The boundary between them is enforced by a test, not a convention.
+
+```
+                    user's wallet
+                         ^
+                         | signs (only the user can)
+                         |
+   +---------------------+---------------------+
+   |            unsigned artifacts             |
+   |                                           |
+   |  PUBLIC (this repo)                       |
+   |                                           |
+   |  data plane      read / quote             |
+   |  policy plane    allowlists, guards,      |
+   |                  attestations, grants     |
+   |  control plane   grant lifecycle,         |
+   |                  session keys, AA, router |
+   +-------------------------------------------+
+                         |
+                         x  no import may cross
+                         |
+   +-------------------------------------------+
+   |  PRIVATE (not published)                  |
+   |  keystore, house signer, exec-server      |
+   +-------------------------------------------+
+```
+
+## Why three planes
+
+The design assumption is that **the model can be wrong or adversarially steered**.
+Everything follows from treating it as an untrusted proposer.
+
+If the model is untrusted, then authorization cannot come from the model. It comes
+from an owner signature over a bounded grant. And if authorization is separate from
+proposal, then the code that proposes must be unable to reach the code that signs —
+otherwise the separation is aspirational.
+
+That is why the boundary is a test (`test/custody-boundary.test.mjs`) rather than a
+paragraph in a README. It walks the import graph from every shipped entrypoint and
+fails on:
+
+- a private module present in the tree
+- any public module importing signer or key material
+- a dangling local import (extraction left something behind)
+- a secret-shaped literal anywhere
+
+## Data plane
+
+`src/data/` — 30+ providers, each declaring an honest tier.
+
+| Tier | Meaning |
+|---|---|
+| `read-only` | data only; no execution claim |
+| `quote-only` | can price a route; no reviewed transaction builder |
+| `prepare` | returns a policy-bound unsigned transaction |
+| `intent` | returns typed data to sign (CoW orders, GMX orders) |
+
+The tier is load-bearing. "We support protocol X" is ambiguous and has caused real
+confusion; the tier is not. **API coverage ≠ execution support.**
+
+`src/data/catalog.mjs` is the registry; `dataHealth()` probes liveness. Note the
+distinction in health output: a promise that resolved with `{ok: false}` is
+*degraded*, not healthy — and an HTTP 200 serving an explorer error page is not a
+successful read.
+
+## Policy plane
+
+The moat. Holds no keys; constrains what a signer may be asked to do.
+
+- **Destination allowlist** (`src/venues.mjs`) — per chain, fail-closed. An empty
+  allowlist refuses everything. It never means "allow anything."
+- **Auto-slippage** (`src/auto-slippage.mjs`) — a guard computed from live depth and
+  volatility per leg, recomputed before each broadcast. A caller-supplied tolerance
+  is a *maximum*, not the selected value. Hard ceiling 100 bps; over that, block and
+  requote rather than widen.
+- **Attestations** (`route-`, `vault-`, `gmx-attestation.mjs`) — dynamic execution
+  targets require an attestation minted inside the trusted boundary. Model-authored
+  JSON is not authorization.
+- **Approval guard** — exact-amount approvals, never unlimited by default, with
+  allowance read back after the approve lands.
+
+Guards are re-checked at **sign and broadcast** time. A stale minimum is not a
+minimum.
+
+## Control plane
+
+`src/public-control/` — grant schema and rendering, session-key model, ERC-4337
+adapter, bundler client, grant indexer.
+
+`src/router/` — model routing with a custody firewall. `risk-classifier.mjs` scores
+an action's risk; `proposal.mjs` refuses to construct a proposal containing
+dangerous fields (private keys, mnemonics, bearer tokens) at any nesting depth. The
+router can propose, simulate, explain, and draft. It cannot authorize.
+
+## Scanner framework
+
+`src/scanner/` — makes a chain data rather than an integration.
+
+- `contract.mjs` — 10 capabilities, a validator, a registry, coverage matrix
+- `evm-scanner.mjs` — one generic implementation for any EVM JSON-RPC chain
+- `chains.config.mjs` — the 11 built-ins as config, plus `registerCustomChain()`
+
+Unimplemented capabilities are **absent, not faked**: calling one throws a message
+naming what *is* supported. A caller can never mistake `undefined` for a negative
+result.
+
+Evidence labels (`LIVE` / `CACHED` / `STALE` / `UNKNOWN` / `UNAVAILABLE`) and risk
+verdicts (`PASS` / `CAUTION` / `FAIL` / `UNKNOWN`) exist to stop the collapse that
+causes losses: **`UNKNOWN` is not `PASS`**, and "we could not check" is a different
+fact from "there is nothing there."
+
+## Agent mesh
+
+`profiles/` + `skills/` — seven installable Hermes lanes plus a template.
+
+A lane is narrow on purpose: smaller context is cheaper and more accurate, per-lane
+memory doesn't cross-contaminate, and a grant scoped to one lane can't be spent by
+another.
+
+Every lane ships DISARMED, and every grant action a lane may request is read,
+simulate, or prepare. No lane may request broadcast or signing — enforced in
+`test/profiles.test.mjs`, so widening custody cannot pass review quietly.
+
+No lane pins a model. `profile.json` carries a capability *class*
+(`strong-reasoner`, `fast-tool-caller`), so the installer never writes a vendor into
+a user's config.
+
+## What is not here
+
+The exec plane: keystore, house signer, local-signer service, exec-server,
+capability minting, and the venue adapters that hold signing authority. That is
+operator infrastructure. Its absence is the point — a self-hosted Oracle has nothing
+to steal.

package/docs/profiles.md

@@ -0,0 +1,132 @@
+# Agent profiles
+
+Oracle is not one agent. It's a mesh of specialists with a router in front.
+
+```
+        you
+         |
+       Task
+         |
+      oracle            <- routes, never authorizes custody
+         |
+  +------+------+------+------+------+------+------+
+  |      |      |      |      |      |      |      |
+ poly   hyper  robin  solana bitcoin stable protocol
+ market liquid hood                         builder
+```
+
+Each lane is a [Hermes](https://github.com/NousResearch/hermes-agent) **profile**:
+its own system prompt, skill set, memory, and session store. They share a wallet
+policy and a receipts discipline, nothing else.
+
+## Why profiles instead of one big agent
+
+Three practical reasons, learned the hard way:
+
+1. **Context stays small.** A Polymarket question shouldn't load Bitcoin
+   ordinals knowledge. Smaller context is cheaper, faster, and more accurate.
+2. **Memory doesn't cross-contaminate.** What the perps lane learned about
+   funding rates should not leak into the NFT lane's judgment.
+3. **Blast radius is bounded.** A grant scoped to one lane's venues can't be
+   spent by another.
+
+## The lanes
+
+| Profile | Owns | Typical grant |
+|---|---|---|
+| `oracle` | routing, synthesis, multi-chain comparison | read + simulate only |
+| `polymarket-agent` | prediction markets, event odds, CLOB cards/API-key order intents | read, quote, prepare |
+| `hyperliquid-agent` | perps, spot, HIP-3 builder dexs, HIP-4 outcomes | read, quote, prepare |
+| `robinhood-agent` | Robinhood Chain (4663) tokens, NFTs, tokenized Robinhood-style assets, capped NFT mints | read, quote, prepare |
+| `solana-agent` | Solana swaps, research, Jupiter routes | read, quote, prepare |
+| `bitcoin-agent` | Bitcoin L1, Ordinals/runes, inscriptions | read, prepare:inscription |
+| `stable-agent` | Stable (988), USDT-native gas quirks | read, quote, prepare |
+| `protocol-builder` | scaffold, review, prepare protocol/NFT/gacha/DEX deploys and mint bots | prepare:deploy, prepare:mint, simulate |
+| `_template` | your new lane | you decide |
+
+`protocol-builder` can design a protocol and prepare an unsigned deploy or mint
+bot transaction. It never house-signs, and its destinations and gas-war caps are
+allowlisted like any other lane.
+
+## Model choice is yours
+
+Oracle makes **no model calls**. It has no LLM client, no API key, no inference
+dependency — its runtime deps are `ethers`, `viem`, and three `@noble`/`@scure`
+crypto libraries. Every lane inherits whatever provider your Hermes is configured
+with.
+
+So there is nothing to sign up for. If Hermes already talks to a model, Oracle
+works.
+
+What profiles *do* give you is **per-lane** model choice, because each profile has
+its own `config.yaml`:
+
+```yaml
+# ~/.hermes/profiles/<name>/config.yaml
+model:
+  provider: anthropic        # or openai-codex, nous, xai-oauth, a local model...
+  default: claude-opus-5
+```
+
+That lets you put a heavy reasoner on the router and something cheap and fast on
+a polling lane:
+
+| Lane | Wants | Why |
+|---|---|---|
+| `oracle` | strongest reasoner | routing and synthesis need judgment |
+| `protocol-builder` | strongest reasoner | contract review is unforgiving |
+| `hyperliquid-agent` | fast, numeric, tool-heavy | many small tool calls |
+| `polymarket-agent` | news-shaped reasoning | event pricing is narrative |
+| research fan-out | cheap and parallel | breadth over depth |
+
+Starting point, not doctrine. Benchmark on your own workload.
+
+### If you want one login for many models
+
+Optional convenience, not a requirement: [Nous
+Portal](https://nousresearch.com) fronts the frontier set (Claude, GPT, Grok,
+DeepSeek, Qwen and more) behind a single Hermes credential, so each lane can pick
+a different model without five separate API keys and five bills.
+
+```bash
+hermes auth add nous
+```
+
+Any Hermes-supported provider works equally well. Oracle does not care.
+
+## Creating a lane
+
+```bash
+hermes profile create polymarket-agent
+```
+
+Then give it a `SOUL.md` (who it is, what it owns, what it must refuse) and a
+`config.yaml` (model + provider). Point it at Oracle's MCP read plane:
+
+```bash
+hermes mcp add oracle-data --command "oracle-data-mcp"
+```
+
+Now that lane can read 30+ providers across 11 chains, quote real routes, and
+prepare unsigned transactions — and it still cannot sign anything.
+
+## Posture
+
+Every lane starts `DISARMED`. Arming is a deliberate, scoped, expiring act:
+
+```
+grant:
+  chain: 8453
+  actions: [read:chain, simulate:tx, prepare:swap]
+  targets: [<router address>]
+  maxValueWei: <cap>
+  expiresAt: <unix ts>
+```
+
+An action outside the grant is refused, not negotiated. When the grant expires,
+the lane goes back to reading.
+
+## A rule worth keeping
+
+Give a lane the narrowest grant that makes it useful, and let it expire. A
+permanent broad grant is just a hot wallet with extra steps.

package/examples/add-a-chain.mjs

@@ -0,0 +1,65 @@
+// Example: register a chain Oracle has never seen, then use it.
+//
+// Run:  node examples/add-a-chain.mjs
+//
+// The point of this example is that there is no adapter to write. A chain is a
+// config object; the generic EVM scanner supplies the capabilities.
+
+import { registerCustomChain } from "../src/scanner/chains.config.mjs";
+import { scannerCoverage } from "../src/scanner/contract.mjs";
+
+// 1. Describe the chain. Note rpcEnv holds VARIABLE NAMES, not URLs -- endpoints
+//    stay in the environment so nothing sensitive lands in source control.
+const scanner = registerCustomChain({
+  key: "examplechain",
+  chainId: 424242,
+  name: "Example Chain",
+  rpcEnv: ["EXAMPLECHAIN_RPC_URL"],
+  nativeCurrency: { symbol: "EXC", decimals: 18 },
+  explorer: "https://explorer.example",
+
+  // Omitted deliberately: dexscreenerSlug. Without it, pool discovery reports
+  // UNAVAILABLE rather than guessing -- a wrong slug would return another chain's
+  // pools, which is worse than no answer.
+
+  // Omitted deliberately: venues. With none, the chain is read/research capable and
+  // fail-closed for routing value. Adding one requires recorded provenance; see
+  // docs/adding-a-chain.md.
+});
+
+console.log(`registered: ${scanner.name} (chain ${scanner.chainId})`);
+
+// 2. Ask what it can actually do. The answer is honest -- unimplemented
+//    capabilities are listed as unsupported, not silently absent.
+const caps = scanner.capabilities();
+console.log(`\nsupported   (${caps.supported.length}): ${caps.supported.join(", ")}`);
+console.log(`unsupported (${caps.unsupported.length}): ${caps.unsupported.join(", ")}`);
+
+// 3. An unimplemented capability throws with an actionable message. It never
+//    returns undefined, which a caller could mistake for "no result".
+try {
+  await scanner.quote({ from: "0x", to: "0x", amount: "1" });
+} catch (err) {
+  console.log(`\nquote() correctly refused:\n  ${err.message.split("\n")[0]}`);
+}
+
+// 4. Pool discovery is UNAVAILABLE, and says why.
+const pools = await scanner.resolvePools("0x1111111111111111111111111111111111111111");
+console.log(`\nresolvePools evidence: ${pools.evidence}`);
+console.log(`  reason: ${pools.reason}`);
+
+// 5. Live reads need an RPC. Show the exact variable to set rather than failing
+//    with a generic network error.
+console.log(`\nto make live reads, set one of: ${scanner.rpcEnv.join(", ")}`);
+try {
+  const head = await scanner.blockNumber();
+  console.log(`  head: ${head.blockNumber} (${head.evidence})`);
+} catch {
+  console.log("  (no RPC configured -- expected for this example chain)");
+}
+
+// 6. The coverage matrix now includes it alongside the built-ins.
+const cov = scannerCoverage();
+console.log(`\ncoverage: ${cov.chainCount} chain(s) registered`);
+const mine = cov.chains[424242];
+console.log(`  examplechain failClosed for routing: ${mine.failClosed}`);

package/examples/research-a-token.mjs

@@ -0,0 +1,70 @@
+// Example: research a token end to end, honestly.
+//
+// Run:  node examples/research-a-token.mjs
+//       node examples/research-a-token.mjs base 0x<address>
+//
+// Demonstrates the discipline the desk is built around: read the identity off the
+// chain, find pools with real liquidity, and report UNKNOWN where a check could not
+// run rather than letting silence read as approval.
+
+import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
+import { getScanner, listScanners, EVIDENCE, RISK } from "../src/scanner/contract.mjs";
+
+registerBuiltinScanners();
+
+const chainRef = process.argv[2] || "base";
+// Base USDC by default -- a token whose answers are easy to sanity-check.
+const token = process.argv[3] || "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+
+const scanner =
+  listScanners().find((s) => s.key === chainRef) || getScanner(Number(chainRef));
+if (!scanner) {
+  console.error(`unknown chain "${chainRef}"`);
+  process.exit(1);
+}
+
+console.log(`chain: ${scanner.name} (${scanner.chainId})`);
+console.log(`token: ${token}\n`);
+
+// 1. Identity from the CONTRACT, not a token list. A list can be stale or omit a
+//    two-hour-old launch, and the on-chain answer is what governs a transfer.
+const meta = await scanner.resolveToken(token);
+if (meta.evidence !== EVIDENCE.LIVE) {
+  console.log(`identity: ${meta.evidence} -- ${meta.warning ?? meta.error}`);
+  console.log("stopping: without ERC-20 metadata there is nothing to price.");
+  process.exit(0);
+}
+console.log(`identity: ${meta.symbol} (${meta.name}), ${meta.decimals} decimals`);
+
+// 2. Pools, ranked by liquidity. Depth is what determines your fill; the headline
+//    price is a fiction for anything but the smallest clip.
+const pools = await scanner.resolvePools(token);
+console.log(`\npools: ${pools.evidence}`);
+if (pools.reason) console.log(`  ${pools.reason}`);
+for (const p of pools.pools.slice(0, 5)) {
+  const liq = p.liquidityUsd == null ? "unknown" : `$${Math.round(p.liquidityUsd).toLocaleString()}`;
+  console.log(`  ${p.dex.padEnd(14)} ${liq.padStart(14)}  ${p.pair}`);
+}
+
+// 3. Structural risk. Read the verdict AND the individual checks -- an overall
+//    UNKNOWN often hides several passes plus one unprovable item, and which item is
+//    unprovable is the decision-relevant part.
+const risk = await scanner.scoreRisk(token);
+console.log(`\nrisk verdict: ${risk.verdict}`);
+for (const c of risk.checks) {
+  console.log(`  ${c.result.padEnd(8)} ${c.check.padEnd(16)} ${c.detail ?? ""}`);
+}
+
+// 4. The honest close. UNKNOWN is not PASS, and a buy path is not an exit path.
+console.log("");
+if (risk.verdict === RISK.FAIL) {
+  console.log("FAIL: disqualifying finding above. Do not trade.");
+} else if (risk.verdict === RISK.UNKNOWN) {
+  console.log(
+    "UNKNOWN is not PASS. Structural checks looked fine, but sellability is\n" +
+      "unproven without a verified router on this chain. Until a round-trip sell\n" +
+      "simulation succeeds, treat this token as not exitable.",
+  );
+} else {
+  console.log(`${risk.verdict}: structural checks only -- still not a recommendation.`);
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@oracle-agent/oracle",
+  "version": "0.1.0",
+  "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default — the public package never takes your key. Built for Hermes; no model key required.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/demi-hl/oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/demi-hl/oracle.git"
+  },
+  "keywords": [
+    "ai-agent",
+    "multichain",
+    "evm",
+    "self-custody",
+    "defi",
+    "hermes",
+    "nous",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "oracle-data": "./bin/desk-server.mjs",
+    "oracle-public": "./bin/oracle-public-server.mjs",
+    "oracle-data-mcp": "./bin/oracle-data-mcp.mjs",
+    "oracle-init": "./bin/oracle-init.mjs",
+    "oracle-scan": "./bin/oracle-scan.mjs",
+    "oracle-route": "./bin/oracle-route.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./data": "./src/data/desk-data.mjs",
+    "./policy": "./src/public-control/policy-schema.mjs",
+    "./chains": "./src/chains.mjs",
+    "./scanner": "./src/scanner/index.mjs",
+    "./router": "./src/router/index.mjs",
+    "./nft-gas-war": "./src/nft-gas-war-guard.mjs"
+  },
+  "scripts": {
+    "test": "ORACLE_TEST_ISOLATE_SECRETS=1 ORACLE_ROUTE_ATTESTATION_SECRET=oracle-unit-test-secret node --test test/*.test.mjs",
+    "test:boundary": "ORACLE_TEST_ISOLATE_SECRETS=1 ORACLE_ROUTE_ATTESTATION_SECRET=oracle-unit-test-secret node --test test/custody-boundary.test.mjs",
+    "e2e:solana-bitcoin": "node scripts/e2e-solana-bitcoin.mjs",
+    "e2e:hypercore-staking": "node scripts/e2e-hypercore-staking.mjs",
+    "start:data": "node bin/desk-server.mjs",
+    "start:public": "node bin/oracle-public-server.mjs",
+    "scan:public-apis": "node scripts/public-api-scan.mjs",
+    "health": "node -e \"import('./src/data/desk-data.mjs').then(m=>m.data.health().then(h=>console.log(JSON.stringify(h,null,2))))\"",
+    "init": "node bin/oracle-init.mjs",
+    "init:apply": "node bin/oracle-init.mjs --apply",
+    "scan": "node bin/oracle-scan.mjs",
+    "verify:venues": "node scripts/verify-v3-venues.mjs",
+    "route": "node bin/oracle-route.mjs",
+    "scan:secrets": "node scripts/secret-scan.mjs",
+    "test:count": "node scripts/check-test-count.mjs",
+    "test:count:update": "node scripts/check-test-count.mjs --update"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@scure/base": "^2.2.0",
+    "ethers": "^6.16.0",
+    "viem": "^2.55.8"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "profiles/",
+    "skills/",
+    "public/",
+    "artifacts/",
+    "README.md",
+    "SETUP.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "docs/",
+    "examples/",
+    "scripts/",
+    "!bin/oracle-vault.mjs",
+    "!src/key-vault.mjs",
+    "!src/data/providers/hl-exec.mjs"
+  ]
+}

package/profiles/_template/SOUL.md

@@ -0,0 +1,47 @@
+# your lane
+
+> Template. Copy this directory, rename it, and rewrite this file.
+
+## What you own
+
+One sentence. A lane that owns "crypto" owns nothing — the whole point is a narrow
+remit so the context stays small and the memory stays clean.
+
+## The thing that bites people here
+
+Every venue has one. Perps have liquidation. Low-caps have honeypots. New chains
+have dry bridges. Solana has blockhash expiry.
+
+Write yours here, concretely, with the check that catches it. This section is the
+reason the lane exists; a generic assistant will not know this.
+
+## Hard rules
+
+Keep these. They are the desk's invariants, not suggestions:
+
+1. **You do not sign.** Transactions are prepared for the user's wallet.
+2. **A grant is authorization; your reasoning is not.** Outside the grant's chain,
+   venue, destination, spend cap, or TTL → refuse, and say which bound broke.
+3. **Receipts or it didn't happen.** No hash, no receipt, no balance delta → it
+   did not succeed.
+4. **Never invent chain facts.** Not from a live read → `unknown`.
+
+Then add rules specific to your venue.
+
+## Voice
+
+Terse. Answer first, evidence second. State confidence: `high` / `moderate` /
+`low` / `unknown`.
+
+---
+
+## Wiring it up
+
+```bash
+hermes profile create my-lane
+hermes mcp add oracle-data --command "oracle-data-mcp"
+```
+
+Then copy this `SOUL.md` into `~/.hermes/profiles/my-lane/SOUL.md` and set the
+model in that profile's `config.yaml`. `bin/oracle-init` does all of this for the
+bundled lanes — read it if you want to script your own.

package/profiles/_template/profile.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "./profile.schema.json",
+  "id": "_template",
+  "label": "your lane",
+  "role": "venue",
+  "color": "#8892a0",
+  "description": "Copy this directory to add a lane. Rename the id, write the SOUL, list your chains.",
+  "template": true,
+  "model": {
+    "note": "Pick per workload. Heavy judgment -> strong reasoner. Many small tool calls -> fast model.",
+    "suggested": "balanced"
+  },
+  "skills": ["oracle-receipts"],
+  "mcp": ["oracle-data"],
+  "chains": [],
+  "posture": {
+    "default": "DISARMED",
+    "grantActions": ["read:chain", "simulate:tx"],
+    "signing": "user-wallet",
+    "rationale": "Start read-only. Widen the grant only once the lane has proven it behaves."
+  }
+}

package/profiles/bitcoin-agent/SOUL.md

@@ -0,0 +1,31 @@
+# bitcoin agent
+
+You cover **Bitcoin mainnet**: L1 reads, Ordinals/runes research, Satflow market
+PSBTs, and inscription preparation.
+
+## What you own
+
+Fees, tip height, addresses, UTXOs, transactions, inscription metadata, rune and
+ordinal reads, collection/item market data, and user-wallet inscription PSBT
+preparation.
+
+## Bitcoin is not EVM
+
+- Bitcoin uses UTXOs, PSBTs, commit/reveal flows, and fee-rate bidding. Do not
+  translate EVM calldata assumptions into Bitcoin.
+- Public signing is user-wallet. Xverse, UniSat, Leather, OKX, Phantom, Magic
+  Eden, or compatible injected wallets sign the PSBT.
+- Operator WIF/local signing is not part of the public lane.
+
+## Inscription hard rules
+
+1. Check health, fee rates, and the body-size cap before preparing.
+2. Show content hash, byte length, MIME type, destination, change address, fee rate,
+   and estimated cost before the user signs.
+3. Explain commit/reveal as non-atomic.
+4. Never request or print seed, WIF, xprv, or wallet export.
+5. Never claim success without commit/reveal txids and inscription id when known.
+
+## Voice
+
+Short. Fee-aware. State confidence explicitly. If a fee/read is stale, re-read it.

package/profiles/bitcoin-agent/profile.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "./profile.schema.json",
+  "id": "bitcoin-agent",
+  "label": "bitcoin agent",
+  "role": "venue",
+  "color": "#F7931A",
+  "description": "Bitcoin L1: Esplora reads, Ordinals/runes research, Satflow PSBTs, and inscription preparation.",
+  "model": {
+    "note": "Bitcoin/Ordinals work is irreversible and fee-sensitive; wants a careful verifier.",
+    "suggested": "careful-verifier"
+  },
+  "skills": [
+    "oracle-bitcoin",
+    "oracle-receipts",
+    "oracle-circuit-breaker",
+    "oracle-smart-wallet-scanner"
+  ],
+  "mcp": [
+    "oracle-data"
+  ],
+  "chains": [],
+  "nonEvm": "bitcoin-mainnet",
+  "posture": {
+    "default": "DISARMED",
+    "grantActions": [
+      "read:chain",
+      "prepare:inscription"
+    ],
+    "signing": "user-wallet",
+    "rationale": "Bitcoin inscriptions are commit/reveal PSBTs. Oracle prepares and verifies; the user's Bitcoin wallet signs."
+  }
+}

package/profiles/hyperliquid-agent/SOUL.md

@@ -0,0 +1,34 @@
+# hyperliquid agent
+
+You cover **Hyperliquid** — perps and spot — plus HyperEVM (chain 999).
+
+## What you own
+
+Mids, order books, funding rates, open interest, positions, and liquidation
+distance. You read the public `/info` API through Oracle's data plane.
+
+## Leverage changes the job
+
+On a spot desk a bad entry costs you basis points. Here it can close the account.
+So before any sizing discussion:
+
+- **liquidation distance** in percent, not dollars
+- **funding** — a position that pays 40% annualized funding is a slow loss even
+  when the thesis is right
+- **book depth at your size** — the mid is irrelevant if you cross 80 bps to fill
+- **cross vs isolated** — cross margin means one bad leg can take the others
+
+## Hard rules
+
+1. **Always state liquidation distance** when discussing a leveraged position.
+   Not optional.
+2. **Funding is a cost, not a footnote.** Quote it in annualized terms.
+3. **Never size to "max."** If the user asks for maximum leverage, give the
+   number and state the liquidation move that wipes it.
+4. **You do not sign.** Orders are prepared for the user's wallet.
+5. **Receipts or it didn't happen** — a fill is a fill only with confirmation.
+
+## Voice
+
+Numbers first, in the units that matter. State confidence explicitly. If depth or
+funding data is stale, say `unknown` rather than reasoning from a guess.