@oracle-agent/oracle 0.13.0 → 0.14.0

package/src/equities/venues/arcus-spot.mjs

@@ -0,0 +1,105 @@
+// Arcus spot pairs on Robinhood Chain 4663.
+// Tier: quote-only. CRITICAL: bid and ask are passed through UNTOUCHED, including
+// crossed books where bid > ask. Repairing a crossed book here would hide a real
+// data integrity failure from liveness.mjs and let a garbage mid rank as real.
+//
+// Fees are explicitly zero in the fixture capture. A known zero is a fixed point
+// zero with costAccounted true for the fee component alone. Gas and impact are
+// still unknown, so the overall costAccounted claim stays false.
+
+import { getVenues } from '../fixtures.mjs';
+import { fromSourceNumber, requireSourceNumber } from '../sourceNum.mjs';
+import { parseDecimal } from '../num.mjs';
+import { validateQuote } from '../types.mjs';
+
+export const VENUE = 'arcus_spot';
+export const CHAIN = 'robinhood-4663';
+export const TIER = 'quote-only';
+
+function spot() {
+  return getVenues().venues.arcus_spot;
+}
+
+export function listPairs() {
+  return Object.keys(spot().pairs).sort();
+}
+
+export function quote({ symbol, side = 'buy', sizeUsd = null } = {}) {
+  if (typeof symbol !== 'string' || symbol.length === 0) return null;
+  const pair = spot().pairs[symbol];
+  if (!pair) return null;
+
+  // Pass bid and ask through exactly as captured. Do not swap, average, or clamp.
+  const bid = pair.bid === undefined || pair.bid === null ? null : requireSourceNumber(pair.bid, `${symbol}.bid`);
+  const ask = pair.ask === undefined || pair.ask === null ? null : requireSourceNumber(pair.ask, `${symbol}.ask`);
+  const last = fromSourceNumber(pair.last);
+
+  // Mid is only computed when both sides exist. A crossed book still gets a mid
+  // (the arithmetic average of the bad numbers) because mid is evidence, not a
+  // filter. Liveness will exclude the whole quote for crossed-book.
+  let mid = null;
+  if (bid !== null && ask !== null) {
+    mid = {
+      mantissa: bid.mantissa + ask.mantissa,
+      scale: bid.scale === ask.scale ? bid.scale + 1 : Math.max(bid.scale, ask.scale) + 1,
+    };
+    // Align to a common scale before averaging.
+    const scale = Math.max(bid.scale, ask.scale);
+    const b = bid.scale === scale ? bid.mantissa : bid.mantissa * 10n ** BigInt(scale - bid.scale);
+    const a = ask.scale === scale ? ask.mantissa : ask.mantissa * 10n ** BigInt(scale - ask.scale);
+    mid = { mantissa: b + a, scale: scale + 1 };
+    // (b+a) at scale+1 is the average at scale, which is what we want.
+    // Actually: average = (b+a)/2. With mantissa b+a and scale scale+1 that is
+    // (b+a) * 10^-(scale+1) = ((b+a)/10) * 10^-scale, not /2.
+    // Correct: mid = (b+a) / 2 at the same scale.
+    mid = { mantissa: (b + a) / 2n, scale };
+  } else if (last !== null) {
+    mid = last;
+  }
+
+  if (bid === null && ask === null && mid === null) return null;
+
+  const requested = sizeUsd === null ? parseDecimal('0') : sizeUsd;
+  // Explicit zero fee. Known measured zero, not unknown.
+  const fees = parseDecimal('0');
+
+  const q = {
+    venue: VENUE,
+    chain: CHAIN,
+    instrument: 'spot',
+    tier: TIER,
+    symbolRaw: symbol,
+    symbol,
+    side,
+    requestedSize: requested,
+    fees,
+    gasEstimate: null,
+    priceImpact: null,
+    fundingHourly: null,
+    // Fees known as zero, but gas and impact unknown, so overall claim is false.
+    costAccounted: false,
+    capturedAt: getVenues().capturedAt * 1000,
+    blockOrSeq: null,
+    raw: {
+      fixture: 'fixtures/venues.json#venues.arcus_spot',
+      last: pair.last,
+      bid: pair.bid,
+      ask: pair.ask,
+      vol24h: pair.vol24h,
+      feeKnownZero: true,
+      reasonCostUnknown: 'gas and impact at size not captured; fee is a known zero',
+    },
+  };
+
+  if (bid !== null) q.bid = bid;
+  if (ask !== null) q.ask = ask;
+  if (mid !== null) q.mid = mid;
+
+  return validateQuote(q);
+}
+
+export function quoteAll({ side = 'buy', sizeUsd = null } = {}) {
+  return listPairs()
+    .map((symbol) => quote({ symbol, side, sizeUsd }))
+    .filter((q) => q !== null);
+}

