@oracle-agent/oracle 0.3.3 → 0.3.5

package/src/data/providers/opensea-nft.mjs

@@ -1,49 +1,11 @@
 // OpenSea NFT floors — uses OPENSEA_API_KEY from env or ~/.config/locals-only/opensea.env
 
 import { readFileSync, existsSync } from "node:fs";
-import { getAddress } from "ethers";
 import { httpJson } from "../http.mjs";
 import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
-import { stampPrepared } from "../../prepare-envelope.mjs";
 
 export const OPENSEA_API = "https://api.opensea.io/api/v2";
 
-export const OPENSEA_ACCOUNT_CHAINS = Object.freeze([
-  "blast",
-  "base",
-  "ethereum",
-  "zora",
-  "arbitrum",
-  "sei",
-  "avalanche",
-  "polygon",
-  "optimism",
-  "ape_chain",
-  "flow",
-  "b3",
-  "soneium",
-  "ronin",
-  "bera_chain",
-  "solana",
-  "shape",
-  "unichain",
-  "gunzilla",
-  "abstract",
-  "animechain",
-  "hyperevm",
-  "somnia",
-  "monad",
-  "hyperliquid",
-  "megaeth",
-  "ink",
-  "robinhood",
-  "stablechain",
-]);
-
-const OPENSEA_CHAIN_SET = new Set(OPENSEA_ACCOUNT_CHAINS);
-const OPENSEA_NON_EVM_CHAINS = new Set(["solana", "flow"]);
-const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
-
 function loadKeyFromDisk() {
   const p = process.env.OPENSEA_ENV_FILE || `${process.env.HOME || ""}/.config/locals-only/opensea.env`;
   if (!existsSync(p)) return "";
@@ -80,81 +42,6 @@ function headers(opts = {}) {
   return credentialedHeaders({ accept: "application/json" }, { "x-api-key": apiKey(opts) }, endpoint(opts).trusted);
 }
 
-function accountChain(value) {
-  const chain = String(value || "ethereum").trim().toLowerCase();
-  if (!OPENSEA_CHAIN_SET.has(chain)) throw new Error(`opensea: unsupported account chain ${chain}`);
-  return chain;
-}
-
-function evmAddress(value, label = "address") {
-  try {
-    return getAddress(String(value || "").trim().toLowerCase());
-  } catch {
-    throw new Error(`opensea: invalid ${label}`);
-  }
-}
-
-function accountAddress(value, chain = null) {
-  const address = String(value || "").trim();
-  if (!address) throw new Error("opensea: account address required");
-  if (chain && !OPENSEA_NON_EVM_CHAINS.has(chain)) return evmAddress(address, "account address");
-  if (!chain && /^0x[0-9a-fA-F]{40}$/.test(address)) return evmAddress(address, "account address");
-  if (!/^[1-9A-HJ-NP-Za-km-z]{32,64}$/.test(address)) throw new Error("opensea: invalid account address");
-  return address;
-}
-
-function positiveDecimal(value, label) {
-  const text = String(value ?? "").trim();
-  if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(text) || Number(text) <= 0) {
-    throw new Error(`opensea: ${label} must be a positive plain decimal`);
-  }
-  return text;
-}
-
-function positiveInteger(value, label) {
-  const n = Number(value);
-  if (!Number.isSafeInteger(n) || n <= 0) throw new Error(`opensea: ${label} must be a positive integer`);
-  return n;
-}
-
-function isoTime(value, label) {
-  const text = String(value || "").trim();
-  const ms = Date.parse(text);
-  if (!text || !Number.isFinite(ms)) throw new Error(`opensea: ${label} must be an ISO 8601 timestamp`);
-  return { text: new Date(ms).toISOString(), ms };
-}
-
-function normalizeAccountNft(raw = {}, chain, owner) {
-  return {
-    chain,
-    owner,
-    contract: raw.contract || null,
-    tokenId: raw.identifier == null ? null : String(raw.identifier),
-    tokenStandard: raw.token_standard || null,
-    collection: raw.collection || null,
-    name: raw.name || null,
-    description: raw.description || null,
-    imageUrl: raw.display_image_url || raw.image_url || raw.original_image_url || null,
-    originalImageUrl: raw.original_image_url || raw.image_url || null,
-    animationUrl: raw.display_animation_url || raw.original_animation_url || null,
-    metadataUrl: raw.metadata_url || null,
-    marketplaceUrl: raw.opensea_url || null,
-    estimatedValueUsd: raw.estimated_value_usd != null && Number.isFinite(Number(raw.estimated_value_usd))
-      ? Number(raw.estimated_value_usd)
-      : null,
-    spam: raw.is_disabled === true || raw.is_nsfw === true,
-    disabled: raw.is_disabled === true,
-    nsfw: raw.is_nsfw === true,
-    traits: Array.isArray(raw.traits) ? raw.traits : [],
-    updatedAt: raw.updated_at || null,
-    acquisitionCost: null,
-    itemPnl: {
-      status: "unavailable",
-      reason: "OpenSea account inventory does not expose trustworthy per-item acquisition cost",
-    },
-  };
-}
-
 /** Shared request context for the multichain scanner. */
 export function openseaContext(opts = {}) {
   return {
@@ -210,162 +97,3 @@ export async function openseaFloor(slug, opts = {}) {
     },
   };
 }
