@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/data/providers/hl-assets.mjs

@@ -0,0 +1,165 @@
+// Hyperliquid asset ID resolution — main perps, HIP-3 builder dexs, HIP-4 outcomes.
+// Docs: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
+//
+// Main perps:      asset = index in meta.universe
+// HIP-3 builder:   asset = 100000 + perp_dex_index * 10000 + index_in_meta
+// HIP-4 outcomes:  encoding = 10 * outcome + side; asset = 100_000_000 + encoding
+//                  coin form: #<encoding>
+
+import { hlInfo, hlMetaAndAssetCtxs } from "./hl-info.mjs";
+
+const OUTCOME_ASSET_BASE = 100_000_000;
+const BUILDER_PERP_BASE = 100_000;
+
+let _dexCache = { at: 0, dexs: null };
+let _metaCache = new Map(); // dex -> { at, universe, ctxs }
+
+async function perpDexs(opts = {}) {
+  const now = Date.now();
+  if (_dexCache.dexs && now - _dexCache.at < 60_000 && !opts.fetchImpl) return _dexCache.dexs;
+  const dexs = await hlInfo({ type: "perpDexs" }, opts);
+  _dexCache = { at: now, dexs: Array.isArray(dexs) ? dexs : [] };
+  return _dexCache.dexs;
+}
+
+async function metaForDex(dex = "", opts = {}) {
+  const key = dex || "";
+  const now = Date.now();
+  const hit = _metaCache.get(key);
+  // skip cache when caller injects fetchImpl (unit tests / custom transport)
+  if (hit && now - hit.at < 30_000 && !opts.fetchImpl) return hit;
+  const raw = dex
+    ? await hlInfo({ type: "metaAndAssetCtxs", dex }, opts)
+    : await hlMetaAndAssetCtxs(opts);
+  const universe = raw?.[0]?.universe ?? raw?.universe ?? [];
+  const ctxs = Array.isArray(raw?.[1]) ? raw[1] : [];
+  const entry = { at: now, universe, ctxs };
+  _metaCache.set(key, entry);
+  return entry;
+}
+
+/** Parse HIP-4 coin "#1100" or encoding number → { encoding, outcome, side }. */
+export function parseOutcomeCoin(coin) {
+  const text = String(coin || "").trim();
+  let encoding;
+  if (text.startsWith("#")) encoding = Number(text.slice(1));
+  else if (/^\d+$/.test(text)) encoding = Number(text);
+  else return null;
+  if (!Number.isInteger(encoding) || encoding < 0) return null;
+  const side = encoding % 10;
+  if (side !== 0 && side !== 1) return null;
+  const outcome = Math.floor(encoding / 10);
+  return { encoding, outcome, side, coin: `#${encoding}`, assetId: OUTCOME_ASSET_BASE + encoding };
+}
+
+export function outcomeAssetId(outcome, side) {
+  const o = Number(outcome);
+  const s = Number(side);
+  if (!Number.isInteger(o) || o < 0) throw new Error("hl-assets: outcome id must be a non-negative integer");
+  if (s !== 0 && s !== 1) throw new Error("hl-assets: outcome side must be 0 or 1");
+  const encoding = 10 * o + s;
+  return { encoding, outcome: o, side: s, coin: `#${encoding}`, assetId: OUTCOME_ASSET_BASE + encoding };
+}
+
+/**
+ * Resolve any tradeable HL coin name to asset id + precision.
+ * Accepts: "BTC", "xyz:TSLA", "#1100", { outcome, side }, { dex, coin }.
+ */
+export async function resolveHlAsset(args = {}, opts = {}) {
+  // HIP-4 explicit
+  if (args.outcome != null || (args.coin && String(args.coin).startsWith("#"))) {
+    const parsed =
+      args.outcome != null
+        ? outcomeAssetId(args.outcome, args.side ?? args.outcomeSide ?? 0)
+        : parseOutcomeCoin(args.coin);
+    if (!parsed) throw new Error(`hl-assets: invalid outcome coin ${args.coin}`);
+    // szDecimals for outcomes: typically 2-4; use 2 default (binary contracts)
+    const szDecimals = args.szDecimals != null ? Number(args.szDecimals) : 2;
+    return {
+      kind: "outcome",
+      coin: parsed.coin,
+      assetId: parsed.assetId,
+      encoding: parsed.encoding,
+      outcome: parsed.outcome,
+      side: parsed.side,
+      szDecimals,
+      maxLeverage: 1,
+      dex: null,
+      markPx: null,
+    };
+  }
+
+  const rawName = String(args.coin || args.symbol || args.name || "").trim();
+  if (!rawName) throw new Error("hl-assets: coin required");
+
+  // HIP-3 builder dex coin: dex:COIN
+  if (rawName.includes(":")) {
+    const [dex, ...rest] = rawName.split(":");
+    const leaf = rest.join(":");
+    if (!dex || !leaf) throw new Error(`hl-assets: bad builder coin ${rawName}`);
+    const dexs = await perpDexs(opts);
+    const dexIndex = dexs.findIndex((d) => d && d.name === dex);
+    if (dexIndex < 1) throw new Error(`hl-assets: unknown builder dex "${dex}"`);
+    const { universe, ctxs } = await metaForDex(dex, opts);
+    const index = universe.findIndex((a) => a.name === rawName || a.name === `${dex}:${leaf}` || a.name.endsWith(`:${leaf}`));
+    if (index < 0) throw new Error(`hl-assets: ${rawName} not in dex ${dex} meta`);
+    const asset = universe[index];
+    if (asset.isDelisted) throw new Error(`hl-assets: ${rawName} is delisted`);
+    const assetId = BUILDER_PERP_BASE + dexIndex * 10_000 + index;
+    const ctx = ctxs[index] || {};
+    return {
+      kind: "hip3",
+      coin: asset.name || rawName,
+      assetId,
+      szDecimals: asset.szDecimals ?? 0,
+      maxLeverage: asset.maxLeverage ?? null,
+      dex,
+      dexIndex,
+      indexInMeta: index,
+      markPx: ctx.markPx ?? null,
+    };
+  }
+
+  // Main dex perps
+  const { universe, ctxs } = await metaForDex("", opts);
+  const coin = rawName.toUpperCase();
+  const index = universe.findIndex((a) => a.name === coin);
+  if (index < 0) {
+    // optional: bare leaf match on builder dexs (TSLA -> xyz:TSLA)
+    if (opts.allowBareBuilderLeaf === true) {  // opt-in only; explicit dex:COIN preferred
+      try {
+        const dexs = await perpDexs(opts);
+        for (let di = 1; di < dexs.length; di++) {
+          const d = dexs[di];
+          if (!d?.name) continue;
+          const tryName = `${d.name}:${coin}`;
+          try {
+            return await resolveHlAsset({ coin: tryName }, opts);
+          } catch {
+            /* next dex */
+          }
+        }
+      } catch {
+        /* offline / mock without perpDexs */
+      }
+    }
+    throw new Error(`hl-perps: ${coin} is not a listed perp`);
+  }
+  const asset = universe[index];
+  if (asset.isDelisted) throw new Error(`hl-assets: ${coin} is delisted`);
+  const ctx = ctxs[index] || {};
+  return {
+    kind: "main",
+    coin: asset.name,
+    assetId: index,
+    szDecimals: asset.szDecimals ?? 0,
+    maxLeverage: asset.maxLeverage ?? null,
+    dex: "",
+    markPx: ctx.markPx ?? null,
+  };
+}
+
+export function clearHlAssetCache() {
+  _dexCache = { at: 0, dexs: null };
+  _metaCache.clear();
+}

