@oracle-agent/oracle 0.14.0 → 0.15.0

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

@@ -1,165 +0,0 @@
-// 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

@@ -1,108 +0,0 @@
-// 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

@@ -1,210 +0,0 @@
-// 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

@@ -1,61 +0,0 @@
-// 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);
-}