-
-/** Paginated account NFT inventory for one OpenSea-supported chain. */
-export async function openseaAccountNfts(args = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("OPENSEA_API_KEY required");
-  const chain = accountChain(args.chain);
-  const owner = accountAddress(args.address || args.owner, chain);
-  const pageSize = Math.min(Math.max(Number(args.pageSize ?? args.limit ?? 200) || 200, 1), 200);
-  const maxPages = Math.min(Math.max(Number(args.maxPages ?? 5) || 5, 1), 25);
-  const nfts = [];
-  let next = args.next ? String(args.next) : null;
-  let pages = 0;
-
-  do {
-    const url = new URL(`${base(opts)}/chain/${encodeURIComponent(chain)}/account/${encodeURIComponent(owner)}/nfts`);
-    url.searchParams.set("limit", String(pageSize));
-    if (args.collection) url.searchParams.set("collection", String(args.collection));
-    if (next) url.searchParams.set("next", next);
-    const raw = await httpJson(url.toString(), {
-      headers: headers(opts),
-      fetchImpl: opts.fetchImpl,
-      timeoutMs: opts.timeoutMs ?? 20_000,
-    });
-    for (const item of Array.isArray(raw?.nfts) ? raw.nfts : []) {
-      nfts.push(normalizeAccountNft(item, chain, owner));
-    }
-    next = raw?.next ? String(raw.next) : null;
-    pages += 1;
-  } while (next && pages < maxPages);
-
-  return {
-    provider: "opensea-nft",
-    source: "opensea-account-inventory",
-    chain,
-    owner,
-    count: nfts.length,
-    pages,
-    complete: !next,
-    next,
-    nfts,
-    exec: false,
-    readOnly: true,
-  };
-}
-
-/** OpenSea-indexed account PnL. This is account-level, not per-NFT cost basis. */
-export async function openseaAccountPnl(args = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("OPENSEA_API_KEY required");
-  const address = accountAddress(args.address || args.owner);
-  const raw = await httpJson(`${base(opts)}/account/${encodeURIComponent(address)}/pnl`, {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 20_000,
-  });
-  return {
-    provider: "opensea-nft",
-    source: "opensea-indexed-account-pnl",
-    address,
-    scope: "OpenSea-indexed account trading PnL across supported currencies, not per-item NFT cost basis",
-    methodology: "provider-indexed",
-    realizedPnlUsd: raw?.realized_pnl_usd ?? null,
-    unrealizedPnlUsd: raw?.unrealized_pnl_usd ?? null,
-    totalPnlUsd: raw?.total_pnl_usd ?? null,
-    netInvestedUsd: raw?.net_invested_usd ?? null,
-    currentValueUsd: raw?.current_value_usd ?? null,
-    returnPercentage: raw?.return_percentage ?? null,
-    itemLevelPnlAvailable: false,
-    raw,
-    exec: false,
-    readOnly: true,
-  };
-}
-
-function normalizeListingItem(raw = {}) {
-  const chain = accountChain(raw.chain);
-  if (OPENSEA_NON_EVM_CHAINS.has(chain)) {
-    throw new Error("opensea: listing actions currently require an EVM NFT chain");
-  }
-  const start = raw.startTime || raw.start_time
-    ? isoTime(raw.startTime || raw.start_time, "startTime")
-    : { text: new Date().toISOString(), ms: Date.now() };
-  const end = isoTime(raw.endTime || raw.end_time, "endTime");
-  if (end.ms <= start.ms) throw new Error("opensea: endTime must be after startTime");
-  const tokenId = String(raw.tokenId ?? raw.token_id ?? "").trim();
-  if (!/^\d+$/.test(tokenId)) throw new Error("opensea: tokenId must be an unsigned integer string");
-  return {
-    chain,
-    contract: evmAddress(raw.contract, "NFT contract"),
-    token_id: tokenId,
-    quantity: positiveInteger(raw.quantity ?? 1, "quantity"),
-    price: {
-      amount: positiveDecimal(raw.price?.amount ?? raw.amount ?? raw.priceAmount, "price amount"),
-      currency: evmAddress(raw.price?.currency ?? raw.currency ?? ZERO_ADDRESS, "price currency"),
-    },
-    start_time: start.text,
-    end_time: end.text,
-  };
-}
-
-function containsApprovalStep(steps = []) {
-  return steps.some((step) => /approv|setapprovalforall/i.test(JSON.stringify(step)));
-}
-
-/**
- * Ask OpenSea for approval and Seaport signing actions. Nothing is signed,
- * submitted, or broadcast. The user's wallet handles every returned action.
- */
-export async function openseaPrepareList(args = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("OPENSEA_API_KEY required");
-  if (args.userConfirmed !== true) {
-    throw new Error("opensea: userConfirmed=true required after NFT, marketplace, price, currency, and expiry review");
-  }
-  const seller = evmAddress(args.seller || args.address || args.owner, "seller");
-  const sourceItems = Array.isArray(args.items) && args.items.length ? args.items : [args];
-  if (sourceItems.length > 50) throw new Error("opensea: at most 50 listing items per preparation");
-  const items = sourceItems.map(normalizeListingItem);
-  const chains = new Set(items.map((item) => item.chain));
-  if (chains.size !== 1) throw new Error("opensea: all prepared listing items must be on one chain");
-  const useCreatorFee = args.useCreatorFee !== false;
-  const request = {
-    address: seller,
-    items,
-    use_creator_fee: useCreatorFee,
-  };
-  if (args.taker) request.taker = evmAddress(args.taker, "taker");
-
-  const raw = await httpJson(`${base(opts)}/listings/actions`, {
-    method: "POST",
-    headers: headers(opts),
-    body: request,
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 25_000,
-    retries: 0,
-    dedupe: false,
-  });
-  const steps = Array.isArray(raw?.steps) ? raw.steps : [];
-  if (!steps.length) throw new Error("opensea: listing action response contained no wallet steps");
-
-  return stampPrepared({
-    provider: "opensea-nft",
-    marketplace: "opensea",
-    chain: items[0].chain,
-    kind: "nft-list-actions",
-    prepareReady: true,
-    executionReady: false,
-    signingReady: false,
-    broadcastReady: false,
-    requiresUserSignature: true,
-    requiresSeparateApproval: containsApprovalStep(steps),
-    seller,
-    items,
-    useCreatorFee,
-    taker: request.taker || null,
-    feeDisclosure: useCreatorFee
-      ? "Creator fees requested. Inspect the returned Seaport consideration recipients and wallet simulation before signing."
-      : "Creator fees disabled by explicit request. Marketplace protocol fees may still apply and must be inspected before signing.",
-    steps,
-    note: "Execute approvals separately, then sign the Seaport order in the user's wallet. Oracle does not submit or broadcast the listing.",
-  });
-}