package/src/data/providers/hl-info.mjs

@@ -0,0 +1,108 @@
+// Hyperliquid public info client — read-only, no agent key.
+
+import { httpJson } from "../http.mjs";
+
+export const HL_INFO_MAINNET = "https://api.hyperliquid.xyz/info";
+export const HL_INFO_TESTNET = "https://api.hyperliquid-testnet.xyz/info";
+
+function infoUrl({ testnet, baseUrl } = {}) {
+  if (baseUrl) {
+    return baseUrl.replace(/\/$/, "").endsWith("/info")
+      ? baseUrl
+      : `${baseUrl.replace(/\/$/, "")}/info`;
+  }
+  if (process.env.HL_INFO_URL) return process.env.HL_INFO_URL;
+  if (process.env.HL_API_URL) {
+    const b = process.env.HL_API_URL.replace(/\/$/, "");
+    return b.endsWith("/info") ? b : `${b}/info`;
+  }
+  return testnet || process.env.HL_TESTNET === "1" ? HL_INFO_TESTNET : HL_INFO_MAINNET;
+}
+
+export async function hlInfo(body, opts = {}) {
+  if (!body || !body.type) throw new Error("hlInfo requires body.type");
+  const url = infoUrl(opts);
+  return httpJson(url, {
+    method: "POST",
+    body,
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function hlHealth(opts = {}) {
+  const mids = await hlInfo({ type: "allMids" }, opts);
+  const n = mids && typeof mids === "object" ? Object.keys(mids).length : 0;
+  return { ok: n > 0, midCount: n };
+}
+
+export async function hlAllMids(opts = {}) {
+  return hlInfo({ type: "allMids" }, opts);
+}
+
+export async function hlL2Book(coin, opts = {}) {
+  if (!coin) throw new Error("hlL2Book requires coin");
+  return hlInfo({ type: "l2Book", coin: String(coin) }, opts);
+}
+
+export async function hlOutcomeMeta(opts = {}) {
+  return hlInfo({ type: "outcomeMeta" }, opts);
+}
+
+export async function hlClearinghouse(user, opts = {}) {
+  if (!user) throw new Error("hlClearinghouse requires user address");
+  return hlInfo({ type: "spotClearinghouseState", user }, opts);
+}
+
+export async function hlUserFills(user, opts = {}) {
+  if (!user) throw new Error("hlUserFills requires user address");
+  return hlInfo({ type: "userFills", user }, opts);
+}
+
+// D1 expansions
+export async function hlMeta(opts = {}) {
+  return hlInfo({ type: "meta" }, opts);
+}
+
+export async function hlMetaAndAssetCtxs(opts = {}) {
+  const body = { type: "metaAndAssetCtxs" };
+  if (opts.dex) body.dex = opts.dex;
+  return hlInfo(body, opts);
+}
+
+export async function hlPerpDexs(opts = {}) {
+  return hlInfo({ type: "perpDexs" }, opts);
+}
+
+export async function hlCandleSnapshot({ coin, interval = "1h", startTime, endTime }, opts = {}) {
+  if (!coin) throw new Error("hlCandleSnapshot requires coin");
+  const req = {
+    type: "candleSnapshot",
+    req: {
+      coin: String(coin),
+      interval,
+      startTime: startTime ?? Date.now() - 24 * 3600 * 1000,
+      endTime: endTime ?? Date.now(),
+    },
+  };
+  return hlInfo(req, opts);
+}
+
+export async function hlOpenOrders(user, opts = {}) {
+  if (!user) throw new Error("hlOpenOrders requires user");
+  return hlInfo({ type: "openOrders", user }, opts);
+}
+
+export async function hlFrontendOpenOrders(user, opts = {}) {
+  if (!user) throw new Error("hlFrontendOpenOrders requires user");
+  return hlInfo({ type: "frontendOpenOrders", user }, opts);
+}
+
+export async function hlUserState(user, opts = {}) {
+  if (!user) throw new Error("hlUserState requires user");
+  return hlInfo({ type: "clearinghouseState", user }, opts);
+}
+
+export async function hlSpotMeta(opts = {}) {
+  return hlInfo({ type: "spotMeta" }, opts);
+}

package/src/data/providers/hl-markets.mjs

@@ -0,0 +1,210 @@
+// Hyperliquid market datapoints for the Hyperliquid agent.
+//
+// The raw /info endpoints return parallel arrays and stringly-typed numbers
+// that every consumer ends up re-deriving: universe[i] pairs with assetCtxs[i],
+// funding is an 8-hour decimal that people want annualized, open interest is
+// denominated in the coin rather than USD. Doing that join once, here, keeps
+// every chart and card consistent instead of each one inventing its own math.
+//
+// Reads only. No keys, no signing.
+
+import { hlMetaAndAssetCtxs, hlAllMids, hlCandleSnapshot, hlL2Book, hlSpotMeta } from "./hl-info.mjs";
+
+/** Liveness: the media lane is healthy when the underlying info plane answers. */
+export async function hlMarketsHealth(opts = {}) {
+  const t0 = Date.now();
+  try {
+    const mids = await hlAllMids(opts);
+    return {
+      provider: "hl-markets",
+      ok: true,
+      venue: "hyperliquid",
+      symbols: Object.keys(mids || {}).length,
+      latencyMs: Date.now() - t0,
+    };
+  } catch (e) {
+    return { provider: "hl-markets", ok: false, error: String(e?.message || e), latencyMs: Date.now() - t0 };
+  }
+}
+
+const HOURS_PER_YEAR = 24 * 365;
+const FUNDING_INTERVAL_HOURS = 8;
+
+function num(value) {
+  if (value == null) return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function pct(a, b) {
+  if (a == null || b == null || b === 0) return null;
+  return ((a - b) / b) * 100;
+}
+
+/**
+ * Join the perp universe with its asset contexts into one flat row per market.
+ *
+ * This is THE datapoint set for an Hyperliquid agent board: price, 24h change, volume,
+ * open interest in both coin and USD, funding (interval + annualized), and the
+ * leverage/decimals metadata needed to render or size an order.
+ */
+export async function hlMarketDatapoints(args = {}, opts = {}) {
+  const [meta, mids] = await Promise.all([
+    hlMetaAndAssetCtxs(opts),
+    hlAllMids(opts).catch(() => ({})),
+  ]);
+
+  // metaAndAssetCtxs returns [ { universe: [...] }, [ ctx, ... ] ]
+  const universe = meta?.[0]?.universe ?? meta?.universe ?? [];
+  const ctxs = Array.isArray(meta?.[1]) ? meta[1] : [];
+
+  const rows = universe.map((asset, i) => {
+    const ctx = ctxs[i] || {};
+    const mark = num(ctx.markPx);
+    const prev = num(ctx.prevDayPx);
+    const oiCoin = num(ctx.openInterest);
+    const funding = num(ctx.funding);
+
+    return {
+      coin: asset.name,
+      index: i,
+      markPx: mark,
+      oraclePx: num(ctx.oraclePx),
+      midPx: num(ctx.midPx) ?? num(mids?.[asset.name]),
+      prevDayPx: prev,
+      change24hPct: pct(mark, prev),
+      dayNtlVolumeUsd: num(ctx.dayNtlVlm),
+      premium: num(ctx.premium),
+      // funding is the per-8h rate as a decimal; both forms are useful and
+      // people get the conversion wrong constantly.
+      fundingRate: funding,
+      fundingRateAprPct: funding == null ? null : funding * (HOURS_PER_YEAR / FUNDING_INTERVAL_HOURS) * 100,
+      openInterestCoin: oiCoin,
+      openInterestUsd: oiCoin == null || mark == null ? null : oiCoin * mark,
+      maxLeverage: asset.maxLeverage ?? null,
+      szDecimals: asset.szDecimals ?? null,
+      isDelisted: Boolean(asset.isDelisted),
+    };
+  });
+
+  const live = rows.filter((r) => !r.isDelisted);
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "market-datapoints",
+    asOfMs: Date.now(),
+    count: live.length,
+    markets: live,
+    totals: {
+      openInterestUsd: live.reduce((a, r) => a + (r.openInterestUsd || 0), 0),
+      dayNtlVolumeUsd: live.reduce((a, r) => a + (r.dayNtlVolumeUsd || 0), 0),
+    },
+  };
+}
+
+/** Top movers / volume / OI / funding leaders — the standard board cuts. */
+export async function hlLeaderboards(args = {}, opts = {}) {
+  const limit = Math.max(1, Math.min(Number(args.limit) || 10, 50));
+  const { markets, asOfMs, totals } = await hlMarketDatapoints(args, opts);
+
+  const by = (key, dir = -1) =>
+    markets
+      .filter((m) => m[key] != null)
+      .sort((a, b) => (a[key] - b[key]) * dir)
+      .slice(0, limit);
+
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "leaderboards",
+    asOfMs,
+    totals,
+    gainers: by("change24hPct"),
+    losers: by("change24hPct", 1),
+    byVolume: by("dayNtlVolumeUsd"),
+    byOpenInterest: by("openInterestUsd"),
+    fundingHighest: by("fundingRateAprPct"),
+    fundingLowest: by("fundingRateAprPct", 1),
+  };
+}
+
+/**
+ * One coin, everything a segment or card needs: current state, the recent
+ * candle series, and top-of-book depth.
+ */
+export async function hlCoinDatapoints(args = {}, opts = {}) {
+  const coin = String(args.coin || args.symbol || "").trim().toUpperCase();
+  if (!coin) throw new Error("hl-markets: coin required");
+  const interval = String(args.interval || "1h");
+  const lookbackMs = Number(args.lookbackMs) || 24 * 60 * 60 * 1000;
+  const endTime = Date.now();
+  const startTime = endTime - lookbackMs;
+
+  const [board, candles, book] = await Promise.all([
+    hlMarketDatapoints({}, opts),
+    hlCandleSnapshot({ coin, interval, startTime, endTime }, opts).catch(() => []),
+    // hlL2Book takes a bare coin string, not an args object.
+    hlL2Book(coin, opts).catch(() => null),
+  ]);
+
+  const market = board.markets.find((m) => m.coin === coin) || null;
+  if (!market) throw new Error(`hl-markets: ${coin} is not a listed perp`);
+
+  const series = (Array.isArray(candles) ? candles : []).map((c) => ({
+    t: Number(c.t),
+    open: num(c.o),
+    high: num(c.h),
+    low: num(c.l),
+    close: num(c.c),
+    volume: num(c.v),
+  }));
+
+  const levels = book?.levels ?? [];
+  const bestBid = num(levels?.[0]?.[0]?.px);
+  const bestAsk = num(levels?.[1]?.[0]?.px);
+
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "coin-datapoints",
+    asOfMs: Date.now(),
+    coin,
+    market,
+    book: {
+      bestBid,
+      bestAsk,
+      spread: bestBid == null || bestAsk == null ? null : bestAsk - bestBid,
+      spreadBps: bestBid == null || bestAsk == null || bestAsk === 0 ? null : ((bestAsk - bestBid) / bestAsk) * 10_000,
+    },
+    candles: { interval, count: series.length, series },
+  };
+}
+
+/** Spot pairs, joined the same way. */
+export async function hlSpotDatapoints(args = {}, opts = {}) {
+  const spot = await hlSpotMeta(opts);
+  const tokens = spot?.tokens ?? [];
+  const pairs = spot?.universe ?? [];
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "spot-datapoints",
+    asOfMs: Date.now(),
+    tokenCount: tokens.length,
+    pairCount: pairs.length,
+    tokens: tokens.map((t) => ({
+      name: t.name,
+      index: t.index,
+      szDecimals: t.szDecimals ?? null,
+      weiDecimals: t.weiDecimals ?? null,
+      tokenId: t.tokenId ?? null,
+      isCanonical: Boolean(t.isCanonical),
+    })),
+    pairs: pairs.map((p) => ({
+      name: p.name,
+      index: p.index,
+      tokens: p.tokens,
+      isCanonical: Boolean(p.isCanonical),
+    })),
+  };
+}

