@oracle-agent/oracle 0.1.0

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

@@ -0,0 +1,99 @@
+// OpenSea NFT floors — uses OPENSEA_API_KEY from env or ~/.config/locals-only/opensea.env
+
+import { readFileSync, existsSync } from "node:fs";
+import { httpJson } from "../http.mjs";
+import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
+
+export const OPENSEA_API = "https://api.opensea.io/api/v2";
+
+function loadKeyFromDisk() {
+  const p = process.env.OPENSEA_ENV_FILE || `${process.env.HOME || ""}/.config/locals-only/opensea.env`;
+  if (!existsSync(p)) return "";
+  try {
+    for (const ln of readFileSync(p, "utf8").split("\n")) {
+      const m = ln.match(/^\s*OPENSEA_API_KEY\s*=\s*(.+)\s*$/);
+      if (m) return m[1].replace(/^["']|["']$/g, "").trim();
+    }
+  } catch {
+    /* ignore */
+  }
+  return "";
+}
+
+function apiKey(opts = {}) {
+  return opts.apiKey || process.env.OPENSEA_API_KEY || process.env.OPEN_SEA_API_KEY || loadKeyFromDisk();
+}
+
+function endpoint(opts = {}) {
+  return resolveProviderEndpoint({
+    provider: "opensea",
+    defaultUrl: OPENSEA_API,
+    hosts: ["api.opensea.io", "testnets-api.opensea.io"],
+    url: opts.baseUrl || process.env.OPENSEA_API_URL,
+  });
+}
+
+function base(opts = {}) {
+  return endpoint(opts).baseUrl;
+}
+
+function headers(opts = {}) {
+  // x-api-key is attached only for a pinned OpenSea host.
+  return credentialedHeaders({ accept: "application/json" }, { "x-api-key": apiKey(opts) }, endpoint(opts).trusted);
+}
+
+/** Shared request context for the multichain scanner. */
+export function openseaContext(opts = {}) {
+  return {
+    base: base(opts),
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  };
+}
+
+export async function openseaHealth(opts = {}) {
+  if (!apiKey(opts)) {
+    return { ok: false, configured: false, error: "OPENSEA_API_KEY not set" };
+  }
+  try {
+    const c = await openseaCollection("boredapeyachtclub", opts);
+    return { ok: true, configured: true, name: c.name || c.collection };
+  } catch (e) {
+    return { ok: false, configured: true, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+export async function openseaCollection(slug, opts = {}) {
+  if (!slug) throw new Error("collection slug required");
+  if (!apiKey(opts)) throw new Error("OPENSEA_API_KEY required");
+  return httpJson(`${base(opts)}/collections/${encodeURIComponent(slug)}`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}
+
+/** Best-effort floor from collection stats / collection payload. */
+export async function openseaFloor(slug, opts = {}) {
+  const c = await openseaCollection(slug, opts);
+  const stats = c.stats || c.total || {};
+  const floor =
+    c.floor_price ??
+    c.floorPrice ??
+    stats.floor_price ??
+    stats.floorPrice ??
+    null;
+  return {
+    slug: c.collection || slug,
+    name: c.name || null,
+    floor,
+    totalSupply: c.total_supply ?? stats.total_supply ?? null,
+    numOwners: c.num_owners ?? stats.num_owners ?? null,
+    raw: {
+      contracts: c.contracts,
+      fees: c.fees,
+      category: c.category,
+    },
+  };
+}

package/src/data/providers/paraswap.mjs

@@ -0,0 +1,117 @@
+// ParaSwap/Velora public market API — keyless price routes, quote-only here.
+import { httpJson } from "../http.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall } from "../../auto-slippage.mjs";
+
+export const PARASWAP_API = "https://api.paraswap.io";
+const base = (o = {}) => (o.baseUrl || process.env.PARASWAP_API_URL || PARASWAP_API).replace(/\/$/, "");
+function token(value, name) {
+  const s = String(value || "");
+  if (!/^0x[0-9a-fA-F]{40}$/.test(s)) throw new Error(`${name} must be a 20-byte token address`);
+  return s.toLowerCase();
+}
+
+export async function paraswapTokens(args = {}, opts = {}) {
+  const chainId = Number(args.chainId || 1);
+  return httpJson(`${base(opts)}/tokens/${chainId}`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs });
+}
+
+export async function paraswapPrice(args = {}, opts = {}) {
+  const chainId = Number(args.chainId || args.network || 1);
+  if (args.amount == null) throw new Error("amount required");
+  const params = new URLSearchParams({
+    srcToken: token(args.srcToken, "srcToken"),
+    destToken: token(args.destToken, "destToken"),
+    amount: String(args.amount),
+    srcDecimals: String(Number(args.srcDecimals)),
+    destDecimals: String(Number(args.destDecimals)),
+    side: String(args.side || "SELL").toUpperCase(),
+    network: String(chainId),
+    version: String(args.version || "6.2"),
+  });
+  if (args.includeDEXS) params.set("includeDEXS", String(args.includeDEXS));
+  if (args.excludeDEXS) params.set("excludeDEXS", String(args.excludeDEXS));
+  const result = await httpJson(`${base(opts)}/prices?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  const amountOut = result?.priceRoute?.destAmount;
+  if (!amountOut) return { ...result, executionReady: false };
+  return {
+    ...attachAutoSlippage(result, {
+      chainId,
+      venue: result?.priceRoute?.contractAddress || "paraswap-quote",
+      amountOut,
+      liquidityUsd: args.liquidityUsd,
+      priceChange5m: args.priceChange5m,
+      quoteAgeMs: 0,
+      requestedCapBps: args.maxSlippageBps ?? args.slippageBps,
+    }),
+    executionReady: false,
+    executionBlocker: "call prepare to bind the price route to a validated transaction",
+  };
+}
+
+export async function paraswapPrepare(args = {}, opts = {}) {
+  if (String(args.side || "SELL").toUpperCase() !== "SELL") {
+    throw new Error("paraswap: agentic prepare currently supports exact-input SELL only");
+  }
+  const chainId = Number(args.chainId || args.network || 1);
+  const userAddress = token(args.userAddress, "userAddress");
+  const quote = await paraswapPrice(args, opts);
+  const priceRoute = quote?.priceRoute;
+  const expectedTarget = String(priceRoute?.contractAddress || "").toLowerCase();
+  if (!expectedTarget) throw new Error("paraswap: price route missing contractAddress");
+  const body = {
+    srcToken: token(args.srcToken, "srcToken"),
+    destToken: token(args.destToken, "destToken"),
+    srcAmount: String(priceRoute.srcAmount || args.amount),
+    // ParaSwap treats destAmount as the on-chain minimum for SELL routes.
+    destAmount: String(quote.amountOutMinimum),
+    priceRoute,
+    userAddress,
+    ignoreChecks: false,
+    ignoreGasEstimate: false,
+  };
+  if (args.receiver) body.receiver = token(args.receiver, "receiver");
+  const tx = await httpJson(`${base(opts)}/transactions/${chainId}`, {
+    method: "POST",
+    body,
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 25_000,
+  });
+  if (Number(tx.chainId ?? chainId) !== chainId) throw new Error("paraswap: transaction chain mismatch");
+  if (String(tx.to || "").toLowerCase() !== expectedTarget) throw new Error("paraswap: transaction target mismatch");
+  if (tx.from && String(tx.from).toLowerCase() !== userAddress) throw new Error("paraswap: transaction sender mismatch");
+  return {
+    provider: "paraswap",
+    calldataReady: true,
+    // NOT executable authority. The bytes are assembled but nothing is signed:
+    // the user's wallet is still the only thing that can authorize this. The
+    // previous `executionReady: true` read as "cleared to execute" and trained
+    // agents to treat a quote as permission.
+    requiresUserSignature: true,
+    signingReady: false,
+    broadcastReady: false,
+    chainId,
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval: body.srcToken !== "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
+      ? { token: body.srcToken, spender: priceRoute.tokenTransferProxy || expectedTarget, amount: body.srcAmount }
+      : null,
+    transaction: {
+      chainId,
+      from: tx.from || userAddress,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value ?? "0x0",
+      ...(tx.gas != null ? { gasLimit: tx.gas } : {}),
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
+    },
+  };
+}
+
+export async function paraswapHealth(opts = {}) {
+  const data = await paraswapTokens({ chainId: 1 }, opts);
+  const count = Array.isArray(data?.tokens) ? data.tokens.length : Object.keys(data?.tokens || {}).length;
+  return { ok: count > 0, tokenSample: count };
+}

package/src/data/providers/pendle.mjs

@@ -0,0 +1,187 @@
+// Pendle public core API — markets and Hosted SDK Convert tx builder, no key.
+import { getAddress } from "ethers";
+import { httpJson } from "../http.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
+
+export const PENDLE_API = "https://api-v2.pendle.finance/core";
+
+// Official Pendle Router from deployment docs. Bytecode checked via eth_getCode
+// on Arbitrum/Base 2026-07-23.
+export const PENDLE_ROUTER_BY_CHAIN = Object.freeze({
+  42161: "0x888888888889758F76e7103c6CbF23ABbF58F946",
+  8453: "0x888888888889758F76e7103c6CbF23ABbF58F946",
+});
+
+const ZERO = "0x0000000000000000000000000000000000000000";
+const NATIVE = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+
+const base = (o = {}) => (o.baseUrl || process.env.PENDLE_API_URL || PENDLE_API).replace(/\/$/, "");
+
+function checksum(value, label) {
+  try {
+    return getAddress(value);
+  } catch {
+    throw new Error(`${label} must be a valid EVM address`);
+  }
+}
+
+function normal(value, label) {
+  return checksum(value, label).toLowerCase();
+}
+
+function isNative(value) {
+  const v = String(value || "").toLowerCase();
+  return v === "native" || v === "eth" || v === NATIVE || v === ZERO;
+}
+
+function amountString(value, label) {
+  let amount;
+  try {
+    amount = BigInt(String(value));
+  } catch {
+    throw new Error(`${label} must be an integer string`);
+  }
+  if (amount <= 0n) throw new Error(`${label} must be positive`);
+  return amount.toString();
+}
+
+function normalizeInputs(inputs) {
+  if (!Array.isArray(inputs) || inputs.length === 0) throw new Error("pendle convert requires inputs[]");
+  return inputs.map((input, i) => ({
+    token: checksum(input.token, `pendle input ${i} token`),
+    amount: amountString(input.amount, `pendle input ${i} amount`),
+  }));
+}
+
+function normalizeOutputs(outputs) {
+  if (!Array.isArray(outputs) || outputs.length === 0) throw new Error("pendle convert requires outputs[]");
+  return outputs.map((token, i) => checksum(token, `pendle output ${i} token`));
+}
+
+function routerFor(chainId) {
+  const router = PENDLE_ROUTER_BY_CHAIN[Number(chainId)];
+  if (!router) throw new Error(`Pendle prepare not enabled for chainId ${chainId}`);
+  return router;
+}
+
+function firstOutputAmount(result) {
+  const amount = result?.routes?.[0]?.outputs?.[0]?.amount || result?.outputs?.[0]?.amount;
+  if (!amount) throw new Error("Pendle convert response missing output amount");
+  return amountString(amount, "pendle output amount");
+}
+
+function normalizeRequiredApprovals(requiredApprovals, spender) {
+  const approvals = (Array.isArray(requiredApprovals) ? requiredApprovals : [])
+    .filter((approval) => approval?.token && approval?.amount && !isNative(approval.token))
+    .map((approval) => ({
+      token: normal(approval.token, "pendle approval token"),
+      spender: normal(spender, "pendle approval spender"),
+      amount: amountString(approval.amount, "pendle approval amount"),
+    }));
+  if (!approvals.length) return null;
+  return approvals.length === 1 ? approvals[0] : approvals;
+}
+
+export async function pendleMarkets(args = {}, opts = {}) {
+  const chainId = Number(args.chainId || 42161);
+  const p = new URLSearchParams({
+    limit: String(Math.min(100, Math.max(1, Number(args.limit || 20)))),
+    skip: String(Math.max(0, Number(args.skip || 0))),
+  });
+  if (args.isExpired != null) p.set("isExpired", String(Boolean(args.isExpired)));
+  return httpJson(`${base(opts)}/v1/${chainId}/markets?${p}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function pendleHealth(opts = {}) {
+  const data = await pendleMarkets({ chainId: 42161, limit: 1 }, opts);
+  return { ok: Array.isArray(data?.results), marketSample: data?.results?.length || 0 };
+}
+
+export async function pendlePrepare(q = {}, opts = {}) {
+  const chainId = Number(q.chainId ?? 42161);
+  const router = routerFor(chainId);
+  const from = q.from || q.fromAddress || q.userAddress || q.taker || q.receiver;
+  if (!from) throw new Error("pendlePrepare requires from/receiver");
+  const receiver = checksum(q.receiver || from, "pendle receiver");
+  const inputs = normalizeInputs(q.inputs);
+  const outputs = normalizeOutputs(q.outputs);
+  if (q.enableAggregator === true || (Array.isArray(q.aggregators) && q.aggregators.length)) {
+    throw new Error("Pendle aggregator paths are disabled by policy; use direct convert only");
+  }
+  const selected = resolveAutoSlippage({
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  if (!selected.executable) {
+    throw new Error(`Pendle: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
+  }
+  const body = {
+    receiver,
+    slippage: selected.selectedBps / 10_000,
+    enableAggregator: false,
+    useLimitOrder: false,
+    inputs,
+    outputs,
+    ...(q.redeemRewards != null ? { redeemRewards: Boolean(q.redeemRewards) } : {}),
+    ...(q.needScale != null ? { needScale: Boolean(q.needScale) } : {}),
+    ...(q.additionalData ? { additionalData: String(q.additionalData) } : {}),
+  };
+  const raw = await httpJson(`${base(opts)}/v3/sdk/${chainId}/convert`, {
+    method: "POST",
+    body,
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 25_000,
+  });
+  const route = raw?.routes?.[0];
+  const tx = route?.tx;
+  if (!tx?.to || !tx?.data) throw new Error("Pendle convert returned no executable tx");
+  if (normal(tx.to, "pendle tx target") !== normal(router, "pendle router")) {
+    throw new Error("Pendle convert returned unexpected router target");
+  }
+  if (tx.from && normal(tx.from, "pendle tx sender") !== normal(from, "pendle sender")) {
+    throw new Error("Pendle convert transaction sender mismatch");
+  }
+  const amountOut = firstOutputAmount(raw);
+  const quote = attachAutoSlippage(raw, {
+    chainId,
+    venue: tx.to,
+    amountOut,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  return {
+    provider: "pendle",
+    calldataReady: true,
+    // NOT executable authority. The bytes are assembled but nothing is signed:
+    // the user's wallet is still the only thing that can authorize this. The
+    // previous `executionReady: true` read as "cleared to execute" and trained
+    // agents to treat a quote as permission.
+    requiresUserSignature: true,
+    signingReady: false,
+    broadcastReady: false,
+    chainId,
+    action: raw.action || null,
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval: normalizeRequiredApprovals(raw.requiredApprovals, tx.to),
+    transaction: {
+      chainId,
+      from: tx.from || from,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value ?? "0x0",
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
+    },
+  };
+}
+
+export async function pendleQuote(q = {}, opts = {}) {
+  const prepared = await pendlePrepare(q, opts);
+  const { transaction: _transaction, ...quote } = prepared;
+  return quote;
+}

package/src/data/providers/poly-public.mjs

@@ -0,0 +1,96 @@
+// Polymarket public REST — CLOB + Gamma. No L2 API key, no wallet.
+
+import { httpJson } from "../http.mjs";
+
+export const POLY_CLOB_DEFAULT = "https://clob.polymarket.com";
+export const POLY_GAMMA_DEFAULT = "https://gamma-api.polymarket.com";
+
+function clobBase(opts = {}) {
+  return (opts.clobUrl || process.env.POLY_CLOB_URL || POLY_CLOB_DEFAULT).replace(/\/$/, "");
+}
+
+function gammaBase(opts = {}) {
+  return (opts.gammaUrl || process.env.POLY_GAMMA_URL || POLY_GAMMA_DEFAULT).replace(/\/$/, "");
+}
+
+export async function polyTime(opts = {}) {
+  return httpJson(`${clobBase(opts)}/time`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function polyHealth(opts = {}) {
+  const t = await polyTime(opts);
+  const ok = t != null && t !== "";
+  return { ok, time: t };
+}
+
+export async function polyMarkets({ limit = 5, offset = 0, ...rest } = {}, opts = {}) {
+  const q = new URLSearchParams({
+    limit: String(limit),
+    offset: String(offset),
+    ...Object.fromEntries(
+      Object.entries(rest)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => [k, String(v)])
+    ),
+  });
+  return httpJson(`${gammaBase(opts)}/markets?${q}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function polyBook(tokenId, opts = {}) {
+  if (!tokenId) throw new Error("polyBook requires tokenId");
+  const q = new URLSearchParams({ token_id: String(tokenId) });
+  return httpJson(`${clobBase(opts)}/book?${q}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function polyMidpoint(tokenId, opts = {}) {
+  if (!tokenId) throw new Error("polyMidpoint requires tokenId");
+  const q = new URLSearchParams({ token_id: String(tokenId) });
+  return httpJson(`${clobBase(opts)}/midpoint?${q}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+// D1 expansions
+export async function polySpread(tokenId, opts = {}) {
+  if (!tokenId) throw new Error("polySpread requires tokenId");
+  const q = new URLSearchParams({ token_id: String(tokenId) });
+  return httpJson(`${clobBase(opts)}/spread?${q}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function polyPrice(tokenId, { side = "buy" } = {}, opts = {}) {
+  if (!tokenId) throw new Error("polyPrice requires tokenId");
+  const q = new URLSearchParams({ token_id: String(tokenId), side: String(side) });
+  return httpJson(`${clobBase(opts)}/price?${q}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function polyEvents({ limit = 5, offset = 0, ...rest } = {}, opts = {}) {
+  const q = new URLSearchParams({
+    limit: String(limit),
+    offset: String(offset),
+    ...Object.fromEntries(
+      Object.entries(rest)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => [k, String(v)])
+    ),
+  });
+  return httpJson(`${gammaBase(opts)}/events?${q}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}

package/src/data/providers/poly-ws.mjs

@@ -0,0 +1,103 @@
+// Short-lived Polymarket CLOB WebSocket market snapshots.
+
+const POLY_WS = process.env.POLY_WS_URL || "wss://ws-subscriptions-clob.polymarket.com/ws/market";
+
+/**
+ * Subscribe to asset_ids (token ids) and return first book-like payload.
+ */
+export async function polyWsSnapshot(assetIds = [], opts = {}) {
+  const ids = Array.isArray(assetIds) ? assetIds.map(String) : [String(assetIds)];
+  if (!ids.length || !ids[0]) throw new Error("polyWsSnapshot requires assetIds");
+  const timeoutMs = opts.timeoutMs ?? 8_000;
+  const maxMessages = opts.maxMessages ?? 1;
+  const WebSocketImpl = opts.WebSocket || globalThis.WebSocket;
+  if (!WebSocketImpl) throw new Error("WebSocket not available");
+
+  const url = opts.url || POLY_WS;
+  const started = Date.now();
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const messages = [];
+    let dataCount = 0;
+    const ws = new WebSocketImpl(url);
+    const timer = setTimeout(() => {
+      cleanup();
+      if (!settled) {
+        settled = true;
+        if (messages.length) resolve({ ok: true, partial: true, ms: Date.now() - started, messages });
+        else reject(new Error(`poly ws timeout after ${timeoutMs}ms`));
+      }
+    }, timeoutMs);
+
+    function cleanup() {
+      clearTimeout(timer);
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+    }
+
+    ws.addEventListener("open", () => {
+      // CLOB market channel: assets_ids
+      ws.send(
+        JSON.stringify({
+          assets_ids: ids,
+          type: "market",
+        })
+      );
+    });
+
+    ws.addEventListener("message", (ev) => {
+      let data;
+      try {
+        data = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+      } catch {
+        data = { raw: String(ev.data).slice(0, 300) };
+      }
+      messages.push(data);
+      dataCount += 1;
+      if (dataCount >= maxMessages) {
+        cleanup();
+        if (!settled) {
+          settled = true;
+          resolve({
+            ok: true,
+            ms: Date.now() - started,
+            assetIds: ids,
+            messages,
+            last: messages[messages.length - 1],
+          });
+        }
+      }
+    });
+
+    ws.addEventListener("error", () => {
+      cleanup();
+      if (!settled) {
+        settled = true;
+        reject(new Error("poly ws error"));
+      }
+    });
+  });
+}
+
+export async function polyWsHealth(opts = {}) {
+  // Use a well-known active token if none provided — caller can pass assetId
+  const assetId =
+    opts.assetId ||
+    "98022490269692409998126496127597032490334070080325855126491859374983463996227";
+  try {
+    const snap = await polyWsSnapshot([assetId], { ...opts, maxMessages: 1 });
+    return { ok: true, ms: snap.ms, got: Boolean(snap.last), partial: snap.partial || false };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+export async function polyWsBook(assetId, opts = {}) {
+  if (!assetId) throw new Error("assetId required");
+  const snap = await polyWsSnapshot([assetId], opts);
+  return { ms: snap.ms, assetId: String(assetId), data: snap.last, messages: snap.messages };
+}

package/src/data/providers/rh-agent.mjs

@@ -0,0 +1,59 @@
+// RH agent HTTP read client — talks to the live RH product over HTTP.
+// Unauthenticated D0/D1 ops only. Does NOT import rhbot.
+
+import { httpJson } from "../http.mjs";
+
+export const RH_AGENT_DEFAULT_BASE = "http://127.0.0.1:8792";
+
+function baseUrl(opts = {}) {
+  return (
+    opts.baseUrl ||
+    process.env.RH_AGENT_BASE_URL ||
+    process.env.RH_AGENT_URL ||
+    RH_AGENT_DEFAULT_BASE
+  ).replace(/\/$/, "");
+}
+
+async function get(path, opts = {}) {
+  return httpJson(`${baseUrl(opts)}${path}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function rhHealth(opts = {}) {
+  return get("/api/health", opts);
+}
+
+export async function rhPolicy(opts = {}) {
+  return get("/api/agent/policy", opts);
+}
+
+// D1 — public RH routes (no requireUser)
+export async function rhChainConfig(opts = {}) {
+  return get("/api/chain/config", opts);
+}
+
+export async function rhChainGas(opts = {}) {
+  return get("/api/chain/gas", opts);
+}
+
+export async function rhSwapsConfig(opts = {}) {
+  return get("/api/swaps/config", opts);
+}
+
+export async function rhSwapsPresets(opts = {}) {
+  return get("/api/swaps/presets", opts);
+}
+
+export async function rhTradingStatus(opts = {}) {
+  return get("/api/trading/status", opts);
+}
+
+export async function rhNftDrops(opts = {}) {
+  return get("/api/nft-drops", opts);
+}
+
+export async function rhFeeEstimate(opts = {}) {
+  return get("/api/fee/estimate", opts);
+}