package/src/data/providers/satflow.mjs

@@ -330,7 +330,6 @@ export async function satflowPrepareList(args = {}, opts = {}) {
     kind: "list-intent",
     requiresUserSignature: true,
     marketplace: "satflow",
-    listingRequest: body,
     intent: data,
     unsignedPsbt: data?.unsignedListingPSBTBase64 || data?.unsigned_psbt || null,
     note: "Sign listing PSBTs in a Bitcoin wallet; listing broadcast is outside the data plane.",

package/src/data/providers/uniswap-v3.mjs

@@ -29,6 +29,22 @@ export const UNI_V3_CHAINS = {
     weth: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
     usdc: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
   },
+  // Robinhood Chain. Addresses mirror rhbot server/swap.js SWAP_CONFIG (the vetted
+  // source) and were re-proved on the live chain before being added here:
+  // eth_chainId == 4663, eth_getCode non-empty for every address below, and a real
+  // quoteExactInputSingle returned 1 WETH -> 1866.58 USDG at fee 100 (2026-07-31).
+  //
+  // Why this entry matters: LI.FI / ParaSwap / CoW do not index 4663, so the router's
+  // aggregator-only candidate list returned "no usable route" for every RH swap. The
+  // on-chain QuoterV2 is the only source that can price this chain. `usdc` is USDG
+  // (Global Dollar, 6-dec) — the stable quote RH pools actually use.
+  4663: {
+    name: "robinhood",
+    quoter: "0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7",
+    router: "0xcaf681a66d020601342297493863e78c959e5cb2",
+    weth: "0x0bd7d308f8e1639fab988df18a8011f41eacad73",
+    usdc: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+  },
 };
 
 export const UNI_V3_FEE_TIERS = [100, 500, 3000, 10000];