package/src/data/providers/hl-outcome.mjs

@@ -0,0 +1,61 @@
+// HIP-4 outcome market prepare helpers (local, no VPS).
+import { stampPrepared } from "../../prepare-envelope.mjs";
+import { hlOutcomeMeta } from "./hl-info.mjs";
+import { outcomeAssetId, parseOutcomeCoin } from "./hl-assets.mjs";
+import { hlPreparePerpOrder, hlPrepareCancelOrder } from "./hl-perps.mjs";
+
+export async function hlOutcomeList(opts = {}) {
+  const meta = await hlOutcomeMeta(opts);
+  return {
+    provider: "hl-outcome",
+    kind: "outcome-meta",
+    outcomes: meta?.outcomes || [],
+    questions: meta?.questions || [],
+  };
+}
+
+/**
+ * Prepare a HIP-4 outcome order.
+ * args: { outcome, side: 0|1|'yes'|'no', sideName?, coin?, ...hlPreparePerpOrder fields }
+ */
+export async function hlPrepareOutcomeOrder(args = {}, opts = {}) {
+  let coin = args.coin;
+  let outcome = args.outcome;
+  let side = args.side;
+  if (typeof side === "string") {
+    const s = side.toLowerCase();
+    if (s === "yes" || s === "0") side = 0;
+    else if (s === "no" || s === "1") side = 1;
+  }
+  if (args.sideName && outcome != null) {
+    const meta = await hlOutcomeMeta(opts);
+    const o = (meta?.outcomes || []).find((x) => Number(x.outcome) === Number(outcome));
+    if (o?.sideSpecs) {
+      const idx = o.sideSpecs.findIndex(
+        (sp) => String(sp.name).toLowerCase() === String(args.sideName).toLowerCase()
+      );
+      if (idx >= 0) side = idx;
+    }
+  }
+  if (!coin) {
+    if (outcome == null || side == null) {
+      throw new Error("hl-outcome: provide coin (#N) or outcome + side (0/1 or yes/no)");
+    }
+    coin = outcomeAssetId(outcome, side).coin;
+  }
+  const prepared = await hlPreparePerpOrder({ ...args, coin }, opts);
+  // ensure stamped kind
+  return stampPrepared(
+    { ...prepared, kind: "hip4-order", provider: "hl-perps" },
+    { provider: "hl-perps", kind: "hip4-order" }
+  );
+}
+
+export async function hlPrepareOutcomeCancel(args = {}, opts = {}) {
+  let coin = args.coin;
+  if (!coin && args.outcome != null) {
+    const side = args.side ?? 0;
+    coin = outcomeAssetId(args.outcome, side).coin;
+  }
+  return hlPrepareCancelOrder({ ...args, coin }, opts);
+}