@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/data/providers/babylon-staking.mjs

@@ -0,0 +1,149 @@
+// Babylon BTC staking — keyless read plane (staking-api.babylonlabs.io v2).
+//
+// Why this exists: Babylon is the largest native-BTC staking protocol, and its
+// public v2 API answers the question Oracle actually needs — "what is THIS
+// staker's BTC position?" — without a key, without an account, and without the
+// user handing over anything but a public key.
+//
+// Verified live (v2):
+//   GET /v2/stats                              200  APR / TVL / delegation counts
+//   GET /v2/finality-providers                 200  FP roster + state + commission
+//   GET /v2/delegations?staker_pk_hex=<pk>     200  per-staker positions (paginated)
+//
+// Read-only. No signing, no unbonding, no withdrawal. Staking actions are
+// user-wallet operations and are deliberately absent from this module.
+
+import { httpJson } from "../http.mjs";
+
+export const BABYLON_STAKING_API = "https://staking-api.babylonlabs.io";
+
+function baseUrl(opts = {}) {
+  return String(opts.baseUrl || process.env.BABYLON_STAKING_API_URL || BABYLON_STAKING_API).replace(/\/$/, "");
+}
+
+function get(path, opts = {}) {
+  return httpJson(`${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+    headers: { Accept: "application/json" },
+  });
+}
+
+/**
+ * Babylon identifies stakers and finality providers by 32-byte x-only BTC
+ * public keys (64 hex chars). Accept the 33-byte compressed form too and drop
+ * the parity byte, because that is what most wallets hand the user.
+ */
+export function babylonPkHex(value, label = "pkHex") {
+  const text = String(value || "").trim().toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]+$/.test(text)) throw new Error(`babylon-staking: ${label} must be hex`);
+  if (text.length === 66 && (text.startsWith("02") || text.startsWith("03"))) return text.slice(2);
+  if (text.length !== 64) throw new Error(`babylon-staking: ${label} must be a 64-char x-only (or 66-char compressed) BTC public key`);
+  return text;
+}
+
+export async function babylonHealth(opts = {}) {
+  try {
+    const res = await get("/v2/stats", opts);
+    const data = res?.data || {};
+    const tvl = Number(data.active_tvl ?? 0);
+    return {
+      ok: Number.isFinite(tvl) && tvl > 0,
+      provider: "babylon-staking",
+      baseUrl: baseUrl(opts),
+      activeTvlSats: String(data.active_tvl ?? ""),
+      activeFinalityProviders: data.active_finality_providers ?? null,
+      exec: false,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      provider: "babylon-staking",
+      baseUrl: baseUrl(opts),
+      error: String(error?.message || error),
+      exec: false,
+    };
+  }
+}
+
+/** Protocol-wide staking stats: TVL in sats, delegation counts, BTC staking APR. */
+export async function babylonStats(_args = {}, opts = {}) {
+  const res = await get("/v2/stats", opts);
+  const d = res?.data || {};
+  return {
+    provider: "babylon-staking",
+    activeTvlSats: String(d.active_tvl ?? ""),
+    totalActiveTvlSats: String(d.total_active_tvl ?? ""),
+    activeDelegations: d.active_delegations ?? null,
+    totalActiveDelegations: d.total_active_delegations ?? null,
+    activeFinalityProviders: d.active_finality_providers ?? null,
+    totalFinalityProviders: d.total_finality_providers ?? null,
+    // APRs arrive as fractions (0.00042 = 0.042%). Surface both so a caller
+    // cannot silently render a fraction as a percent.
+    btcStakingApr: d.btc_staking_apr ?? null,
+    btcStakingAprPct: d.btc_staking_apr == null ? null : Number(d.btc_staking_apr) * 100,
+    maxStakingApr: d.max_staking_apr ?? null,
+    maxStakingAprPct: d.max_staking_apr == null ? null : Number(d.max_staking_apr) * 100,
+    raw: d,
+  };
+}
+
+/** Finality provider roster. Optional `state` filter, e.g. FINALITY_PROVIDER_STATUS_ACTIVE. */
+export async function babylonFinalityProviders(args = {}, opts = {}) {
+  const res = await get("/v2/finality-providers", opts);
+  let rows = Array.isArray(res?.data) ? res.data : [];
+  if (args.state) {
+    const want = String(args.state).trim().toUpperCase();
+    rows = rows.filter((r) => String(r.state || "").toUpperCase().includes(want));
+  }
+  if (args.btcPk) {
+    const pk = babylonPkHex(args.btcPk, "btcPk");
+    rows = rows.filter((r) => String(r.btc_pk || "").toLowerCase() === pk);
+  }
+  const limit = Math.min(500, Math.max(1, Number(args.limit || rows.length || 1)));
+  return {
+    provider: "babylon-staking",
+    count: rows.length,
+    finalityProviders: rows.slice(0, limit).map((r) => ({
+      btcPk: r.btc_pk ?? null,
+      moniker: r.description?.moniker ?? null,
+      website: r.description?.website ?? null,
+      state: r.state ?? null,
+      commission: r.commission ?? null,
+      activeTvlSats: r.active_tvl == null ? null : String(r.active_tvl),
+      activeDelegations: r.active_delegations ?? null,
+    })),
+  };
+}
+
+/**
+ * Per-staker BTC delegations. This is the keyless per-user position read: the
+ * caller supplies only a PUBLIC key, so nothing here is custodial.
+ */
+export async function babylonDelegations(args = {}, opts = {}) {
+  const stakerPk = babylonPkHex(args.stakerPkHex || args.stakerPk || args.pkHex || args.pk, "stakerPkHex");
+  const params = new URLSearchParams({ staker_pk_hex: stakerPk });
+  if (args.paginationKey) params.set("pagination_key", String(args.paginationKey));
+  const res = await get(`/v2/delegations?${params}`, opts);
+  const rows = Array.isArray(res?.data) ? res.data : [];
+  const totalSats = rows.reduce((n, r) => n + Number(r.delegation_staking?.staking_amount ?? r.staking_amount ?? 0), 0);
+  return {
+    provider: "babylon-staking",
+    stakerPkHex: stakerPk,
+    count: rows.length,
+    totalStakedSats: String(totalSats),
+    nextKey: res?.pagination?.next_key || null,
+    delegations: rows.map((r) => ({
+      stakingTxHashHex: r.delegation_staking?.staking_tx_hash_hex ?? r.staking_tx_hash_hex ?? null,
+      state: r.state ?? null,
+      stakingAmountSats:
+        r.delegation_staking?.staking_amount == null && r.staking_amount == null
+          ? null
+          : String(r.delegation_staking?.staking_amount ?? r.staking_amount),
+      stakingTimelock: r.delegation_staking?.staking_timelock ?? null,
+      startHeight: r.delegation_staking?.start_height ?? null,
+      finalityProviderBtcPks: r.finality_provider_btc_pks_hex ?? null,
+    })),
+    raw: rows,
+  };
+}

package/src/data/providers/balancer.mjs

@@ -0,0 +1,209 @@
+// Balancer public GraphQL API + v3 Router exact-input prepare. No key.
+import { Interface, getAddress, isAddress } from "ethers";
+import { httpJson } from "../http.mjs";
+import { rpcCall as defaultRpcCall } from "./evm-rpc.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall } from "../../auto-slippage.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
+
+export const BALANCER_API = "https://api-v3.balancer.fi/";
+const endpoint = (o = {}) => o.baseUrl || process.env.BALANCER_API_URL || BALANCER_API;
+
+async function gql(query, variables, opts = {}) {
+  return httpJson(endpoint(opts), {
+    method: "POST",
+    body: { query, variables },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+}
+
+const POOLS_QUERY = `query Pools($first: Int, $where: GqlPoolFilter) { poolGetPools(first: $first, where: $where) { id address chain type protocolVersion dynamicData { totalLiquidity volume24h fees24h } } }`;
+
+// Official Balancer v3 Router deployments; bytecode checked via eth_getCode on
+// 2026-07-23. Polygon is intentionally excluded from this v3 prepare slice.
+export const BALANCER_V3_CHAINS = Object.freeze({
+  1: {
+    name: "ethereum",
+    router: "0xAE563E3f8219521950555F5962419C8919758Ea2",
+    weth: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  },
+  10: {
+    name: "optimism",
+    router: "0xe2fa4e1d17725e72dcdAfe943Ecf45dF4B9E285b",
+    weth: "0x4200000000000000000000000000000000000006",
+    usdc: "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
+  },
+  8453: {
+    name: "base",
+    router: "0x3f170631ed9821Ca51A59D996aB095162438DC10",
+    weth: "0x4200000000000000000000000000000000000006",
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  },
+  42161: {
+    name: "arbitrum",
+    router: "0xEAedc32a51c510d35ebC11088fD5fF2b47aACF2E",
+    weth: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+    usdc: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+  },
+  43114: {
+    name: "avalanche",
+    router: "0xF39CA6ede9BF7820a952b52f3c94af526bAB9015",
+    weth: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
+    usdc: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+  },
+});
+
+const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+const ZERO = "0x0000000000000000000000000000000000000000";
+const BALANCER_V3_IFACE = new Interface([
+  "function querySwapSingleTokenExactIn(address pool,address tokenIn,address tokenOut,uint256 exactAmountIn,address sender,bytes userData) returns (uint256 amountOut)",
+  "function swapSingleTokenExactIn(address pool,address tokenIn,address tokenOut,uint256 exactAmountIn,uint256 minAmountOut,uint256 deadline,bool wethIsEth,bytes userData) payable returns (uint256 amountOut)",
+]);
+
+function chainMeta(chainId) {
+  const id = Number(chainId ?? 8453);
+  const meta = BALANCER_V3_CHAINS[id];
+  if (!meta) {
+    throw new Error(`balancer-v3: unsupported chainId ${chainId} (supported: ${Object.keys(BALANCER_V3_CHAINS).join(", ")})`);
+  }
+  return { chainId: id, ...meta };
+}
+
+function isNativeToken(value) {
+  const v = String(value || "").toLowerCase();
+  return !v || v === "eth" || v === "native" || v === ZERO || v === NATIVE.toLowerCase();
+}
+
+function normalizeAddress(value, label) {
+  if (!isAddress(value)) throw new Error(`${label} must be a valid EVM address`);
+  return getAddress(value);
+}
+
+function normalizeToken(value, meta, label) {
+  const s = String(value || "");
+  if (isNativeToken(s) || /^weth$/i.test(s)) return getAddress(meta.weth);
+  if (/^usdc$/i.test(s)) return getAddress(meta.usdc);
+  return normalizeAddress(s, label);
+}
+
+function positiveAmount(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;
+}
+
+function userData(value) {
+  if (value == null || value === "") return "0x";
+  const data = String(value);
+  if (!/^0x[0-9a-fA-F]*$/.test(data)) throw new Error("balancer userData must be hex");
+  return data;
+}
+
+export async function balancerPools(args = {}, opts = {}) {
+  const first = Math.min(100, Math.max(1, Number(args.first || 20)));
+  const chains = (args.chains || [args.chain || "ETHEREUM"]).map((x) => String(x).toUpperCase());
+  return gql(POOLS_QUERY, { first, chains, where: { chainIn: chains } }, opts);
+}
+
+export async function balancerHealth(opts = {}) {
+  const data = await gql("query { __typename }", {}, opts);
+  return { ok: data?.data?.__typename === "Query" };
+}
+
+export async function balancerQuote(q = {}, opts = {}) {
+  const meta = chainMeta(q.chainId);
+  const pool = normalizeAddress(q.pool, "balancer pool");
+  const tokenInRaw = q.tokenIn || "WETH";
+  const tokenIn = normalizeToken(tokenInRaw, meta, "balancer tokenIn");
+  const tokenOut = normalizeToken(q.tokenOut || "USDC", meta, "balancer tokenOut");
+  const amountIn = positiveAmount(q.amountIn, "balancer amountIn");
+  const sender = normalizeAddress(q.sender || q.from || q.fromAddress || q.recipient, "balancer sender");
+  const data = BALANCER_V3_IFACE.encodeFunctionData("querySwapSingleTokenExactIn", [
+    pool,
+    tokenIn,
+    tokenOut,
+    amountIn,
+    sender,
+    userData(q.userData),
+  ]);
+  const call = opts.rpcCall || defaultRpcCall;
+  const raw = await call(meta.chainId, "eth_call", [{ to: meta.router, data }, q.blockTag || "latest"], opts);
+  const decoded = BALANCER_V3_IFACE.decodeFunctionResult("querySwapSingleTokenExactIn", raw);
+  const amountOut = BigInt(decoded[0]);
+  if (amountOut <= 0n) throw new Error("balancer quote returned zero output");
+  return attachAutoSlippage({
+    venue: "balancer",
+    protocolVersion: 3,
+    chainId: meta.chainId,
+    chain: meta.name,
+    router: meta.router,
+    pool,
+    tokenIn,
+    tokenOut,
+    amountIn: amountIn.toString(),
+    amountOut: amountOut.toString(),
+  }, {
+    chainId: meta.chainId,
+    venue: meta.router,
+    amountOut: amountOut.toString(),
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+export async function balancerPrepare(q = {}, opts = {}) {
+  const meta = chainMeta(q.chainId);
+  const sender = normalizeAddress(q.sender || q.from || q.fromAddress || q.recipient, "balancer sender");
+  const inputRaw = q.tokenIn || "WETH";
+  const nativeInput = isNativeToken(inputRaw);
+  const quote = await balancerQuote({ ...q, sender }, opts);
+  const deadlineWindow = Math.min(600, Math.max(30, Number(q.deadlineSeconds ?? 300)));
+  const nowSeconds = Number(opts.nowSeconds ?? Math.floor(Date.now() / 1000));
+  const deadline = BigInt(nowSeconds + deadlineWindow);
+  const wethIsEth = q.wethIsEth != null ? Boolean(q.wethIsEth) : nativeInput;
+  const data = BALANCER_V3_IFACE.encodeFunctionData("swapSingleTokenExactIn", [
+    quote.pool,
+    quote.tokenIn,
+    quote.tokenOut,
+    BigInt(quote.amountIn),
+    BigInt(quote.amountOutMinimum),
+    deadline,
+    wethIsEth,
+    userData(q.userData),
+  ]);
+  return stampPrepared({
+    provider: "balancer",
+    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: meta.chainId,
+    deadline: deadline.toString(),
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval: nativeInput ? null : {
+      token: quote.tokenIn,
+      spender: meta.router,
+      amount: quote.amountIn,
+    },
+    transaction: {
+      chainId: meta.chainId,
+      from: sender,
+      to: meta.router,
+      data,
+      value: nativeInput ? quote.amountIn : "0",
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId: meta.chainId, venue: meta.router, data }),
+    },
+  }, { provider: "balancer", kind: "balancer-tx" });
+}

package/src/data/providers/beefy-yields.mjs

@@ -0,0 +1,45 @@
+// Beefy Finance — cross-chain yield aggregator vaults (no API key).
+
+import { httpJson } from "../http.mjs";
+
+export const BEEFY_API = "https://api.beefy.finance";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.BEEFY_API_URL || BEEFY_API).replace(/\/$/, "");
+}
+
+export async function beefyHealth(opts = {}) {
+  try {
+    const data = await httpJson(`${base(opts)}/apy`, {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 15_000,
+    });
+    const keys = Object.keys(data || {});
+    return { ok: keys.length > 0, provider: "beefy-yields", vaultCount: keys.length };
+  } catch (e) {
+    return { ok: false, provider: "beefy-yields", error: String(e.message || e).slice(0, 120) };
+  }
+}
+
+export async function beefyApy(args = {}, opts = {}) {
+  const data = await httpJson(`${base(opts)}/apy`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  if (args.chain) {
+    const prefix = String(args.chain).toLowerCase();
+    const filtered = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (String(k).toLowerCase().startsWith(prefix)) filtered[k] = v;
+    }
+    return filtered;
+  }
+  return data;
+}
+
+export async function beefyApyBreakdown(opts = {}) {
+  return httpJson(`${base(opts)}/apy/breakdown`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 25_000,
+  });
+}

package/src/data/providers/birdeye-tokens.mjs

@@ -0,0 +1,33 @@
+// Birdeye public token list — Solana token rankings (no API key).
+// Rate-limited public endpoint, light touch expected.
+
+import { httpJson } from "../http.mjs";
+
+export const BIRDEYE_PUBLIC = "https://public-api.birdeye.so";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.BIRDEYE_API_URL || BIRDEYE_PUBLIC).replace(/\/$/, "");
+}
+
+export async function birdeyeHealth(opts = {}) {
+  try {
+    const data = await httpJson(`${base(opts)}/public/tokenlist?sort_by=v24hUSD&sort_type=desc&offset=0&limit=1`, {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 10_000,
+    });
+    return { ok: Array.isArray(data?.data) && data.data.length > 0, provider: "birdeye-tokens" };
+  } catch (e) {
+    return { ok: false, provider: "birdeye-tokens", error: String(e.message || e).slice(0, 120) };
+  }
+}
+
+export async function birdeyeTokenList(args = {}, opts = {}) {
+  const sortBy = String(args.sortBy || "v24hUSD");
+  const sortType = String(args.sortType || "desc");
+  const offset = Math.max(0, Number(args.offset || 0));
+  const limit = Math.min(50, Math.max(1, Number(args.limit || 20)));
+  return httpJson(`${base(opts)}/public/tokenlist?sort_by=${encodeURIComponent(sortBy)}&sort_type=${encodeURIComponent(sortType)}&offset=${offset}&limit=${limit}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}

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

@@ -0,0 +1,145 @@
+// Bisq — non-KYC peer-to-peer BTC market data (markets.bisq.network) — keyless.
+//
+// Why this matters as a distinct price source: every other venue Oracle reads
+// is a KYC'd exchange or an on-chain DEX. Bisq is neither — it is decentralized
+// P2P trading settled by bank transfer and similar rails, so its print carries
+// a non-KYC premium/discount relative to centralized spot. That basis is the
+// signal; the absolute price is not meant to be a reference rate.
+//
+// Verified live:
+//   GET /api/markets                  200  map keyed by pair (bsq_btc, btc_usd…)
+//   GET /api/ticker?market=btc_usd    200  { last, high, low, volume_left, … }
+//   GET /api/trades?market=btc_usd    200  array, newest first
+//
+// LIQUIDITY CAVEAT: Bisq volume is thin and trades are sparse. A single print
+// can move `last` by percent, and the most recent trade may be hours or days
+// old, so every response carries the trade timestamp/age for judgement.
+//
+// Read-only. Bisq trades are executed in the Bisq desktop client, not here.
+
+import { httpJson } from "../http.mjs";
+
+export const BISQ_MARKETS_API = "https://markets.bisq.network";
+
+function baseUrl(opts = {}) {
+  return String(opts.baseUrl || process.env.BISQ_MARKETS_URL || BISQ_MARKETS_API).replace(/\/$/, "");
+}
+
+/** Bisq pairs are lowercase `left_right`, e.g. btc_usd, bsq_btc, xmr_btc. */
+export function bisqMarket(value, label = "market") {
+  const text = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[/\-\s]/g, "_");
+  if (!/^[a-z0-9]{2,12}_[a-z0-9]{2,12}$/.test(text)) {
+    throw new Error(`bisq-markets: ${label} must look like btc_usd (got "${value}")`);
+  }
+  return text;
+}
+
+function get(path, opts = {}) {
+  return httpJson(`${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}
+
+export async function bisqHealth(opts = {}) {
+  try {
+    const markets = await get("/api/markets", opts);
+    const count = markets && typeof markets === "object" ? Object.keys(markets).length : 0;
+    return {
+      ok: count > 0,
+      provider: "bisq-markets",
+      baseUrl: baseUrl(opts),
+      marketCount: count,
+      exec: false,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      provider: "bisq-markets",
+      baseUrl: baseUrl(opts),
+      error: String(error?.message || error),
+      exec: false,
+    };
+  }
+}
+
+/** Tradable pairs. Optional `quote`/`base` filter, e.g. quote: "btc". */
+export async function bisqMarkets(args = {}, opts = {}) {
+  const res = await get("/api/markets", opts);
+  let rows = Object.values(res && typeof res === "object" ? res : {});
+  if (args.base) {
+    const b = String(args.base).trim().toLowerCase();
+    rows = rows.filter((m) => String(m.lsymbol || "").toLowerCase() === b);
+  }
+  if (args.quote) {
+    const q = String(args.quote).trim().toLowerCase();
+    rows = rows.filter((m) => String(m.rsymbol || "").toLowerCase() === q);
+  }
+  return {
+    provider: "bisq-markets",
+    count: rows.length,
+    markets: rows.map((m) => ({
+      pair: m.pair ?? null,
+      name: m.name ?? null,
+      base: m.lsymbol ?? null,
+      baseName: m.lname ?? null,
+      quote: m.rsymbol ?? null,
+      quoteName: m.rname ?? null,
+      baseType: m.ltype ?? null,
+      quoteType: m.rtype ?? null,
+    })),
+  };
+}
+
+/** Ticker for one pair. `buy`/`sell` are frequently null — Bisq offers are sparse. */
+export async function bisqTicker(args = {}, opts = {}) {
+  const market = bisqMarket(args.market || args.pair || "btc_usd", "market");
+  const t = await get(`/api/ticker?market=${encodeURIComponent(market)}`, opts);
+  const row = Array.isArray(t) ? t[0] || {} : t || {};
+  return {
+    provider: "bisq-markets",
+    market,
+    last: row.last == null ? null : Number(row.last),
+    high: row.high == null ? null : Number(row.high),
+    low: row.low == null ? null : Number(row.low),
+    bid: row.buy == null ? null : Number(row.buy),
+    ask: row.sell == null ? null : Number(row.sell),
+    volumeBase: row.volume_left == null ? null : Number(row.volume_left),
+    volumeQuote: row.volume_right == null ? null : Number(row.volume_right),
+    note: "Bisq is thin, non-KYC P2P — treat as a basis signal against centralized spot, not a reference rate",
+    raw: row,
+  };
+}
+
+/** Recent trades, newest first. Reports the age of the latest print. */
+export async function bisqTrades(args = {}, opts = {}) {
+  const market = bisqMarket(args.market || args.pair || "btc_usd", "market");
+  const limit = Math.min(2000, Math.max(1, Number(args.limit || 50)));
+  const params = new URLSearchParams({ market, limit: String(limit) });
+  if (args.timestampFrom) params.set("timestamp_from", String(args.timestampFrom));
+  if (args.timestampTo) params.set("timestamp_to", String(args.timestampTo));
+  const res = await get(`/api/trades?${params}`, opts);
+  const rows = Array.isArray(res) ? res : [];
+  // trade_date is epoch MILLISECONDS on this API.
+  const latestMs = rows.length ? Number(rows[0].trade_date || 0) : null;
+  const volumeBase = rows.reduce((n, r) => n + Number(r.amount || 0), 0);
+  return {
+    provider: "bisq-markets",
+    market,
+    count: rows.length,
+    latestTradeAt: latestMs ? new Date(latestMs).toISOString() : null,
+    latestTradeAgeHours: latestMs ? Math.round(((Date.now() - latestMs) / 3_600_000) * 10) / 10 : null,
+    volumeBase,
+    trades: rows.slice(0, limit).map((r) => ({
+      price: r.price == null ? null : Number(r.price),
+      amount: r.amount == null ? null : Number(r.amount),
+      volume: r.volume == null ? null : Number(r.volume),
+      paymentMethod: r.payment_method ?? null,
+      tradeDate: r.trade_date ?? null,
+      tradeAt: r.trade_date ? new Date(Number(r.trade_date)).toISOString() : null,
+    })),
+  };
+}