@@ -274,7 +290,7 @@ export async function uniV3PrepareExactIn(q = {}, opts = {}) {
       value: nativeInput ? quote.amountIn : "0",
       slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: meta.router, data }),
     },
-  });
+  }, { provider: "uniswap-v3", kind: "univ3-swap-tx" });
 }
 
 export async function uniV3Health(opts = {}) {

package/src/exec-policy.mjs

@@ -294,11 +294,6 @@ function assertLedgerDurable(phase) {
  * @param {"sign"|"broadcast"} phase
  */
 export function enforceTxPolicy(tx = {}, phase = "broadcast") {
-  const normalizedPhase = String(phase ?? "").trim().toLowerCase();
-  if (normalizedPhase !== "sign" && normalizedPhase !== "broadcast") {
-    throw new Error(`policy: unknown phase ${JSON.stringify(phase)}, expected "sign" or "broadcast"`);
-  }
-  phase = normalizedPhase;
   assertLedgerDurable(phase);
   const chainId = Number(tx.chainId);
   if (!allowedChains().has(chainId)) {

package/src/gmx-attestation.mjs

@@ -158,7 +158,6 @@ export function assertGmxOrderAttestation(attestation, tx = {}, { chainId, nowMs
 
 export function assertGmxApprovalAttestation(attestation, tx = {}, guard = {}, { chainId, nowMs = Date.now(), secret } = {}) {
   if (!attestation || attestation.mode !== "gmx-order-attestation") throw new Error("gmx order attestation required");
-  assertFreshWindow(attestation, nowMs, "gmx approval attestation");
   if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("gmx attestation expired");
   assertSignature(attestation, secret);
   const txChainId = Number(tx.chainId ?? chainId);

package/src/router/prepare-route.mjs

@@ -45,6 +45,29 @@ export const ARTIFACT = Object.freeze({
 const DEFAULT_DRIFT_TOLERANCE_BPS = 100;
 
 const PREPARERS = {
+  // On-chain Uniswap V3. Unlike the aggregators below, this builds calldata from the
+  // chain's own router rather than an API's transaction payload — which is what makes
+  // chains no aggregator indexes (e.g. Robinhood 4663) preparable at all.
+  //
+  // The provider stamps requiresUserSignature:true / signingReady:false /
+  // broadcastReady:false. Preparing is NOT permission to execute: the wallet is still
+  // the only thing that can authorize this, and the unattended daemon surface list
+  // (hl, poly) is deliberately unchanged by adding this.
+  "uniswap-v3": async ({ chainId, tokenIn, tokenOut, amountIn, taker }, opts) => {
+    const { uniV3PrepareExactIn } = await import("../data/providers/uniswap-v3.mjs");
+    const p = await uniV3PrepareExactIn(
+      { chainId, tokenIn, tokenOut, amountIn, recipient: taker },
+      opts,
+    );
+    return {
+      artifactKind: ARTIFACT.TRANSACTION,
+      transaction: p.transaction,
+      requiresApproval: p.requiresApproval ?? null,
+      amountOut: p.quote?.amountOut ?? null,
+      minOut: p.quote?.amountOutMinimum ?? null,
+    };
+  },
+
   lifi: async ({ chainId, tokenIn, tokenOut, amountIn, taker }, opts) => {
     const { lifiPrepare } = await import("../data/providers/lifi.mjs");
     const p = await lifiPrepare(

package/src/router/route-sources.mjs

@@ -20,6 +20,7 @@ import { paraswapPrice } from "../data/providers/paraswap.mjs";
 import { zeroxQuote } from "../data/providers/zerox.mjs";
 import { oneinchQuote } from "../data/providers/oneinch.mjs";
 import { cowQuote } from "../data/providers/cowswap.mjs";
+import { uniV3QuoteExactIn, UNI_V3_CHAINS } from "../data/providers/uniswap-v3.mjs";
 import { llamaPrices } from "../data/providers/defillama.mjs";
 import { NATIVE_PRICE_KEY } from "./best-execution.mjs";
 
@@ -188,6 +189,42 @@ export function swapCandidates({
     },
   });
 
+  // On-chain Uniswap V3 QuoterV2. UNLIKE every other source in this list, this is
+  // not a third-party API — it is an eth_call against the chain itself.
+  //
+  // Why it exists here: aggregators only index chains they chose to support. On
+  // Robinhood Chain (4663) LI.FI/ParaSwap/CoW all return nothing, so the candidate
+  // list came back empty and the router reported "no usable route" — which reads
+  // like a permission wall but is really zero coverage. A chain with a live V3
+  // deployment can always be priced directly, with no API key and no indexer.
+  //
+  // Kept LAST so it acts as a floor: when aggregators do cover a chain they usually
+  // win on route quality, and best-execution still compares net output. This only
+  // decides the trade when it is the sole source that answered.
+  //
+  // Read-only. quoteExactInputSingle is a view call; this cannot sign or broadcast.
+  if (UNI_V3_CHAINS[Number(chainId)]) {
+    c.push({
+      source: "uniswap-v3",
+      run: async () => {
+        const q = await uniV3QuoteExactIn(
+          { chainId, tokenIn, tokenOut, amountIn },
+          opts,
+        );
+        // Gas is deliberately null, not 0: the quoter returns a gasEstimate in UNITS,
+        // and without a gas price that is not a USD cost. Reporting 0 would make this
+        // source look free and beat correctly-priced aggregators. See CoW above for
+        // the one case where 0 is a measured fact rather than a missing number.
+        return {
+          amountOut: q?.amountOut,
+          minOut: q?.minOut ?? q?.amountOutMinimum ?? null,
+          gasUsd: null,
+          meta: { onchain: true, fee: q?.fee, gasUnits: q?.gasEstimate, quoter: q?.quoter },
+        };
+      },
+    });
+  }
+
   return c;
 }
 

package/src/scanner/chains.config.mjs

@@ -215,7 +215,54 @@ export const CHAIN_CONFIGS = Object.freeze([
     name: "Robinhood Chain",
     rpcEnv: ["RH_CHAIN_RPC", "ROBINHOOD_RPC_URL"],
     nativeCurrency: { symbol: "ETH", decimals: 18 },
-    venues: [],
+    // DexScreener does index this chain under the slug "robinhood" (verified live
+    // 2026-07-31: a CASHCAT search returns pairs tagged chainId "robinhood"). Without
+    // the slug, resolvePools reported UNAVAILABLE on every RH token even though the
+    // data was there.
+    dexscreenerSlug: "robinhood",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7",
+        label: "Uniswap V3 QuoterV2",
+        verified: {
+          method:
+            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
+            "live sane price (WETH->USDG fee 100 quoted 1866.58 USDG, and USDG->CASHCAT " +
+            "fee 10000 quoted a live amount). A contract that correctly prices known pairs " +
+            "IS a working V3 quoter",
+          source: "live eth_call against rpc.mainnet.chain.robinhood.com",
+          date: "2026-07-31",
+          chainId: 4663,
+        },
+      },
+      {
+        kind: "router",
+        address: "0xcaf681a66d020601342297493863e78c959e5cb2",
+        label: "Uniswap V3 SwapRouter02",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode (24497 bytes) on this chain and the paired " +
+            "quoter at the same deployment passed a live functional quote",
+          source: "live eth_getCode against rpc.mainnet.chain.robinhood.com",
+          date: "2026-07-31",
+          chainId: 4663,
+        },
+      },
+      {
+        kind: "factory",
+        address: "0x1f7d7550b1b028f7571e69a784071f0205fd2efa",
+        label: "Uniswap V3 Factory",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode (24535 bytes) and a PoolCreated log scan " +
+            "over this factory returned 76 pools in ~9000 recent blocks",
+          source: "live eth_getLogs against rpc.mainnet.chain.robinhood.com",
+          date: "2026-07-31",
+          chainId: 4663,
+        },
+      },
+    ],
   },
   {
     key: "base",

package/src/vault-attestation.mjs

@@ -129,7 +129,6 @@ export function assertVaultAttestation(attestation, tx = {}, { chainId, nowMs =
 export function assertVaultApprovalAttestation(attestation, tx = {}, guard = {}, { chainId, nowMs = Date.now(), secret } = {}) {
   if (!attestation || attestation.mode !== "vault-attestation") throw new Error("vault attestation required");
   if (String(attestation.action) !== "deposit") throw new Error("vault approval requires deposit attestation");
-  assertFreshWindow(attestation, nowMs, "vault approval attestation");
   if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("vault attestation expired");
   const expected = hmac(attestationSecret(secret), canonicalJson(unsigned(attestation)));
   if (!sameSignature(attestation.signature, expected)) throw new Error("vault attestation signature mismatch");

package/skills/balance/SKILL.md

@@ -1,176 +0,0 @@
----
-name: balance
-description: Use when the user says balance, holdings, portfolio, wallet balance, or invokes /balance. Call the deterministic read-only multichain portfolio tool and report coverage honestly.
----
-
-# Balance
-
-Use `portfolio_snapshot` for every fresh balance request. It runs the deterministic
-multichain balance and NFT inventory reads once, then records one compact local
-observation so the user can build history without a separate tracker.
-
-Use `portfolio_history` for balance-history requests and `portfolio_value_graph`
-for charts. Use `portfolio_balance` only when the user explicitly asks for a
-non-recorded read or when local history storage is unavailable.
-
-This skill is read-only. Public addresses are identifiers, not signing rights.
-Never request a private key, seed phrase, wallet export, session key, or signature.
-
-## Trigger
-
-Run this workflow when the user:
-
-- invokes `/balance`;
-- says `balance` by itself;
-- asks for holdings, wallet balance, portfolio, net assets, or assets across chains;
-- supplies one or more public wallet addresses and asks what they hold.
-
-## Address routing
-
-Parse only public addresses supplied with the request:
-
-- `0x...` maps to `addresses.evm` and `addresses.hyperliquid` unless the user
-  explicitly assigns different addresses;
-- a Solana base58 public key maps to `addresses.solana`;
-- a Bitcoin `bc1`, `1`, or `3` address maps to `addresses.bitcoin`;
-- explicit labels such as `evm:`, `solana:`, `bitcoin:`, and `hyperliquid:` win.
-
-If no addresses are in the request, call `portfolio_snapshot` with an empty object.
-The tool uses configured public-address defaults:
-
-- `ORACLE_EVM_ADDRESS`, with legacy fallback `ORACLE_DEFAULT_ADDRESS`;
-- `ORACLE_SOLANA_ADDRESS`;
-- `ORACLE_BITCOIN_ADDRESS`;
-- `ORACLE_HYPERLIQUID_ADDRESS`, with EVM fallback.
-
-If every family returns `not-configured`, ask only for the missing public addresses.
-Do not call a zero address a user wallet and do not report missing families as zero.
-
-## Mandatory call
-
-Call `portfolio_snapshot`:
-
-```json
-{
-  "addresses": {
-    "evm": "optional public address",
-    "solana": "optional public key",
-    "bitcoin": "optional public address",
-    "hyperliquid": "optional public address"
-  },
-  "includeTokens": true,
-  "includeCollectibles": true,
-  "includePrices": true,
-  "includeNfts": true
-}
-```
-
-Omit address fields the user did not supply. Omit `evmChainIds` unless the user
-asks for a subset. The default queries every configured EVM chain. Read fungible
-and chain details from `result.balance`, NFT holdings from `result.nfts`, and the
-combined historical observation from `result.snapshot`.
-
-Never call a chain write, prepare, sign, send, submit, execute, or broadcast tool
-while answering a balance request. The compact profile-local history append made
-by `portfolio_snapshot` is allowed and contains no keys or executable payloads.
-
-## Coverage contract
-
-The current aggregator covers:
-
-- native balances on every configured EVM chain;
-- Solana SOL plus SPL Token and Token-2022 accounts;
-- Bitcoin BTC plus Runes and inscriptions when an address indexer is configured;
-- Hyperliquid HyperCore spot balances and perp account state;
-- OpenSea-supported EVM/Solana NFT inventory and Bitcoin inscriptions where the
-  configured providers expose owner data;
-- profile-local snapshots and an SVG known-value history graph.
-
-It must explicitly report unsupported or unavailable surfaces:
-
-- EVM token and NFT enumeration is unavailable without an address indexer;
-- Solana token accounts are unverified until metadata confirms symbol and spam
-  status;
-- a Solana amount of one with zero decimals is only a collectible candidate;
-- Bitcoin Runes and inscriptions require an address-indexed provider;
-- Cosmos requires a chain-specific bech32 address and LCD/RPC adapter;
-- Sui and Aptos remain unsupported until their balance adapters are installed;
-- any provider failure is `unavailable`, never a zero balance;
-- NFT prices are provider estimates, not executable bids.
-
-## History and graph
-
-For “balance history”, “portfolio history”, or a date range, call
-`portfolio_history` with the same public addresses and the requested `since`,
-`until`, and `limit`. Keep `null` values unavailable. Do not interpolate them.
-
-For “graph”, “chart”, or “show me performance”, call `portfolio_value_graph`.
-State the returned `summary.changeUsd`, `summary.changePct`, point count, and
-whether any plotted snapshots were incomplete. The image plots known priced
-value, not guaranteed liquidation value or net worth.
-
-## Response format
-
-Start with:
-
-```text
-Balance, <queriedAt>
-Known priced value: $<knownUsd>  (not a complete total)
-Coverage: <ok>/<requestedSurfaces> surfaces live
-```
-
-If `valuation.complete` is true, you may remove the parenthetical. Do not rename
-`knownUsd` to `total`, `net worth`, or `portfolio value` when coverage is partial.
-
-Then show nonzero assets first, grouped by family:
-
-```text
-EVM
-Ethereum: 0.42 ETH  $...
-Base: 18.1 ETH  $...
-
-Solana
-SOL: ...
-SPL: <mint>  <amount>  unverified
-
-Bitcoin
-BTC: ...
-Runes: ...
-Inscriptions: ...
-
-Hyperliquid
-Spot: ...
-Perps account value: $...
-Positions: ...
-```
-
-Collapse successful zero-native EVM chains into one line:
-
-```text
-Zero native: Polygon, Optimism, Arbitrum
-```
-
-End with concise exceptions:
-
-```text
-Unavailable: <failed providers or unconfigured addresses>
-Unpriced: <nonzero assets without a price>
-Warnings: <spam, stale, unknown-not-empty, or incomplete discovery warnings>
-```
-
-Do not dump raw RPC payloads unless the user asks. Keep exact public addresses in
-the response only when the user supplied multiple addresses and disambiguation is
-necessary.
-
-## Truth rules
-
-- `0` means a provider successfully returned zero.
-- `unavailable` means the provider failed or the adapter is absent.
-- `not-configured` means the public address is missing.
-- `unknownNotEmpty` means the provider cannot tell whether assets exist. Never
-  convert it to an empty portfolio.
-- Every USD figure must carry a price source and query timestamp in the tool
-  result.
-- Do not sum Stable Mainnet native USDT0 with its mirrored ERC-20 representation.
-- Do not price unverified or spam tokens by symbol alone.
-- Do not hide failed chains to make the summary look complete.