@oracle-agent/oracle 0.1.0

package/src/data/providers/curve.mjs

@@ -0,0 +1,200 @@
+// Curve public REST API + RouterNG single-hop 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";
+
+export const CURVE_API = "https://api.curve.finance/v1";
+const base = (o = {}) => (o.baseUrl || process.env.CURVE_API_URL || CURVE_API).replace(/\/$/, "");
+
+// Official Curve RouterNG deployments from docs.curve.finance router/zaps +
+// CurveRouterNG docs. Bytecode is checked before allowlisting.
+export const CURVE_ROUTER_NG_BY_CHAIN = Object.freeze({
+  1: "0x45312ea0eFf7E09C83CBE249fa1d7598c4C8cd4e",
+  10: "0x0DCDED3545D565bA3B19E683431381007245d983",
+  56: "0xA72C85C258A81761433B4e8da60505Fe3Dd551CC",
+  137: "0x0DCDED3545D565bA3B19E683431381007245d983",
+  988: "0xFF5Cb29241F002fFeD2eAa224e3e996D24A6E8d1",
+  999: "0xd2002373543Ce3527023C75e7518C274A51ce712",
+  4663: "0xFF5Cb29241F002fFeD2eAa224e3e996D24A6E8d1",
+  8453: "0x4f37A9d177470499A2dD084621020b023fcffc1F",
+  42161: "0x2191718CD32d02B8E60BAdFFeA33E4B5DD9A0A0D",
+  43114: "0x0DCDED3545D565bA3B19E683431381007245d983",
+});
+
+const ZERO = "0x0000000000000000000000000000000000000000";
+const ROUTER_IFACE = new Interface([
+  "function get_dy(address[11] route,uint256[5][5] swap_params,uint256 amount,address[5] pools) view returns (uint256)",
+  "function exchange(address[11] route,uint256[5][5] swap_params,uint256 amount,uint256 expected,address[5] pools,address receiver) payable returns (uint256)",
+]);
+const POOL_IFACE = new Interface(["function coins(uint256) view returns (address)"]);
+
+function routerFor(chainId) {
+  const router = CURVE_ROUTER_NG_BY_CHAIN[Number(chainId)];
+  if (!router) throw new Error(`curve-router-ng: unsupported chainId ${chainId}`);
+  return router;
+}
+
+function normalizeAddress(value, label) {
+  if (!isAddress(value)) throw new Error(`${label} must be a valid EVM address`);
+  return getAddress(value);
+}
+
+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 integer(value, label, min, max) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min || n > max) throw new Error(`${label} must be an integer ${min}..${max}`);
+  return n;
+}
+
+function routeArray(tokenIn, pool, tokenOut) {
+  return [tokenIn, pool, tokenOut, ...Array(8).fill(ZERO)];
+}
+
+function swapParams(i, j, poolType, nCoins) {
+  return [[BigInt(i), BigInt(j), 1n, BigInt(poolType), BigInt(nCoins)], ...Array.from({ length: 4 }, () => [0n, 0n, 0n, 0n, 0n])];
+}
+
+function poolsArray(pool) {
+  return [pool, ...Array(4).fill(ZERO)];
+}
+
+async function poolCoins({ chainId, pool, nCoins, rpcCall, opts }) {
+  const coins = [];
+  for (let i = 0; i < nCoins; i++) {
+    const data = POOL_IFACE.encodeFunctionData("coins", [i]);
+    const raw = await rpcCall(chainId, "eth_call", [{ to: pool, data }, opts.blockTag || "latest"], opts);
+    const decoded = POOL_IFACE.decodeFunctionResult("coins", raw);
+    coins.push(getAddress(decoded[0]));
+  }
+  return coins;
+}
+
+function findIndex(coins, token, label) {
+  const target = token.toLowerCase();
+  const idx = coins.findIndex((coin) => coin.toLowerCase() === target);
+  if (idx < 0) throw new Error(`Curve pool does not contain ${label}`);
+  return idx;
+}
+
+export async function curveOpenApi(opts = {}) {
+  return httpJson(`${base(opts)}/openapi.json`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs });
+}
+
+export async function curvePools(args = {}, opts = {}) {
+  const chain = String(args.chain || args.network || "ethereum").toLowerCase();
+  const registry = String(args.registry || "main").toLowerCase();
+  if (!/^[a-z0-9-]+$/.test(chain) || !/^[a-z0-9-]+$/.test(registry)) throw new Error("invalid Curve chain or registry");
+  return httpJson(`${base(opts)}/getPools/${chain}/${registry}`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs ?? 20_000 });
+}
+
+export async function curveHealth(opts = {}) {
+  const data = await curvePools({ chain: "ethereum", registry: "main" }, opts);
+  const count = data?.data?.poolData?.length || 0;
+  return { ok: data?.success === true && count > 0, poolSample: count };
+}
+
+export async function curveQuote(q = {}, opts = {}) {
+  const chainId = Number(q.chainId ?? 8453);
+  const router = routerFor(chainId);
+  const pool = normalizeAddress(q.pool, "curve pool");
+  const tokenIn = normalizeAddress(q.tokenIn, "curve tokenIn");
+  const tokenOut = normalizeAddress(q.tokenOut, "curve tokenOut");
+  const amountIn = positiveAmount(q.amountIn, "curve amountIn");
+  const nCoins = integer(q.nCoins ?? 2, "curve nCoins", 2, 8);
+  const poolType = integer(q.poolType, "curve poolType", 1, 4);
+  const rpcCall = opts.rpcCall || defaultRpcCall;
+  const coins = await poolCoins({ chainId, pool, nCoins, rpcCall, opts });
+  const i = findIndex(coins, tokenIn, "tokenIn");
+  const j = findIndex(coins, tokenOut, "tokenOut");
+  if (i === j) throw new Error("Curve token indexes must differ");
+  const route = routeArray(tokenIn, pool, tokenOut);
+  const params = swapParams(i, j, poolType, nCoins);
+  const pools = poolsArray(pool);
+  const data = ROUTER_IFACE.encodeFunctionData("get_dy", [route, params, amountIn, pools]);
+  const raw = await rpcCall(chainId, "eth_call", [{ to: router, data }, q.blockTag || "latest"], opts);
+  const decoded = ROUTER_IFACE.decodeFunctionResult("get_dy", raw);
+  const amountOut = BigInt(decoded[0]);
+  if (amountOut <= 0n) throw new Error("curve quote returned zero output");
+  return attachAutoSlippage({
+    venue: "curve",
+    router,
+    chainId,
+    pool,
+    tokenIn,
+    tokenOut,
+    amountIn: amountIn.toString(),
+    amountOut: amountOut.toString(),
+    nCoins,
+    poolType,
+    swapType: 1,
+    i,
+    j,
+    route,
+    swapParams: params.map((row) => row.map((x) => x.toString())),
+    pools,
+  }, {
+    chainId,
+    venue: router,
+    amountOut: amountOut.toString(),
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+export async function curvePrepare(q = {}, opts = {}) {
+  const chainId = Number(q.chainId ?? 8453);
+  const router = routerFor(chainId);
+  const sender = normalizeAddress(q.sender || q.from || q.fromAddress || q.receiver, "curve sender");
+  const receiver = normalizeAddress(q.receiver || q.recipient || sender, "curve receiver");
+  const quote = await curveQuote({ ...q, sender }, opts);
+  const route = routeArray(quote.tokenIn, quote.pool, quote.tokenOut);
+  const params = swapParams(quote.i, quote.j, quote.poolType, quote.nCoins);
+  const pools = poolsArray(quote.pool);
+  const data = ROUTER_IFACE.encodeFunctionData("exchange", [
+    route,
+    params,
+    BigInt(quote.amountIn),
+    BigInt(quote.amountOutMinimum),
+    pools,
+    receiver,
+  ]);
+  return {
+    provider: "curve",
+    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,
+    requiresApproval: {
+      token: quote.tokenIn,
+      spender: router,
+      amount: quote.amountIn,
+    },
+    transaction: {
+      chainId,
+      from: sender,
+      to: router,
+      data,
+      value: "0",
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: router, data }),
+    },
+  };
+}

package/src/data/providers/defillama.mjs

@@ -0,0 +1,88 @@
+// DeFiLlama public prices — protocol pack D3 (no API key).
+
+import { httpJson } from "../http.mjs";
+
+export const DEFILLAMA_COINS = "https://coins.llama.fi";
+export const DEFILLAMA_API = "https://api.llama.fi";
+export const DEFILLAMA_YIELDS = "https://yields.llama.fi";
+export const DEFILLAMA_STABLECOINS = "https://stablecoins.llama.fi";
+
+function coinsBase(opts = {}) {
+  return (opts.baseUrl || process.env.DEFILLAMA_COINS_URL || DEFILLAMA_COINS).replace(/\/$/, "");
+}
+
+function apiBase(opts = {}) {
+  return (opts.baseUrl || process.env.DEFILLAMA_API_URL || DEFILLAMA_API).replace(/\/$/, "");
+}
+
+/** @param {string[]} coins e.g. ['coingecko:ethereum','coingecko:bitcoin'] */
+export async function llamaPrices(coins, opts = {}) {
+  if (!Array.isArray(coins) || !coins.length) throw new Error("llamaPrices requires coins[]");
+  const path = coins.map(encodeURIComponent).join(",");
+  return httpJson(`${coinsBase(opts)}/prices/current/${path}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function llamaHealth(opts = {}) {
+  const data = await llamaPrices(["coingecko:ethereum"], opts);
+  const eth = data?.coins?.["coingecko:ethereum"];
+  return { ok: !!eth?.price, ethUsd: eth?.price ?? null };
+}
+
+export async function llamaProtocols(opts = {}) {
+  return httpJson(`${apiBase(opts)}/protocols`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+}
+
+export async function llamaYields(args = {}, opts = {}) {
+  const base = (opts.yieldsBaseUrl || process.env.DEFILLAMA_YIELDS_URL || DEFILLAMA_YIELDS).replace(/\/$/, "");
+  const result = await httpJson(`${base}/pools`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 30_000,
+  });
+  let rows = Array.isArray(result?.data) ? result.data : [];
+  if (args.chain) rows = rows.filter((x) => String(x.chain).toLowerCase() === String(args.chain).toLowerCase());
+  if (args.project) rows = rows.filter((x) => String(x.project).toLowerCase() === String(args.project).toLowerCase());
+  if (args.stablecoin != null) rows = rows.filter((x) => Boolean(x.stablecoin) === Boolean(args.stablecoin));
+  rows.sort((a, b) => Number(b.tvlUsd || 0) - Number(a.tvlUsd || 0));
+  const limit = Math.min(5000, Math.max(1, Number(args.limit || rows.length || 1)));
+  return { ...result, data: rows.slice(0, limit) };
+}
+
+export async function llamaStablecoins(args = {}, opts = {}) {
+  const base = (opts.stablecoinsBaseUrl || process.env.DEFILLAMA_STABLECOINS_URL || DEFILLAMA_STABLECOINS).replace(/\/$/, "");
+  const includePrices = args.includePrices !== false;
+  return httpJson(`${base}/stablecoins?includePrices=${includePrices}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 30_000,
+  });
+}
+
+export async function llamaDexVolumes(args = {}, opts = {}) {
+  const chain = encodeURIComponent(String(args.chain || "Ethereum"));
+  const params = new URLSearchParams({
+    excludeTotalDataChart: String(args.includeChart !== true),
+    excludeTotalDataChartBreakdown: String(args.includeBreakdown !== true),
+    dataType: "dailyVolume",
+  });
+  return httpJson(`${apiBase(opts)}/overview/dexs/${chain}?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 30_000,
+  });
+}
+
+/** Convenience: map symbols via coingecko ids */
+export async function llamaPricesBySymbol(symbols = ["ethereum", "bitcoin", "solana"], opts = {}) {
+  const coins = symbols.map((s) => `coingecko:${String(s).toLowerCase()}`);
+  const data = await llamaPrices(coins, opts);
+  const out = {};
+  for (const s of symbols) {
+    const key = `coingecko:${String(s).toLowerCase()}`;
+    out[s] = data?.coins?.[key] || null;
+  }
+  return out;
+}

package/src/data/providers/dexscreener.mjs

@@ -0,0 +1,43 @@
+// DexScreener public API — token/pair discovery, no key.
+
+import { httpJson } from "../http.mjs";
+
+export const DEXSCREENER_API = "https://api.dexscreener.com";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.DEXSCREENER_API_URL || DEXSCREENER_API).replace(/\/$/, "");
+}
+
+export async function dexscreenerHealth(opts = {}) {
+  // tokenless root sometimes 404 — use a known stablecoin query
+  const data = await httpJson(
+    `${base(opts)}/latest/dex/search?q=USDC`,
+    { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs ?? 12_000 }
+  );
+  const n = data?.pairs?.length || 0;
+  return { ok: n > 0, pairSample: n };
+}
+
+export async function dexscreenerToken(tokenAddress, opts = {}) {
+  if (!tokenAddress) throw new Error("tokenAddress required");
+  return httpJson(`${base(opts)}/latest/dex/tokens/${tokenAddress}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+}
+
+export async function dexscreenerSearch(q, opts = {}) {
+  if (!q) throw new Error("query required");
+  return httpJson(`${base(opts)}/latest/dex/search?q=${encodeURIComponent(q)}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+}
+
+export async function dexscreenerPair(chainId, pairAddress, opts = {}) {
+  if (!chainId || !pairAddress) throw new Error("chainId and pairAddress required");
+  return httpJson(`${base(opts)}/latest/dex/pairs/${chainId}/${pairAddress}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+}

package/src/data/providers/evm-rpc.mjs

@@ -0,0 +1,203 @@
+// EVM JSON-RPC read pack — multi-chain balances/blocks via public or env RPCs.
+// No wallet keys. Uses chain registry rpcEnv + optional public fallbacks.
+
+import { httpJson } from "../http.mjs";
+import { CHAINS, chainById, rpcUrlFor, isSupportedChain } from "../../chains.mjs";
+import { Interface, getAddress } from "ethers";
+
+const ERC20 = new Interface([
+  "function allowance(address owner,address spender) view returns (uint256)",
+  "function balanceOf(address account) view returns (uint256)",
+]);
+
+function normalizeAddress(value, label) {
+  try {
+    return getAddress(value).toLowerCase();
+  } catch {
+    throw new Error(`${label} must be a valid EVM address`);
+  }
+}
+
+function normalizeTxHash(value) {
+  const hash = String(value || "").trim();
+  if (!/^0x[0-9a-fA-F]{64}$/.test(hash)) throw new Error("txHash must be a 32-byte hex transaction hash");
+  return hash.toLowerCase();
+}
+
+function parseHexInt(value) {
+  if (value == null) return null;
+  return Number.parseInt(String(value), 16);
+}
+
+/** Public fallbacks when env RPC unset — rate-limited, fine for health/read. */
+export const PUBLIC_RPC_FALLBACKS = {
+  1: "https://ethereum.publicnode.com",
+  137: "https://polygon-bor-rpc.publicnode.com",
+  42161: "https://arbitrum-one-rpc.publicnode.com",
+  8453: "https://base-rpc.publicnode.com",
+  10: "https://optimism-rpc.publicnode.com",
+  988: "https://rpc.stable.xyz",
+  56: "https://bsc-rpc.publicnode.com",
+  43114: "https://avalanche-c-chain-rpc.publicnode.com",
+  999: "https://rpc.hyperliquid.xyz/evm",
+  2741: "https://api.mainnet.abs.xyz",
+  4663: "https://rpc.mainnet.chain.robinhood.com",
+};
+
+/**
+ * Resolve RPC URL for a chainId: explicit > env (registry) > public fallback.
+ */
+export function resolveRpcUrl(chainId, { rpcUrl, env = process.env } = {}) {
+  if (rpcUrl) return rpcUrl;
+  const fromEnv = rpcUrlFor(chainId, env);
+  if (fromEnv) return fromEnv;
+  return PUBLIC_RPC_FALLBACKS[Number(chainId)] || null;
+}
+
+/**
+ * JSON-RPC call
+ * @param {number} chainId
+ * @param {string} method
+ * @param {any[]} [params]
+ */
+export async function rpcCall(chainId, method, params = [], opts = {}) {
+  const url = resolveRpcUrl(chainId, opts);
+  if (!url) {
+    throw new Error(
+      `No RPC URL for chainId ${chainId} (set env from chain registry rpcEnv or pass rpcUrl)`
+    );
+  }
+  const body = { jsonrpc: "2.0", id: 1, method, params };
+  const res = await httpJson(url, {
+    method: "POST",
+    body,
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  if (res?.error) {
+    const err = new Error(res.error.message || JSON.stringify(res.error));
+    err.code = res.error.code;
+    throw err;
+  }
+  return res.result;
+}
+
+export async function rpcHealth(chainId, opts = {}) {
+  const blockHex = await rpcCall(chainId, "eth_blockNumber", [], opts);
+  const block = parseInt(blockHex, 16);
+  const idHex = await rpcCall(chainId, "eth_chainId", [], opts);
+  const reported = parseInt(idHex, 16);
+  return {
+    ok: Number.isFinite(block) && reported === Number(chainId),
+    chainId: Number(chainId),
+    reportedChainId: reported,
+    blockNumber: block,
+    name: chainById(chainId)?.name || null,
+  };
+}
+
+export async function rpcBlockNumber(chainId, opts = {}) {
+  const hex = await rpcCall(chainId, "eth_blockNumber", [], opts);
+  return parseInt(hex, 16);
+}
+
+export async function rpcChainId(chainId, opts = {}) {
+  const hex = await rpcCall(chainId, "eth_chainId", [], opts);
+  return parseInt(hex, 16);
+}
+
+export async function rpcGetBalance(chainId, address, opts = {}) {
+  if (!address) throw new Error("rpcGetBalance requires address");
+  const hex = await rpcCall(chainId, "eth_getBalance", [address, "latest"], opts);
+  return { chainId: Number(chainId), address, balanceWei: BigInt(hex).toString(), balanceHex: hex };
+}
+
+export async function erc20Allowance(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? opts.chainId ?? 1);
+  const token = normalizeAddress(args.token || args.tokenAddress, "token");
+  const owner = normalizeAddress(args.owner, "owner");
+  const spender = normalizeAddress(args.spender, "spender");
+  const data = ERC20.encodeFunctionData("allowance", [owner, spender]);
+  const result = await rpcCall(chainId, "eth_call", [{ to: token, data }, args.blockTag || "latest"], opts);
+  const decoded = ERC20.decodeFunctionResult("allowance", result);
+  const allowance = BigInt(decoded[0]);
+  return {
+    chainId,
+    token,
+    owner,
+    spender,
+    allowance: allowance.toString(),
+    allowanceHex: `0x${allowance.toString(16)}`,
+    blockTag: args.blockTag || "latest",
+  };
+}
+
+export async function erc20BalanceOf(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? opts.chainId ?? 1);
+  const token = normalizeAddress(args.token || args.tokenAddress, "token");
+  const account = normalizeAddress(args.account || args.owner || args.address, "account");
+  const data = ERC20.encodeFunctionData("balanceOf", [account]);
+  const result = await rpcCall(chainId, "eth_call", [{ to: token, data }, args.blockTag || "latest"], opts);
+  const decoded = ERC20.decodeFunctionResult("balanceOf", result);
+  const balance = BigInt(decoded[0]);
+  return {
+    chainId,
+    token,
+    account,
+    balance: balance.toString(),
+    balanceHex: `0x${balance.toString(16)}`,
+    blockTag: args.blockTag || "latest",
+  };
+}
+
+export async function transactionReceipt(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? opts.chainId ?? 1);
+  const txHash = normalizeTxHash(args.txHash || args.hash || args.transactionHash);
+  const receipt = await rpcCall(chainId, "eth_getTransactionReceipt", [txHash], opts);
+  if (!receipt) {
+    return { ok: false, chainId, txHash, status: "pending", receipt: null, reason: "receipt pending" };
+  }
+  const statusNumber = parseHexInt(receipt.status);
+  let ok = statusNumber === 1;
+  const status = statusNumber === 1 ? "success" : statusNumber === 0 ? "reverted" : "unknown";
+  let reason = ok ? null : status === "reverted" ? "transaction reverted" : "unknown receipt status";
+  const expectedTo = args.expectedTo ? normalizeAddress(args.expectedTo, "expectedTo") : null;
+  const actualTo = receipt.to ? normalizeAddress(receipt.to, "receipt.to") : null;
+  if (expectedTo && actualTo !== expectedTo) {
+    ok = false;
+    reason = `to mismatch: expected ${expectedTo}, got ${actualTo || "null"}`;
+  }
+  return {
+    ok,
+    chainId,
+    txHash,
+    status,
+    reason,
+    statusCode: statusNumber,
+    to: actualTo,
+    from: receipt.from ? normalizeAddress(receipt.from, "receipt.from") : null,
+    blockNumber: parseHexInt(receipt.blockNumber),
+    transactionIndex: parseHexInt(receipt.transactionIndex),
+    logs: Array.isArray(receipt.logs) ? receipt.logs : [],
+    receipt,
+  };
+}
+
+export async function rpcHealthAll(opts = {}) {
+  const ids = opts.chainIds || Object.values(CHAINS).map((c) => c.chainId);
+  const out = {};
+  await Promise.all(
+    ids.map(async (id) => {
+      if (!isSupportedChain(id) && !PUBLIC_RPC_FALLBACKS[id] && !resolveRpcUrl(id, opts)) {
+        out[id] = { ok: false, error: "no rpc configured", chainId: id };
+        return;
+      }
+      try {
+        out[id] = await rpcHealth(id, opts);
+      } catch (e) {
+        out[id] = { ok: false, chainId: id, error: String(e.message || e) };
+      }
+    })
+  );
+  return out;
+}

package/src/data/providers/geckoterminal.mjs

@@ -0,0 +1,34 @@
+// GeckoTerminal public market-data API — no key.
+import { httpJson } from "../http.mjs";
+
+export const GECKOTERMINAL_API = "https://api.geckoterminal.com/api/v2";
+const base = (o={}) => (o.baseUrl || process.env.GECKOTERMINAL_API_URL || GECKOTERMINAL_API).replace(/\/$/, "");
+const enc = (v) => encodeURIComponent(String(v));
+
+export async function geckoNetworks(args = {}, opts = {}) {
+  const page = Math.max(1, Number(args.page || 1));
+  return httpJson(`${base(opts)}/networks?page=${page}`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs });
+}
+export async function geckoPool(args = {}, opts = {}) {
+  if (!args.network || !args.poolAddress) throw new Error("network and poolAddress required");
+  return httpJson(`${base(opts)}/networks/${enc(args.network)}/pools/${enc(args.poolAddress)}`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs });
+}
+export async function geckoToken(args = {}, opts = {}) {
+  if (!args.network || !(args.address || args.tokenAddress)) throw new Error("network and token address required");
+  return httpJson(`${base(opts)}/networks/${enc(args.network)}/tokens/${enc(args.address || args.tokenAddress)}`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs });
+}
+export async function geckoPoolOhlcv(args = {}, opts = {}) {
+  if (!args.network || !args.poolAddress) throw new Error("network and poolAddress required");
+  const timeframe = ["minute","hour","day"].includes(args.timeframe) ? args.timeframe : "hour";
+  const p = new URLSearchParams();
+  p.set("aggregate", String(Math.max(1, Number(args.aggregate || 1))));
+  p.set("limit", String(Math.min(1000, Math.max(1, Number(args.limit || 168)))));
+  if (args.beforeTimestamp != null) p.set("before_timestamp", String(args.beforeTimestamp));
+  if (args.currency) p.set("currency", String(args.currency));
+  if (args.token) p.set("token", String(args.token));
+  return httpJson(`${base(opts)}/networks/${enc(args.network)}/pools/${enc(args.poolAddress)}/ohlcv/${timeframe}?${p}`, { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs });
+}
+export async function geckoHealth(opts = {}) {
+  const data = await geckoNetworks({ page: 1 }, opts);
+  return { ok: Array.isArray(data?.data) && data.data.length > 0, networkSample: data?.data?.length || 0 };
+}