package/src/equities/venues/hyperliquid-hip3.mjs

@@ -0,0 +1,224 @@
+// Hyperliquid HIP-3 builder-deployed equity perp adapter.
+// Tier: quote-only. Adapters report source truth including dormant dexs and
+// markets with zero volume. Exclusion of those is liveness.mjs, not this file.
+//
+// Fixture shape (venues.hyperliquid_hip3.dexs):
+//   { abcd: { USA500: { mark, vol24h, oi, fundingHourly, fundingAnnPct, maxLev } }, ... }
+// Symbols are namespaced as dex:TICKER so xyz:NVDA never collides with a cash:NVDA
+// if one ever appears.
+//
+// When fixtures/hip3_l2books.json has a book for the coin, size impact is walked
+// from the book (measured). Fees and gas are still unknown, so overall
+// costAccounted stays false, but priceImpact is no longer null.
+
+import { getHip3L2Books, getVenues } from '../fixtures.mjs';
+import { fromSourceNumber, requireSourceNumber } from '../sourceNum.mjs';
+import { div, mul, parseDecimal, sub, toString } from '../num.mjs';
+import { validateQuote } from '../types.mjs';
+
+export const VENUE = 'hyperliquid_hip3';
+export const CHAIN = 'hyperliquid';
+export const TIER = 'quote-only';
+
+function hip3() {
+  return getVenues().venues.hyperliquid_hip3;
+}
+
+export function listDexs() {
+  return Object.keys(hip3().dexs).sort();
+}
+
+export function listMarkets() {
+  const out = [];
+  for (const [dex, markets] of Object.entries(hip3().dexs)) {
+    for (const ticker of Object.keys(markets)) {
+      out.push(`${dex}:${ticker}`);
+    }
+  }
+  return out.sort();
+}
+
+export function findMarkets(symbol) {
+  if (typeof symbol !== 'string' || symbol.length === 0) return [];
+  const colon = symbol.indexOf(':');
+  if (colon > 0) {
+    const dex = symbol.slice(0, colon);
+    const ticker = symbol.slice(colon + 1);
+    const market = hip3().dexs[dex]?.[ticker];
+    if (!market) return [];
+    return [{ dex, ticker, market }];
+  }
+  const hits = [];
+  for (const [dex, markets] of Object.entries(hip3().dexs)) {
+    if (Object.hasOwn(markets, symbol)) {
+      hits.push({ dex, ticker: symbol, market: markets[symbol] });
+    }
+  }
+  return hits;
+}
+
+function bookFor(dex, ticker) {
+  try {
+    const books = getHip3L2Books().books;
+    return books[`${dex}:${ticker}`] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Walk the ask (buy) or bid (sell) side until notional is filled. Returns
+// { vwap, filledUsd, unfilledUsd, levelsUsed } or null if no book.
+function walkBook(book, side, sizeUsd) {
+  if (!book || sizeUsd === null || sizeUsd.mantissa <= 0n) return null;
+  const levels = side === 'buy' ? book.asks : book.bids;
+  if (!levels || levels.length === 0) return null;
+
+  let remaining = Number(toString(sizeUsd));
+  if (!Number.isFinite(remaining) || remaining <= 0) return null;
+
+  let spent = 0;
+  let qty = 0;
+  let levelsUsed = 0;
+  for (const lvl of levels) {
+    const px = Number(lvl.px);
+    const sz = Number(lvl.sz);
+    if (!(px > 0) || !(sz > 0)) continue;
+    const levelNotional = px * sz;
+    const take = Math.min(remaining, levelNotional);
+    const takeQty = take / px;
+    spent += take;
+    qty += takeQty;
+    remaining -= take;
+    levelsUsed += 1;
+    if (remaining <= 1e-9) break;
+  }
+  if (qty <= 0) return null;
+  return {
+    vwap: spent / qty,
+    filledUsd: spent,
+    unfilledUsd: Math.max(0, remaining),
+    levelsUsed,
+  };
+}
+
+function impactFromBook(book, side, sizeUsd, mark) {
+  const walk = walkBook(book, side, sizeUsd);
+  if (!walk) return { impact: null, depth: null };
+  const markN = Number(toString(mark));
+  if (!(markN > 0)) return { impact: null, depth: walk };
+  // Buy impact = (vwap - mark) / mark ; sell impact = (mark - vwap) / mark
+  const raw = side === 'buy' ? (walk.vwap - markN) / markN : (markN - walk.vwap) / markN;
+  const clamped = Math.max(0, raw);
+  // Encode as fixed point via decimal string (source number path).
+  const impact = fromSourceNumber(Number(clamped.toPrecision(12)));
+  return {
+    impact,
+    depth: {
+      ...walk,
+      impactFraction: clamped,
+      fullyFilled: walk.unfilledUsd <= 1e-6,
+    },
+  };
+}
+
+function emitQuote({ dex, ticker, market, side, size }) {
+  const mark = requireSourceNumber(market.mark, `${dex}:${ticker}.mark`);
+  const funding = fromSourceNumber(market.fundingHourly);
+  const vol24h = fromSourceNumber(market.vol24h);
+  const oi = fromSourceNumber(market.oi);
+  const requested = size === null ? parseDecimal('0') : size;
+
+  const book = bookFor(dex, ticker);
+  let priceImpact = null;
+  let depthMeta = null;
+  let reasonCostUnknown = 'fees and gas not captured';
+
+  if (requested.mantissa > 0n) {
+    if (book) {
+      const walked = impactFromBook(book, side, requested, mark);
+      priceImpact = walked.impact;
+      depthMeta = walked.depth;
+      if (!depthMeta?.fullyFilled) {
+        reasonCostUnknown =
+          'book walked but size exceeds visible depth; fees and gas not captured';
+      } else {
+        reasonCostUnknown =
+          'impact measured from l2Book; fees and gas still not captured';
+      }
+    } else {
+      reasonCostUnknown = 'no order book depth wired for this coin; fees and gas not captured';
+    }
+  } else if (!book) {
+    reasonCostUnknown = 'no order book depth wired for this coin; fees and gas not captured';
+  } else {
+    reasonCostUnknown = 'zero size; fees and gas not captured';
+  }
+
+  // Fees and gas unknown always => costAccounted false. Depth only fills priceImpact.
+  const costAccounted = false;
+
+  const q = {
+    venue: VENUE,
+    chain: CHAIN,
+    instrument: 'perp',
+    tier: TIER,
+    symbolRaw: `${dex}:${ticker}`,
+    symbol: ticker,
+    side,
+    requestedSize: requested,
+    mark,
+    fees: null,
+    gasEstimate: null,
+    priceImpact,
+    fundingHourly: funding,
+    costAccounted,
+    capturedAt: getVenues().capturedAt * 1000,
+    blockOrSeq: null,
+    raw: {
+      fixture: 'fixtures/venues.json#venues.hyperliquid_hip3',
+      dex,
+      ticker,
+      vol24h: market.vol24h,
+      oi: market.oi,
+      fundingAnnPct: market.fundingAnnPct,
+      maxLev: market.maxLev,
+      reasonCostUnknown,
+      hasL2Book: book !== null,
+      l2BookFixture: book ? 'fixtures/hip3_l2books.json' : null,
+      depth: depthMeta,
+    },
+  };
+
+  if (vol24h !== null) q.raw.vol24hFixed = vol24h;
+  if (oi !== null) q.raw.oiFixed = oi;
+
+  // Attach top of book when present as evidence, not as repaired mid.
+  if (book?.bids?.[0] && book?.asks?.[0]) {
+    q.bid = parseDecimal(String(book.bids[0].px));
+    q.ask = parseDecimal(String(book.asks[0].px));
+  }
+
+  return validateQuote(q);
+}
+
+export function quote({ symbol, side = 'buy', sizeUsd = null } = {}) {
+  const hits = findMarkets(symbol);
+  if (hits.length === 0) return null;
+  if (hits.length > 1) return null;
+  return emitQuote({ ...hits[0], side, size: sizeUsd });
+}
+
+export function quoteAll({ side = 'buy', sizeUsd = null, ticker = null } = {}) {
+  const out = [];
+  for (const namespaced of listMarkets()) {
+    const [dex, t] = namespaced.split(':');
+    if (ticker !== null && t !== ticker) continue;
+    const market = hip3().dexs[dex][t];
+    out.push(emitQuote({ dex, ticker: t, market, side, size: sizeUsd }));
+  }
+  return out;
+}
+
+export function quoteCore(/* ignored */) {
+  return [];
+}

package/src/equities/venues/rh-uniswap.mjs

@@ -0,0 +1,216 @@
+// Robinhood Chain Uniswap adapter. This is the ONLY prepare tier venue on the desk.
+// Everything else can quote, but this is the one place a user can actually act, which
+// is why bestPreparable exists as a separate pointer from the overall ranking winner.
+//
+// Pricing comes from fixtures/rh_pool_state.json, captured live from chain 4663 via
+// pair.slot0() for Uniswap V3 pools and StateView.getSlot0(poolId) for V4 pools. The
+// original fixture capture recorded only USD liquidity with NO price field, so pool
+// price could not be derived from it at all. That gap is why the state file exists.
+//
+// Chainlink oracle reads are REFERENCE ONLY. They are emitted as referencePrice and
+// are never a rankable route, because nobody can trade at the oracle print.
+
+import { getOracles, getRhPoolState } from '../fixtures.mjs';
+import { fromSourceNumber } from '../sourceNum.mjs';
+import {
+  div,
+  fromScaledInteger,
+  mul,
+  parseDecimal,
+  rescale,
+  sub,
+  toString as numToString,
+} from '../num.mjs';
+import { validateQuote } from '../types.mjs';
+
+export const VENUE = 'rh_uniswap';
+export const CHAIN = 4663;
+export const TIER = 'prepare';
+
+// Q96 is the Uniswap fixed point base. sqrtPriceX96 is sqrt(price) * 2^96, so price
+// is (sqrtPriceX96^2) / 2^192. Squaring first in BigInt keeps this exact.
+const Q192 = 1n << 192n;
+
+// Working precision for the price ratio. High enough that a sub cent equity price is
+// not truncated away, bounded so the mantissa stays sane.
+const PRICE_SCALE = 18;
+
+// Gas units per route shape. These are estimates for a single swap on this chain and
+// are labelled as estimates everywhere they surface. A V4 swap routes through the
+// PoolManager unlock/settle flow and costs materially more than a V3 exactInputSingle.
+const GAS_UNITS = Object.freeze({ v3: 180000n, v4: 240000n });
+
+function poolStateFile() {
+  return getRhPoolState();
+}
+
+// price = sqrtPriceX96^2 / 2^192, expressed as token1 per token0 in RAW base units.
+function rawRatio(sqrtPriceX96) {
+  const sq = sqrtPriceX96 * sqrtPriceX96;
+  // Scale up before dividing so BigInt truncation does not eat the whole fraction.
+  const scaled = (sq * 10n ** BigInt(PRICE_SCALE)) / Q192;
+  return { mantissa: scaled, scale: PRICE_SCALE };
+}
+
+// Convert the raw token1-per-token0 ratio into quote units per ONE equity token.
+// Decimal correction and orientation are separate concerns and both must be applied.
+function poolPrice(state) {
+  const ratio = rawRatio(BigInt(state.sqrtPriceX96));
+  const quoteDecimals = state.quote === 'USDG' ? 6 : 18;
+  const equityDecimals = 18;
+
+  if (state.quoteIsToken0) {
+    // ratio is equity-per-quote in raw units. Human equity per quote is
+    // ratio * 10^quoteDecimals / 10^equityDecimals, and price is its reciprocal.
+    const humanEquityPerQuote = div(
+      mul(ratio, fromScaledInteger(10n ** BigInt(quoteDecimals), 0)),
+      fromScaledInteger(10n ** BigInt(equityDecimals), 0),
+      PRICE_SCALE,
+    );
+    if (humanEquityPerQuote.mantissa === 0n) return null;
+    return div(parseDecimal('1'), humanEquityPerQuote, PRICE_SCALE);
+  }
+
+  // ratio is quote-per-equity in raw units, so only the decimal correction applies.
+  return div(
+    mul(ratio, fromScaledInteger(10n ** BigInt(equityDecimals), 0)),
+    fromScaledInteger(10n ** BigInt(quoteDecimals), 0),
+    PRICE_SCALE,
+  );
+}
+
+// Chainlink price() is a scaled integer. The live feed composition on this chain is
+// 36 oracle decimals plus 6 USDG decimals minus 18 equity decimals, giving scale 24.
+export function referencePrice(symbol) {
+  const oracles = getOracles();
+  const asset = oracles.assets[symbol];
+  if (!asset) return null;
+  return fromScaledInteger(asset.rawPrice, oracles.oracleScaleExp);
+}
+
+// Constant product price impact at a requested notional. A V3 or V4 pool concentrates
+// liquidity, so this xy=k estimate is a MODEL, not a measurement: real impact depends
+// on tick distribution we have not captured. It is therefore reported with
+// costAccounted false so it can never masquerade as a measured cost.
+function modelImpact(liqUsd, notionalUsd) {
+  if (liqUsd === null || notionalUsd === null) return null;
+  if (liqUsd.mantissa <= 0n || notionalUsd.mantissa <= 0n) return null;
+  // impact fraction ~ notional / (liquidity + notional)
+  const denom = { ...liqUsd };
+  const sum = div(notionalUsd, addFixed(denom, notionalUsd), PRICE_SCALE);
+  return sum;
+}
+
+function addFixed(left, right) {
+  const scale = Math.max(left.scale, right.scale);
+  return {
+    mantissa: rescale(left, scale).mantissa + rescale(right, scale).mantissa,
+    scale,
+  };
+}
+
+// Gas cost in QUOTE units. gasPriceWei * gasUnits gives wei of native token. This
+// chain's native token is ETH, so converting that to USDG needs an ETH price we did
+// NOT capture. Rather than invent one, gas is returned in native wei alongside an
+// explicit null for its quote denomination, and callers must treat it as unknown.
+export function gasEstimate(version) {
+  const state = poolStateFile();
+  const units = GAS_UNITS[version];
+  if (!units) return null;
+  const wei = BigInt(state.gasPriceWei) * units;
+  return { wei, units, native: 'ETH' };
+}
+
+export function listPools() {
+  return Object.keys(poolStateFile().pools).sort();
+}
+
+export function quote({ symbol, side = 'buy', sizeUsd = null } = {}) {
+  if (typeof symbol !== 'string' || symbol.length === 0) {
+    throw new TypeError('symbol must be a nonempty string');
+  }
+  const state = poolStateFile();
+  const pool = state.pools[symbol];
+  if (!pool) return null;
+
+  const price = poolPrice(pool);
+  if (price === null) return null;
+
+  const liqUsd = fromSourceNumber(pool.liqUsd);
+  const requested = sizeUsd === null ? parseDecimal('0') : sizeUsd;
+
+  // Fees: a V3 pool reports its fee tier in ppm and that is a real measured number.
+  // A V4 pool's fee can be dynamic via its hook and we did not capture it, so it
+  // stays null and forces costAccounted false rather than defaulting to zero.
+  const fees =
+    pool.feePpm === null || pool.feePpm === undefined
+      ? null
+      : div(fromScaledInteger(BigInt(pool.feePpm), 0), fromScaledInteger(1000000n, 0), 8);
+
+  const impact = requested.mantissa === 0n ? parseDecimal('0') : modelImpact(liqUsd, requested);
+
+  const gas = gasEstimate(pool.version);
+  // Gas is known in native wei but NOT convertible to the quote asset without an ETH
+  // price we never captured. Unknown is not zero, so this stays null.
+  const gasInQuote = null;
+
+  // costAccounted is a claim that every applicable cost is known. Gas is not
+  // denominated, V4 fees are undiscovered, and impact at size is modelled rather than
+  // measured. Any one of those is enough to make the claim false.
+  const costAccounted = false;
+
+  const q = {
+    venue: VENUE,
+    chain: CHAIN,
+    instrument: 'spot',
+    tier: TIER,
+    symbolRaw: symbol,
+    symbol,
+    side,
+    requestedSize: requested,
+    mid: price,
+    fees,
+    gasEstimate: gasInQuote,
+    priceImpact: impact,
+    fundingHourly: null,
+    costAccounted,
+    capturedAt: state.capturedAt * 1000,
+    blockOrSeq: state.block,
+    raw: {
+      fixture: 'fixtures/rh_pool_state.json',
+      pair: pool.pair,
+      version: pool.version,
+      sqrtPriceX96: pool.sqrtPriceX96,
+      quote: pool.quote,
+      quoteIsToken0: pool.quoteIsToken0,
+      liqUsd: pool.liqUsd,
+      gasNativeWei: gas === null ? null : gas.wei.toString(),
+      gasUnits: gas === null ? null : gas.units.toString(),
+      impactModel: 'constant-product-estimate',
+      notes: [
+        'price read live from chain 4663',
+        pool.version === 'v4'
+          ? 'v4 fee may be dynamic via hook and was not captured'
+          : 'v3 fee tier is the pool static fee',
+        'gas known in native wei only, no ETH price captured to denominate it',
+      ],
+    },
+  };
+
+  const reference = referencePrice(symbol);
+  if (reference !== null) {
+    q.referencePrice = reference;
+    // Basis versus the oracle print. Useful evidence, never a tradeable route.
+    q.referenceBasisBps = numToString(
+      div(mul(sub(price, reference), fromScaledInteger(10000n, 0)), reference, 4),
+    );
+  }
+
+  return validateQuote(q);
+}
+
+export function quoteAll({ side = 'buy', sizeUsd = null } = {}) {
+  return listPools()
+    .map((symbol) => quote({ symbol, side, sizeUsd }))
+    .filter((q) => q !== null);
+}

package/src/equities/venues/solana-xstocks.mjs

@@ -0,0 +1,139 @@
+// Solana xStocks adapter (Backed / xStocks SPL tokens).
+// Tier: quote-only. Source is DexScreener-shaped fixture data: priceUsd and
+// liquidityUsd are third-party floats. Converting them to fixed point does NOT
+// make them exact. Impact at size is a model estimate, so any non-trivial size
+// forces costAccounted: false.
+//
+// symbolRaw keeps the x suffix (NVDAx). symbol is the canonical Oracle ticker
+// (NVDA). normalize.mjs already understands the x-suffix rule.
+
+import { getSolanaXstocks } from '../fixtures.mjs';
+import { fromSourceNumber, requireSourceNumber } from '../sourceNum.mjs';
+import { div, parseDecimal } from '../num.mjs';
+import { validateQuote } from '../types.mjs';
+
+export const VENUE = 'solana_xstocks';
+export const CHAIN = 'solana';
+export const TIER = 'quote-only';
+
+// Below this USD liquidity, treat the market as too thin to rank at any size.
+const THIN_LIQ_USD = 25_000;
+// Size above this fraction of reported liq is never cost-accounted.
+const IMPACT_SIZE_FRACTION = 0.02;
+
+function data() {
+  return getSolanaXstocks();
+}
+
+export function listTokens() {
+  return Object.keys(data().tokens).sort();
+}
+
+function bestPair(symbol) {
+  const pairs = data().pairs[symbol];
+  if (!pairs || pairs.length === 0) return null;
+  // Already sorted by liq desc at capture time; re-sort defensively.
+  return [...pairs].sort((a, b) => (b.liquidityUsd ?? 0) - (a.liquidityUsd ?? 0))[0];
+}
+
+function modelImpact(liqUsd, sizeUsd) {
+  if (liqUsd === null || sizeUsd === null) return null;
+  if (liqUsd.mantissa <= 0n || sizeUsd.mantissa <= 0n) return parseDecimal('0');
+  // Constant-product-ish: impact fraction ~= size / (liq + size)
+  const scale = Math.max(liqUsd.scale, sizeUsd.scale);
+  const l =
+    liqUsd.scale === scale
+      ? liqUsd.mantissa
+      : liqUsd.mantissa * 10n ** BigInt(scale - liqUsd.scale);
+  const s =
+    sizeUsd.scale === scale
+      ? sizeUsd.mantissa
+      : sizeUsd.mantissa * 10n ** BigInt(scale - sizeUsd.scale);
+  // (s / (l+s)) at scale+6 for a bit of room
+  const num = s * 10n ** 6n;
+  const den = l + s;
+  return { mantissa: num / den, scale: 6 };
+}
+
+export function quote({ symbol, side = 'buy', sizeUsd = null } = {}) {
+  if (typeof symbol !== 'string' || symbol.length === 0) return null;
+
+  // Accept NVDAx or NVDA.
+  let bare = symbol;
+  let symbolRaw = symbol;
+  const tokens = data().tokens;
+  if (Object.hasOwn(tokens, symbol)) {
+    bare = symbol;
+    symbolRaw = tokens[symbol].symbolRaw;
+  } else if (symbol.endsWith('x') || symbol.endsWith('X')) {
+    const candidate = symbol.slice(0, -1).toUpperCase();
+    if (Object.hasOwn(tokens, candidate)) {
+      bare = candidate;
+      symbolRaw = tokens[candidate].symbolRaw;
+    } else {
+      return null;
+    }
+  } else {
+    return null;
+  }
+
+  const token = tokens[bare];
+  const pair = bestPair(bare);
+  if (!token || !pair) return null;
+
+  const mid = requireSourceNumber(pair.priceUsd, `${bare}.priceUsd`);
+  const liq = fromSourceNumber(pair.liquidityUsd);
+  const requested = sizeUsd === null ? parseDecimal('0') : sizeUsd;
+
+  const impact =
+    requested.mantissa === 0n ? parseDecimal('0') : modelImpact(liq, requested);
+
+  // DexScreener liq is approximate. Any real size is unaccounted for impact quality.
+  let costAccounted = false;
+  if (requested.mantissa === 0n && (pair.liquidityUsd ?? 0) >= THIN_LIQ_USD) {
+    // Even at zero size we do not claim full cost accounting: fees and gas unknown.
+    costAccounted = false;
+  }
+
+  const q = {
+    venue: VENUE,
+    chain: CHAIN,
+    instrument: 'spot',
+    tier: TIER,
+    symbolRaw,
+    symbol: bare,
+    side,
+    requestedSize: requested,
+    mid,
+    fees: null,
+    gasEstimate: null,
+    priceImpact: impact,
+    fundingHourly: null,
+    costAccounted,
+    capturedAt: data().capturedAt * 1000,
+    blockOrSeq: null,
+    raw: {
+      fixture: 'fixtures/solana_xstocks.json',
+      mint: token.mint,
+      pairAddress: pair.pairAddress,
+      dexId: pair.dexId,
+      quote: pair.quote,
+      liquidityUsd: pair.liquidityUsd,
+      volume24h: pair.volume24h,
+      priceUsd: pair.priceUsd,
+      source: 'dexscreener',
+      approximate: true,
+      reasonCostUnknown:
+        'DexScreener liquidity.usd is a third-party float; fees and SOL gas not captured; impact is modeled',
+      thin: (pair.liquidityUsd ?? 0) < THIN_LIQ_USD,
+    },
+  };
+
+  return validateQuote(q);
+}
+
+export function quoteAll({ side = 'buy', sizeUsd = null } = {}) {
+  return listTokens()
+    .map((symbol) => quote({ symbol, side, sizeUsd }))
+    .filter((q) => q !== null);
+}