@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/data/providers/bridges.mjs

@@ -0,0 +1,242 @@
+// Bridge quote pack — Across, Hop, Relay (public, no key).
+
+import { httpJson } from "../http.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
+import { QUOTE_PLACEHOLDER_ADDRESS, quoteAddress } from "../quote-placeholder.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
+
+export const ACROSS_API = "https://across.to/api";
+export const HOP_API = "https://api.hop.exchange/v1";
+export const RELAY_API = "https://api.relay.link";
+
+const HOP_CHAIN_IDS = {
+  ethereum: 1,
+  optimism: 10,
+  bsc: 56,
+  polygon: 137,
+  arbitrum: 42161,
+  avalanche: 43114,
+  base: 8453,
+};
+
+// ── Across ──────────────────────────────────────────────────────────────────
+
+export async function acrossHealth(opts = {}) {
+  try {
+    const q = await acrossSuggestedFees(
+      {
+        token: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+        destinationToken: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+        originChainId: 1,
+        destinationChainId: 42161,
+        amount: "1000000000000000",
+      },
+      opts
+    );
+    return { ok: true, estimatedFillTimeSec: q.estimatedFillTimeSec };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+export async function acrossSuggestedFees(q = {}, opts = {}) {
+  const {
+    token,
+    destinationToken = token,
+    originChainId,
+    destinationChainId,
+    amount,
+  } = q;
+  if (!token || originChainId == null || destinationChainId == null || !amount) {
+    throw new Error("acrossSuggestedFees requires token, originChainId, destinationChainId, amount");
+  }
+  const params = new URLSearchParams({
+    token,
+    destinationToken,
+    originChainId: String(originChainId),
+    destinationChainId: String(destinationChainId),
+    amount: String(amount),
+  });
+  const base = (opts.baseUrl || process.env.ACROSS_API_URL || ACROSS_API).replace(/\/$/, "");
+  return httpJson(`${base}/suggested-fees?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}
+
+// ── Hop ─────────────────────────────────────────────────────────────────────
+
+export async function hopHealth(opts = {}) {
+  try {
+    const q = await hopQuote(
+      {
+        amount: "1000000000000000",
+        token: "ETH",
+        fromChain: "ethereum",
+        toChain: "arbitrum",
+        slippage: 0.5,
+      },
+      opts
+    );
+    return { ok: true, estimatedRecieved: q.estimatedRecieved || q.estimatedReceived };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+export async function hopQuote(q = {}, opts = {}) {
+  const {
+    amount,
+    token = "ETH",
+    fromChain = "ethereum",
+    toChain = "arbitrum",
+  } = q;
+  if (!amount) throw new Error("hopQuote requires amount");
+  const legacyCap = q.slippage == null ? undefined : Math.round(Number(q.slippage) * 100);
+  const selected = resolveAutoSlippage({
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    crossChain: fromChain !== toChain,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps ?? legacyCap,
+  });
+  if (!selected.executable) {
+    throw new Error(`hop: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
+  }
+  const params = new URLSearchParams({
+    amount: String(amount),
+    token,
+    fromChain,
+    toChain,
+    // Hop expresses slippage as percentage points: 0.5 = 50 bps.
+    slippage: String(selected.selectedBps / 100),
+  });
+  const base = (opts.baseUrl || process.env.HOP_API_URL || HOP_API).replace(/\/$/, "");
+  const result = await httpJson(`${base}/quote?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+  const amountOut = result?.estimatedRecieved || result?.estimatedReceived;
+  if (!amountOut) return { ...result, autoSlippagePolicy: selected };
+  return attachAutoSlippage(result, {
+    chainId: Number(q.originChainId || q.chainId || HOP_CHAIN_IDS[fromChain] || 0),
+    venue: result?.tx?.to || "hop",
+    amountOut,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    crossChain: fromChain !== toChain,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps ?? legacyCap,
+  });
+}
+
+// ── Relay ───────────────────────────────────────────────────────────────────
+
+export async function relayHealth(opts = {}) {
+  try {
+    const q = await relayQuote(
+      {
+        user: QUOTE_PLACEHOLDER_ADDRESS,
+        originChainId: 1,
+        destinationChainId: 8453,
+        originCurrency: "0x0000000000000000000000000000000000000000",
+        destinationCurrency: "0x0000000000000000000000000000000000000000",
+        amount: "1000000000000000",
+        tradeType: "EXACT_INPUT",
+      },
+      opts
+    );
+    return { ok: true, hasSteps: Array.isArray(q.steps), stepCount: q.steps?.length || 0 };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+export async function relayQuote(q = {}, opts = {}) {
+  const {
+    user = QUOTE_PLACEHOLDER_ADDRESS,
+    originChainId,
+    destinationChainId,
+    originCurrency = "0x0000000000000000000000000000000000000000",
+    destinationCurrency = "0x0000000000000000000000000000000000000000",
+    amount,
+    tradeType = "EXACT_INPUT",
+  } = q;
+  if (originChainId == null || destinationChainId == null || !amount) {
+    throw new Error("relayQuote requires originChainId, destinationChainId, amount");
+  }
+  const selected = resolveAutoSlippage({
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    crossChain: Number(originChainId) !== Number(destinationChainId),
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  if (!selected.executable) {
+    throw new Error(`relay: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
+  }
+  const base = (opts.baseUrl || process.env.RELAY_API_URL || RELAY_API).replace(/\/$/, "");
+  const result = await httpJson(`${base}/quote`, {
+    method: "POST",
+    body: {
+      user,
+      originChainId: Number(originChainId),
+      destinationChainId: Number(destinationChainId),
+      originCurrency,
+      destinationCurrency,
+      amount: String(amount),
+      tradeType,
+      // Relay expects an integer-string in basis points ("50" = 0.50%).
+      slippageTolerance: String(selected.selectedBps),
+    },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  const amountOut = result?.details?.currencyOut?.amount;
+  if (!amountOut || !/^\d+$/.test(String(amountOut))) {
+    return { ...result, autoSlippagePolicy: selected };
+  }
+  return attachAutoSlippage(result, {
+    chainId: Number(originChainId),
+    venue: result?.steps?.[0]?.items?.[0]?.data?.to || "relay",
+    amountOut,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    crossChain: Number(originChainId) !== Number(destinationChainId),
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+export async function relayPrepare(q = {}, opts = {}) {
+  const quote = await relayQuote(q, opts);
+  const chainId = Number(q.originChainId);
+  const items = (quote.steps || []).flatMap((step) =>
+    (step.items || []).filter((item) => item?.data?.to && item?.data?.data).map((item) => ({ stepId: step.id, ...item.data }))
+  );
+  if (!items.length) throw new Error("relay: quote returned no executable transaction items");
+  const venue = String(quote?.autoSlippage?.venue || "").toLowerCase();
+  if (items.some((tx) => String(tx.to).toLowerCase() !== venue)) {
+    throw new Error("relay: route includes a separate approval/transaction that is not yet safely bound");
+  }
+  const transactions = items.map((tx) => ({
+    chainId,
+    from: tx.from || q.user,
+    to: tx.to,
+    data: tx.data,
+    value: tx.value ?? "0x0",
+    ...(tx.gasLimit != null || tx.gas != null ? { gasLimit: tx.gasLimit ?? tx.gas } : {}),
+    slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
+  }));
+  return stampPrepared({
+    provider: "relay",
+    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,
+    transactions,
+  }, { provider: "relay", kind: "relay-tx" });
+}

package/src/data/providers/bungee.mjs

@@ -0,0 +1,29 @@
+// Bungee/Socket — bridge aggregator with different inventory than LI.FI.
+// https://docs.bungee.exchange — public REST API.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+export const BUNGEE_API = "https://api.socket.tech/v2";
+
+export async function bungeeQuote({ fromChainId, toChainId, fromToken, toToken, fromAmount, userAddress } = {}) {
+  if (!fromChainId || !toChainId || !fromToken || !toToken || !fromAmount || !userAddress) {
+    return { error: "bungee quote requires fromChainId, toChainId, fromToken, toToken, fromAmount, userAddress" };
+  }
+  try {
+    const params = new URLSearchParams({ fromChainId: String(fromChainId), toChainId: String(toChainId), fromTokenAddress: fromToken, toTokenAddress: toToken, fromAmount: String(fromAmount), userAddress, sort: "output", singleTxOnly: "false" });
+    const data = await httpJson(`${BUNGEE_API}/quote?${params}`);
+    return { amountOut: data?.result?.toAmount, feeUsd: data?.result?.totalGasFeesInUsd, route: data?.result?.route, estimatedTime: data?.result?.serviceTime ? `${data.result.serviceTime}s` : "unknown" };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function bungeeHealth() {
+  try {
+    const data = await httpJson(`${BUNGEE_API}/supported/chains`);
+    return { ok: true, chainCount: data?.result?.length ?? 0 };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/celestia-da.mjs

@@ -0,0 +1,38 @@
+// Celestia DA — blob stats and transaction data via Celenium (no API key).
+
+import { httpJson } from "../http.mjs";
+
+export const CELENIUM_API = "https://api.celenium.io";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.CELENIUM_API_URL || CELENIUM_API).replace(/\/$/, "");
+}
+
+export async function celestiaHealth(opts = {}) {
+  try {
+    const data = await httpJson(`${base(opts)}/v1/stats`, {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 10_000,
+    });
+    return { ok: data && data.blobs_count != null, provider: "celestia-da" };
+  } catch (e) {
+    return { ok: false, provider: "celestia-da", error: String(e.message || e).slice(0, 120) };
+  }
+}
+
+export async function celestiaStats(opts = {}) {
+  return httpJson(`${base(opts)}/v1/stats`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}
+
+export async function celestiaBlockStats(args = {}, opts = {}) {
+  const height = Number(args.height);
+  if (height && (!Number.isFinite(height) || height < 1)) throw new Error("celestia-da: height must be positive");
+  const path = height ? `/v1/block/${height}` : "/v1/block";
+  return httpJson(`${base(opts)}${path}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}

package/src/data/providers/changenow.mjs

@@ -0,0 +1,135 @@
+// ChangeNOW swap provider.
+//
+// ChangeNOW is a centralized, non-custodial instant swap service that does
+// not require account registration for basic swaps. Different risk model
+// from DEX routes: funds are sent to a ChangeNOW deposit address and the
+// swapped asset is returned to the user's withdrawal address.
+//
+// Public API: https://api.changenow.io/v2
+// Docs: https://documenter.getpostman.com/view/8180765/SVfTPBxP
+//
+// This module is read/prepare only. It quotes routes and provides deposit
+// instructions. The user sends funds themselves; Oracle never holds or moves
+// funds. No API key required for public endpoints.
+//
+// Never signs, never broadcasts, never holds keys.
+
+import { httpJson } from "../http.mjs";
+
+export const CHANGENOW_API = "https://api.changenow.io/v2";
+
+const KNOWN_CURRENCIES_CACHE = new Map();
+let CURRENCIES_LAST_FETCH = 0;
+const CURRENCY_TTL_MS = 600_000; // 10 minutes
+
+/**
+ * List available currencies from ChangeNOW.
+ * Cached for 10 minutes to avoid rate-limiting on repeated queries.
+ */
+export async function changenowCurrencies({ active = true } = {}) {
+  const now = Date.now();
+  if (KNOWN_CURRENCIES_CACHE.size && now - CURRENCIES_LAST_FETCH < CURRENCY_TTL_MS) {
+    return [...KNOWN_CURRENCIES_CACHE.values()];
+  }
+
+  try {
+    const data = await httpJson(`${CHANGENOW_API}/exchange/currencies?active=${active ? "true" : "false"}`);
+    KNOWN_CURRENCIES_CACHE.clear();
+    for (const c of data ?? []) {
+      KNOWN_CURRENCIES_CACHE.set(String(c.ticker).toLowerCase(), c);
+    }
+    CURRENCIES_LAST_FETCH = now;
+    return data ?? [];
+  } catch (e) {
+    if (KNOWN_CURRENCIES_CACHE.size) return [...KNOWN_CURRENCIES_CACHE.values()];
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+/**
+ * Get the minimum exchangeable amount for a pair.
+ */
+export async function changenowMinAmount(fromTicker, toTicker) {
+  if (!fromTicker || !toTicker) return { error: "changenow minAmount requires fromTicker and toTicker" };
+  try {
+    const data = await httpJson(
+      `${CHANGENOW_API}/exchange/min-amount/${encodeURIComponent(fromTicker)}_${encodeURIComponent(toTicker)}`,
+    );
+    return { minAmount: data?.minAmount ?? "0" };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+/**
+ * Get an estimated exchange amount for a pair.
+ */
+export async function changenowEstimate(fromTicker, toTicker, fromAmount, { flow = "standard" } = {}) {
+  if (!fromTicker || !toTicker || !fromAmount) {
+    return { error: "changenow estimate requires fromTicker, toTicker, fromAmount" };
+  }
+  try {
+    const params = new URLSearchParams({
+      fromCurrency: String(fromTicker).toLowerCase(),
+      toCurrency: String(toTicker).toLowerCase(),
+      fromAmount: String(fromAmount),
+      flow,
+    });
+    const data = await httpJson(`${CHANGENOW_API}/exchange/estimated-amount?${params}`);
+    return {
+      fromAmount: data?.fromAmount,
+      toAmount: data?.toAmount,
+      rate: data?.rate,
+      flow: data?.flow ?? flow,
+    };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+/**
+ * Full quote: use estimate if fromAmount is provided, otherwise minAmount.
+ */
+export async function changenowQuote({ fromTicker, toTicker, fromAmount, flow } = {}) {
+  if (!fromTicker || !toTicker) {
+    return { error: "changenow quote requires fromTicker and toTicker" };
+  }
+
+  const min = await changenowMinAmount(fromTicker, toTicker);
+  if (min.error) return min;
+
+  const amount = fromAmount ?? min.minAmount;
+  const est = await changenowEstimate(fromTicker, toTicker, amount, { flow });
+  if (est.error) return est;
+
+  const currencies = await changenowCurrencies();
+  const fromInfo = currencies.find(c => String(c?.ticker).toLowerCase() === String(fromTicker).toLowerCase());
+  const toInfo = currencies.find(c => String(c?.ticker).toLowerCase() === String(toTicker).toLowerCase());
+
+  return {
+    provider: "changenow",
+    fromTicker,
+    toTicker,
+    fromAmount: amount,
+    toAmount: est.toAmount,
+    estimatedRate: est.rate,
+    minAmount: min.minAmount,
+    flow: est.flow,
+    networkFee: fromInfo?.networkFee ?? null,
+    kycRequired: fromInfo?.kycRequired ?? toInfo?.kycRequired ?? false,
+    riskDisclosure: "ChangeNOW is a centralized swap service. Funds are sent to a ChangeNOW deposit address. Not self-custodial during the swap window.",
+  };
+}
+
+/**
+ * ChangeNOW health check.
+ */
+export async function changenowHealth() {
+  try {
+    const c = await changenowCurrencies();
+    if (c?.error) return { ok: false, error: c.error };
+    return { ok: true, currencyCount: Array.isArray(c) ? c.length : 0 };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/compound.mjs

@@ -0,0 +1,32 @@
+// Compound — OG lending protocol ($2B+ TVL across chains).
+// https://docs.compound.finance — public API.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+const COMPOUND_API = "https://api.compound.finance/api/v2";
+
+export async function compoundMarkets() {
+  try {
+    const data = await httpJson(`${COMPOUND_API}/ctoken`);
+    return (data?.cToken || []).map(m => ({
+      symbol: m?.symbol,
+      underlying: m?.underlying_symbol,
+      supplyApy: m?.supply_rate?.value ? `${(Number(m.supply_rate.value) * 100).toFixed(2)}%` : null,
+      borrowApy: m?.borrow_rate?.value ? `${(Number(m.borrow_rate.value) * 100).toFixed(2)}%` : null,
+      totalSupply: m?.total_supply?.value,
+      totalBorrow: m?.total_borrows?.value,
+      collateralFactor: m?.collateral_factor?.value ? `${(Number(m.collateral_factor.value) * 100).toFixed(0)}%` : null,
+    }));
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function compoundHealth() {
+  try {
+    return { ok: true, note: "Compound v2 — Ethereum mainnet lending" };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/connext.mjs

@@ -0,0 +1,28 @@
+// Connext — canonical cross-chain bridge (xcall).
+// https://docs.connext.network — public REST API.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+export const CONNEXT_API = "https://api.connext.network";
+
+export async function connextQuote({ originDomain, destinationDomain, originToken, destinationToken, amount } = {}) {
+  if (!originDomain || !destinationDomain || !originToken || !destinationToken || !amount) {
+    return { error: "connext quote requires originDomain, destinationDomain, originToken, destinationToken, amount" };
+  }
+  try {
+    const body = { originDomain: String(originDomain), destinationDomain: String(destinationDomain), originToken, destinationToken, amount: String(amount) };
+    const data = await httpJson(`${CONNEXT_API}/estimate`, { method: "POST", body: JSON.stringify(body), headers: { "content-type": "application/json" } });
+    return { amountOut: data?.amountOut, fee: data?.fee, estimatedTime: data?.estimatedTransferTime };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function connextHealth() {
+  try {
+    return { ok: true, note: "Connext Amarok — canonical bridge across 20+ chains" };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/convex.mjs

@@ -0,0 +1,30 @@
+// Convex Finance — Curve liquidity booster + yield optimizer.
+// https://docs.convexfinance.com — public API.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+const CONVEX_API = "https://api.convexfinance.com/api";
+
+export async function convexPools() {
+  try {
+    const data = await httpJson(`${CONVEX_API}/pools`);
+    return (data || []).map(p => ({
+      name: p?.curvePool?.name || p?.name,
+      curveApy: p?.curvePool?.apy ? `${(Number(p.curvePool.apy) * 100).toFixed(2)}%` : null,
+      convexApy: p?.apy ? `${(Number(p.apy) * 100).toFixed(2)}%` : null,
+      tvl: p?.tvl,
+      boosted: p?.boosted || false,
+    }));
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function convexHealth() {
+  try {
+    return { ok: true, note: "Convex — CRV/CVX yield optimizer on Ethereum" };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/cow-protocol.mjs

@@ -0,0 +1,110 @@
+// CoW Protocol public Orderbook API — intent/solver-based DEX reads, no key.
+//
+// Read-only. This module never posts an order: CoW order creation is a signed
+// EIP-712 intent, which belongs on the prepare/exec plane (see cowswap.mjs),
+// not here.
+//
+// Endpoint reality, probed live 2026-08-06:
+//   GET /api/v1/version                      -> 200 (cheap liveness probe)
+//   GET /api/v1/account/{owner}/orders       -> 200 (owner-scoped order book)
+//   GET /api/v1/trades?owner=0x..            -> 200 (owner or orderUid REQUIRED;
+//                                               the unfiltered form returns
+//                                               InvalidTradeFilter)
+//   GET /api/v1/auction                      -> 403 at the CloudFront edge for
+//                                               non-browser clients on EVERY
+//                                               network. Kept as a real call
+//                                               that surfaces the upstream
+//                                               refusal rather than a fake.
+
+import { httpJson } from "../http.mjs";
+
+export const COW_API = "https://api.cow.fi";
+
+/** CoW network path segments keyed by chain id (verified: all return 200 on /version). */
+export const COW_NETWORKS = Object.freeze({
+  1: "mainnet",
+  100: "xdai",
+  42161: "arbitrum_one",
+  8453: "base",
+  11155111: "sepolia",
+});
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.COW_API_URL || COW_API).replace(/\/$/, "");
+}
+
+function network(args = {}) {
+  if (args.network) return String(args.network);
+  const chainId = Number(args.chainId ?? 1);
+  const net = COW_NETWORKS[chainId];
+  if (!net) {
+    throw new Error(`cow-protocol: unsupported chainId ${chainId} (have: ${Object.keys(COW_NETWORKS).join(", ")})`);
+  }
+  return net;
+}
+
+function url(args, path, opts) {
+  return `${base(opts)}/${network(args)}/api/v1${path}`;
+}
+
+function address(value, label) {
+  const text = String(value || "").trim();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(text)) throw new Error(`cow-protocol: ${label} must be an EVM address`);
+  return text;
+}
+
+function limitOf(args, fallback = 10) {
+  return Math.min(1000, Math.max(1, Number(args.limit ?? fallback)));
+}
+
+/**
+ * Current batch auction (orders + native prices the solvers compete over).
+ *
+ * NOTE: the CoW CDN answers 403 to non-browser clients, so this throws with the
+ * upstream status. That is the honest result — the alternative would be to
+ * advertise data we cannot actually fetch.
+ */
+export async function cowAuction(args = {}, opts = {}) {
+  return httpJson(url(args, "/auction", opts), {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+}
+
+/** Orders for one owner. CoW has no global open-order feed; owner is required. */
+export async function cowOpenOrders(args = {}, opts = {}) {
+  const owner = address(args.owner || args.address || args.user, "owner");
+  const params = new URLSearchParams({ limit: String(limitOf(args)) });
+  if (args.offset != null) params.set("offset", String(Math.max(0, Number(args.offset))));
+  const orders = await httpJson(`${url(args, `/account/${owner}/orders`, opts)}?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  const rows = Array.isArray(orders) ? orders : [];
+  const open = args.openOnly === false
+    ? rows
+    : rows.filter((o) => String(o?.status || "").toLowerCase() === "open");
+  return { owner, count: open.length, total: rows.length, orders: open };
+}
+
+/** Settled trades. The API demands exactly one of owner or orderUid. */
+export async function cowRecentTrades(args = {}, opts = {}) {
+  const params = new URLSearchParams();
+  if (args.orderUid) params.set("orderUid", String(args.orderUid));
+  else params.set("owner", address(args.owner || args.address || args.user, "owner"));
+  const trades = await httpJson(`${url(args, "/trades", opts)}?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  const rows = Array.isArray(trades) ? trades : [];
+  return { count: rows.length, trades: rows.slice(0, limitOf(args)) };
+}
+
+export async function cowProtocolHealth(opts = {}) {
+  const version = await httpJson(`${base(opts)}/mainnet/api/v1/version`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  const text = typeof version === "string" ? version : JSON.stringify(version ?? "");
+  return { ok: text.trim().length > 0, provider: "cow-protocol", version: text.trim() || null };
+}