@surf-ai/sdk 0.1.5-beta → 1.0.0-alpha.0

package/dist/server/index.cjs

@@ -30,32 +30,58 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/data/client.ts
-var client_exports = {};
-__export(client_exports, {
-  get: () => get,
-  post: () => post
-});
-function env(surfName, legacyName) {
-  return process.env[surfName] || process.env[legacyName];
+// src/core/config.ts
+function trimTrailingSlashes(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+function readSurfApiConfig() {
+  return {
+    baseUrl: trimTrailingSlashes(process.env.SURF_API_BASE_URL || DEFAULT_API_BASE_URL),
+    apiKey: process.env.SURF_API_KEY
+  };
 }
-function resolveConfig() {
-  const proxyBase = env("SURF_SANDBOX_PROXY_BASE", "DATA_PROXY_BASE");
-  if (proxyBase) {
-    return { baseUrl: proxyBase, headers: {} };
+function requireSurfApiConfig() {
+  const config = readSurfApiConfig();
+  if (!config.apiKey) {
+    throw new Error("SURF_API_KEY is required");
   }
-  const gatewayUrl = env("SURF_DEPLOYED_GATEWAY_URL", "GATEWAY_URL");
-  const appToken = env("SURF_DEPLOYED_APP_TOKEN", "APP_TOKEN");
-  if (gatewayUrl && appToken) {
-    return {
-      baseUrl: `${gatewayUrl.replace(/\/$/, "")}/gateway/v1`,
-      headers: { Authorization: `Bearer ${appToken}` }
-    };
+  return { baseUrl: config.baseUrl, apiKey: config.apiKey };
+}
+function readAdminApiKey() {
+  return process.env.SURF_API_KEY;
+}
+var DEFAULT_API_BASE_URL;
+var init_config = __esm({
+  "src/core/config.ts"() {
+    "use strict";
+    DEFAULT_API_BASE_URL = "https://api.ask.surf/gateway/v1";
   }
-  return { baseUrl: DEFAULT_PUBLIC_URL, headers: {} };
+});
+
+// src/core/transport.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function normalizePath(path2) {
-  return String(path2 || "").replace(/^\/+/, "").replace(/^(?:proxy\/)+/, "");
+  return String(path2 || "").replace(/^\/+/, "");
+}
+function buildUrl(path2, params) {
+  const { baseUrl } = requireSurfApiConfig();
+  const url = new URL(`${baseUrl}/${normalizePath(path2)}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value != null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+function buildHeaders(extra) {
+  const { apiKey } = requireSurfApiConfig();
+  const headers = new Headers(extra);
+  headers.set("Authorization", `Bearer ${apiKey}`);
+  return headers;
 }
 async function fetchJson(url, init, retries = 1) {
   for (let attempt = 0; attempt <= retries; attempt++) {
@@ -65,37 +91,52 @@ async function fetchJson(url, init, retries = 1) {
       throw new Error(`API error ${res.status}: ${text2.slice(0, 200)}`);
     }
     const text = await res.text();
-    if (text) return JSON.parse(text);
-    if (attempt < retries) await new Promise((r) => setTimeout(r, 1e3));
+    if (text) {
+      return JSON.parse(text);
+    }
+    if (attempt < retries) {
+      await sleep(1e3);
+    }
   }
   throw new Error(`Empty response from ${url}`);
 }
-async function get(path2, params) {
-  const config = resolveConfig();
-  const cleaned = {};
-  if (params) {
-    for (const [k, v] of Object.entries(params)) {
-      if (v != null) cleaned[k] = String(v);
-    }
-  }
-  const qs = Object.keys(cleaned).length ? "?" + new URLSearchParams(cleaned).toString() : "";
-  return fetchJson(`${config.baseUrl}/${normalizePath(path2)}${qs}`, {
-    headers: config.headers
+async function getJson(path2, params) {
+  return fetchJson(buildUrl(path2, params), {
+    headers: buildHeaders()
   });
 }
-async function post(path2, body) {
-  const config = resolveConfig();
-  return fetchJson(`${config.baseUrl}/${normalizePath(path2)}`, {
+async function postJson(path2, body) {
+  return fetchJson(buildUrl(path2), {
     method: "POST",
-    headers: { ...config.headers, "Content-Type": "application/json" },
+    headers: buildHeaders({
+      "Content-Type": "application/json"
+    }),
     body: body ? JSON.stringify(body) : void 0
   });
 }
-var DEFAULT_PUBLIC_URL;
+var init_transport = __esm({
+  "src/core/transport.ts"() {
+    "use strict";
+    init_config();
+  }
+});
+
+// src/data/client.ts
+var client_exports = {};
+__export(client_exports, {
+  get: () => get,
+  post: () => post
+});
+async function get(path2, params) {
+  return getJson(path2, params);
+}
+async function post(path2, body) {
+  return postJson(path2, body);
+}
 var init_client = __esm({
   "src/data/client.ts"() {
     "use strict";
-    DEFAULT_PUBLIC_URL = "https://api.ask.surf/gateway/v1";
+    init_transport();
   }
 });
 
@@ -112,18 +153,27 @@ var import_express = __toESM(require("express"), 1);
 var import_cors = __toESM(require("cors"), 1);
 var import_fs = __toESM(require("fs"), 1);
 var import_path = __toESM(require("path"), 1);
-var import_http_proxy_middleware = require("http-proxy-middleware");
 var import_croner = require("croner");
+init_config();
+function requireBearerAuth(req, res, next) {
+  const apiKey = readAdminApiKey();
+  if (!apiKey) {
+    return res.status(503).json({ error: "SURF_API_KEY is not configured" });
+  }
+  if (req.headers.authorization !== `Bearer ${apiKey}`) {
+    return res.status(401).json({ error: "Unauthorized" });
+  }
+  next();
+}
 function createServer(options = {}) {
-  const port = options.port || parseInt(process.env.PORT || "3001", 10);
+  const port = options.port ?? (process.env.PORT ? Number.parseInt(process.env.PORT, 10) : void 0);
+  if (!Number.isInteger(port)) {
+    throw new Error("createServer requires a port via options.port or process.env.PORT");
+  }
   const routesDir = options.routesDir || import_path.default.join(process.cwd(), "routes");
   const cronDir = options.cronDir || process.cwd();
-  const enableProxy = options.proxy !== false;
   const app = (0, import_express.default)();
   app.use((0, import_cors.default)());
-  if (enableProxy) {
-    setupProxy(app, port);
-  }
   app.use(import_express.default.json());
   app.get("/api/health", (_req, res) => {
     res.json({ status: "ok" });
@@ -133,12 +183,13 @@ function createServer(options = {}) {
       if (!file.endsWith(".js") && !file.endsWith(".ts")) continue;
       const name = file.replace(/\.(js|ts)$/, "");
       try {
-        const route = require(import_path.default.join(routesDir, file));
-        const handler = route.default || route;
+        const handler = require(import_path.default.join(routesDir, file));
         if (typeof handler === "function") {
           app.use(`/api/${name}`, handler);
           console.log(`Route registered: /api/${name}`);
+          continue;
         }
+        throw new Error(`Route module must export a handler function via module.exports`);
       } catch (err) {
         console.error(`Failed to load route ${file}: ${err.message}`);
       }
@@ -162,55 +213,6 @@ function createServer(options = {}) {
     }
   };
 }
-function env2(surfName, legacyName) {
-  return process.env[surfName] || process.env[legacyName];
-}
-function setupProxy(app, port) {
-  const gatewayUrl = env2("SURF_DEPLOYED_GATEWAY_URL", "GATEWAY_URL");
-  const appToken = env2("SURF_DEPLOYED_APP_TOKEN", "APP_TOKEN");
-  const proxyBase = env2("SURF_SANDBOX_PROXY_BASE", "DATA_PROXY_BASE");
-  const isDeployed = Boolean(gatewayUrl && appToken);
-  const bufferResponse = (0, import_http_proxy_middleware.responseInterceptor)(async (buf) => buf);
-  if (isDeployed) {
-    app.use("/proxy", (0, import_http_proxy_middleware.createProxyMiddleware)({
-      target: gatewayUrl,
-      changeOrigin: true,
-      selfHandleResponse: true,
-      pathRewrite: (p) => "/gateway/v1" + p,
-      headers: {
-        Authorization: `Bearer ${appToken}`,
-        "Accept-Encoding": "identity"
-      },
-      on: { proxyRes: bufferResponse }
-    }));
-    const loopback = `http://127.0.0.1:${port}/proxy`;
-    process.env.SURF_SANDBOX_PROXY_BASE = loopback;
-    process.env.DATA_PROXY_BASE = loopback;
-  } else if (proxyBase) {
-    const target = proxyBase.replace(/\/proxy$/, "");
-    app.use((0, import_http_proxy_middleware.createProxyMiddleware)({
-      target,
-      changeOrigin: true,
-      selfHandleResponse: true,
-      pathFilter: "/proxy",
-      on: {
-        proxyReq: (proxyReq, req) => {
-          console.log(`[proxy] >> ${req.method} ${req.originalUrl}`);
-        },
-        proxyRes: (0, import_http_proxy_middleware.responseInterceptor)(async (buf, proxyRes, req) => {
-          const status = proxyRes.statusCode;
-          const tag = status && status >= 400 ? "ERR" : "OK";
-          console.log(`[proxy] << ${status} ${tag} ${req.method} ${req.originalUrl} bytes=${buf.length}`);
-          return buf;
-        }),
-        error: (err, req, res) => {
-          console.error(`[proxy] !! ${req.method} ${req.originalUrl} error: ${err.message}`);
-          if (!res.headersSent) res.status(502).json({ error: err.message });
-        }
-      }
-    }));
-  }
-}
 var schemaSync = { run: async () => {
 }, watch: () => {
 } };
@@ -314,7 +316,7 @@ function setupSchemaSync(app, schemaDir) {
     }
     console.error("DB schema sync failed after all retries");
   }
-  app.post("/api/__sync-schema", async (_req, res) => {
+  app.post("/api/__sync-schema", requireBearerAuth, async (_req, res) => {
     try {
       await syncWithRetry(2, 1500);
       res.json({ ok: true });
@@ -418,16 +420,7 @@ function setupCron(app, cronDir) {
       console.log(`Cron registered: [${task.id}] ${task.name} (${task.schedule})`);
     }
   }
-  const envFn = (s, l) => process.env[s] || process.env[l];
-  app.use("/api/cron", (req, res, next) => {
-    const appToken = envFn("SURF_DEPLOYED_APP_TOKEN", "APP_TOKEN");
-    if (!appToken) return next();
-    const auth = req.headers.authorization;
-    if (!auth || auth !== `Bearer ${appToken}`) {
-      return res.status(401).json({ error: "Unauthorized" });
-    }
-    next();
-  });
+  app.use("/api/cron", requireBearerAuth);
   app.get("/api/cron", (_req, res) => {
     res.json(cronTasks.map((t) => {
       const state = cronState.get(t.id) || { lastRunAt: null, lastStatus: null, lastError: null };
@@ -537,236 +530,262 @@ init_client();
 // src/data/categories/exchange.ts
 init_client();
 var exchange = {
-  /** Get order book bid/ask levels with computed stats: spread, spread percentage, mid-price, and total bid/ask depth. Use `limit` to control the number of price levels (1–100, default 20). Set `type=swap` to query perpetual contract order books instead of spot. */
+  /** Returns order book bid/ask levels with computed stats. **Included fields:** spread, spread percentage, mid-price, and total bid/ask depth. Use `limit` to control the number of price levels (1–100, default 20). Set `type=swap` to query perpetual contract order books instead of spot. */
   depth: (params) => get("exchange/depth", params),
-  /** Get historical funding rate records for a perpetual contract. Use `from` to set the start time and `limit` to control result count. For longer history, paginate by using the last returned timestamp as the next `from` value. Note: not all exchanges support historical queries via `from`; some only return recent data regardless. For the latest funding rate snapshot, see `/exchange/perp?fields=funding`. */
+  /** Returns historical funding rate records for a perpetual contract. **Pagination:** use `from` to set the start time and `limit` to control result count. For longer history, pass the last returned timestamp as the next `from` value. **Note:** not all exchanges support historical queries via `from`; some only return recent data regardless. For the latest funding rate snapshot, see `/exchange/perp?fields=funding`. */
   funding_history: (params) => get("exchange/funding-history", params),
-  /** Get OHLCV candlestick data with period summary stats (high, low, total volume). Supports 15 intervals from `1m` to `1M`. Use `from` to set the start time and `limit` to control how many candles to return. For longer ranges, paginate by using the last returned candle's timestamp as the next `from` value. Exchange-side limits vary (200–1000 per request). Set `type=swap` to query perpetual contract candles instead of spot. */
+  /** Returns OHLCV candlestick data with period summary stats (high, low, total volume). **Intervals:** 15 options from `1m` to `1M`. **Pagination:** use `from` to set the start time and `limit` to control candle count. For longer ranges, pass the last returned candle's timestamp as the next `from` value. Exchange-side limits vary (200–1000 per request). Set `type=swap` to query perpetual contract candles instead of spot. */
   klines: (params) => get("exchange/klines", params),
-  /** Get historical long/short ratio for a perpetual contract — ratio value, long account percentage, and short account percentage. Use `interval` (`1h`, `4h`, `1d`) for granularity, `from` for start time, and `limit` for result count. For longer history, paginate by using the last returned timestamp as the next `from` value. Note: not all exchanges support historical queries via `from`; some only return recent data regardless. Just pass the base pair (e.g. `pair=BTC/USDT`). For aggregated cross-exchange long/short ratio, see `/market/futures`. */
+  /** Returns historical long/short ratio for a perpetual contract. **Included fields:** ratio value, long account percentage, short account percentage. **Granularity:** `interval` supports `1h`, `4h`, `1d`. **Pagination:** use `from` for start time and `limit` for result count. For longer history, pass the last returned timestamp as the next `from` value. **Note:** not all exchanges support historical queries via `from`; some only return recent data regardless. Just pass the base pair (e.g. `pair=BTC/USDT`). For aggregated cross-exchange long/short ratio, see `/market/futures`. */
   long_short_ratio: (params) => get("exchange/long-short-ratio", params),
-  /** List trading pairs available on an exchange. Filter by `type` (`spot`, `swap`, `future`, `option`) or free-text `search`. Returns pair name, base/quote currencies, market type, active status, and default fee rates. Use the returned `pair` values as the `pair` parameter in other exchange endpoints. */
+  /** Returns trading pairs available on an exchange. **Filters:** `type` (`spot`, `swap`, `future`, `option`) or free-text `search`. **Included fields:** pair name, base/quote currencies, market type, active status, and default fee rates. Use the returned `pair` values as the `pair` parameter in other exchange endpoints. */
   markets: (params) => get("exchange/markets", params),
-  /** Get a combined snapshot of perpetual contract data for a pair. Use `fields` to select which sub-resources to fetch: `funding` (current funding rate, next settlement, mark/index price) and/or `oi` (open interest in contracts and USD). Just pass the base pair (e.g. `pair=BTC/USDT`). The `:USDT` swap suffix is added automatically. */
+  /** Returns a combined snapshot of perpetual contract data for a pair. **Available fields** (via `fields`): - `funding` — current funding rate, next settlement, mark/index price - `oi` — open interest in contracts and USD Just pass the base pair (e.g. `pair=BTC/USDT`). The `:USDT` swap suffix is added automatically. */
   perp: (params) => get("exchange/perp", params),
-  /** Get the real-time ticker for a trading pair — last price, bid/ask, 24h high/low, 24h volume, and 24h price change. Set `type=swap` to query perpetual contract prices instead of spot. For historical price trends, use `/market/price`. */
+  /** Returns the real-time ticker for a trading pair. **Included fields:** last price, bid/ask, 24h high/low, 24h volume, 24h price change. Set `type=swap` to query perpetual contract prices instead of spot. For historical price trends, use `/market/price`. */
   price: (params) => get("exchange/price", params)
 };
 
 // src/data/categories/fund.ts
 init_client();
 var fund = {
-  /** Get a fund's **profile metadata**: X accounts, team members, recent research, and invested project count. This does NOT return the list of investments — use `/fund/portfolio` for that. Lookup by UUID (`id`) or name (`q`). Returns 404 if not found. */
+  /** Returns a fund's **profile metadata**. **Included fields:** X accounts, team members, recent research, invested project count. This does NOT return the list of investments — use `/fund/portfolio` for that. **Lookup:** by UUID (`id`) or name (`q`). Returns 404 if not found. */
   detail: (params) => get("fund/detail", params),
-  /** List investment rounds for a fund's portfolio, sorted by date (newest first). A project may appear multiple times if the fund participated in multiple rounds. Each entry includes project name, logo, date, raise amount, and lead investor status. Lookup by UUID (`id`) or name (`q`). */
+  /** Returns investment rounds for a fund's portfolio, sorted by date (newest first). A project may appear multiple times if the fund participated in multiple rounds. **Included fields:** project name, logo, date, raise amount, lead investor status. **Lookup:** by UUID (`id`) or name (`q`). */
   portfolio: (params) => get("fund/portfolio", params),
-  /** List top-ranked funds by metric. Available metrics: `tier` (lower is better), `portfolio_count` (number of invested projects). */
+  /** Returns top-ranked funds by a specified metric. **Available metrics:** `tier` (lower is better), `portfolio_count` (number of invested projects). */
   ranking: (params) => get("fund/ranking", params)
 };
 
 // src/data/categories/kalshi.ts
 init_client();
 var kalshi = {
-  /** Get Kalshi events with nested markets, optionally filtered by `event_ticker`. Each event includes market count and a list of markets. Data refresh: ~30 minutes */
+  /** Returns Kalshi events with nested markets, optionally filtered by `event_ticker`. Each event includes market count and a list of markets. **Data refresh:** ~30 minutes */
   events: (params) => get("prediction-market/kalshi/events", params),
-  /** Get Kalshi markets, optionally filtered by `market_ticker`. Each market includes price, volume, and status. Data refresh: ~30 minutes */
+  /** Returns Kalshi markets, optionally filtered by `market_ticker`. Each market includes price, volume, and status. **Data refresh:** ~30 minutes */
   markets: (params) => get("prediction-market/kalshi/markets", params),
-  /** Get daily open interest history for a Kalshi market filtered by `time_range`. Data refresh: ~30 minutes */
+  /** Returns daily open interest history for a Kalshi market, filtered by `time_range`. **Data refresh:** ~30 minutes */
   open_interest: (params) => get("prediction-market/kalshi/open-interest", params),
-  /** Get price history for a Kalshi market. Use `interval=1d` for daily OHLC from market reports (~30 min delay), or `interval=latest` for real-time price from trades. Data refresh: ~30 minutes (daily), real-time (latest) */
+  /** Returns price history for a Kalshi market. **Interval options:** - `interval=1d` — daily OHLC from market reports (~30 min delay) - `interval=latest` — real-time price from trades **Data refresh:** ~30 minutes (daily), real-time (latest) */
   prices: (params) => get("prediction-market/kalshi/prices", params),
-  /** Get top-ranked Kalshi markets by last day's `notional_volume_usd` or `open_interest`. Filter by `status`. Data refresh: ~30 minutes */
+  /** Returns top-ranked Kalshi markets by last day's `notional_volume_usd` or `open_interest`. **Filters:** `status`. **Data refresh:** ~30 minutes */
   ranking: (params) => get("prediction-market/kalshi/ranking", params),
-  /** Get individual trade records for a Kalshi market. Filter by `taker_side`, `min_contracts`, and date range. Sort by `timestamp` or `num_contracts`. Data refresh: real-time */
+  /** Returns individual trade records for a Kalshi market. **Filters:** `taker_side`, `min_contracts`, and date range. **Sort:** `timestamp` or `num_contracts`. **Data refresh:** real-time */
   trades: (params) => get("prediction-market/kalshi/trades", params),
-  /** Get daily trading volume history for a Kalshi market filtered by `time_range`. Data refresh: ~30 minutes */
+  /** Returns daily trading volume history for a Kalshi market, filtered by `time_range`. **Data refresh:** ~30 minutes */
   volumes: (params) => get("prediction-market/kalshi/volumes", params)
 };
 
 // src/data/categories/market.ts
 init_client();
 var market = {
-  /** Get daily ETF flow history for US spot ETFs — net flow (USD), token price, and per-ticker breakdown. Sorted by date descending. `symbol`: `BTC` or `ETH`. */
+  /** Returns daily ETF flow history for US spot ETFs. **Included fields:** net flow (USD), token price, per-ticker breakdown. Sorted by date descending. `symbol`: `BTC` or `ETH`. */
   etf: (params) => get("market/etf", params),
-  /** Get Bitcoin Fear & Greed Index history — index value (0-100), classification label, and BTC price at each data point. Sorted newest-first. Use `from`/`to` to filter by date range. */
+  /** Returns Bitcoin Fear & Greed Index history. **Included fields:** index value (0-100), classification label, BTC price at each data point. Sorted newest-first. Use `from`/`to` to filter by date range. */
   fear_greed: (params) => get("market/fear-greed", params),
-  /** Get futures market data across all tracked tokens — open interest, funding rate, long/short ratio, and 24h volume. Sort by `sort_by` (default: volume_24h). */
+  /** Returns futures market data across all tracked tokens. **Included fields:** open interest, funding rate, long/short ratio, 24h volume. Sorted by `volume_24h` by default — use `sort_by` to change. */
   futures: (params) => get("market/futures", params),
-  /** Get OHLC-style aggregated liquidation data for a token on a specific exchange. Filter by `symbol`, `exchange`, and `interval`. Useful for charting liquidation volume over time. */
+  /** Returns OHLC-style aggregated liquidation data for a token on a specific exchange. **Filters:** `symbol`, `exchange`, `interval`. Useful for charting liquidation volume over time. */
   liquidation_chart: (params) => get("market/liquidation/chart", params),
-  /** Get liquidation breakdown by exchange — total, long, and short volumes in USD. Filter by `symbol` and `time_range` (`1h`, `4h`, `12h`, `24h`). */
+  /** Returns liquidation breakdown by exchange. **Included fields:** total, long, and short volumes in USD. **Filters:** `symbol` and `time_range` (`1h`, `4h`, `12h`, `24h`). */
   liquidation_exchange_list: (params) => get("market/liquidation/exchange-list", params),
-  /** Get individual large liquidation orders above a USD threshold (`min_amount`, default 10000). Filter by `exchange` and `symbol`. For aggregate totals and long/short breakdown by exchange, use `/market/liquidation/exchange-list`. For historical liquidation charts, use `/market/liquidation/chart`. */
+  /** Returns individual large liquidation orders above a USD threshold (`min_amount`, default 10000). **Filters:** `exchange` and `symbol`. For aggregate totals and long/short breakdown by exchange, use `/market/liquidation/exchange-list`. For historical liquidation charts, use `/market/liquidation/chart`. */
   liquidation_order: (params) => get("market/liquidation/order", params),
-  /** Get on-chain indicator time-series for BTC or ETH. Metrics: `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, `exchange-flows` (inflow/outflow/netflow/reserve). */
+  /** Returns on-chain indicator time-series for BTC or ETH. **Available metrics:** `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, `exchange-flows` (inflow/outflow/netflow/reserve). */
   onchain_indicator: (params) => get("market/onchain-indicator", params),
-  /** Get options market data — open interest, volume, put/call ratio, and max pain price for a `symbol`. */
+  /** Returns options market data for a `symbol`. **Included fields:** open interest, volume, put/call ratio, max pain price. */
   options: (params) => get("market/options", params),
-  /** Get historical price data points for a token. Use `time_range` for predefined windows (`1d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `max`) or `from`/`to` for a custom date range (Unix timestamp or YYYY-MM-DD). Granularity is automatic: 5-min for 1d, hourly for 7-90d, daily for 180d+. */
+  /** Returns historical price data points for a token over a specified time range. **Time range options:** - Predefined: `1d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `max` - Custom: use `from` / `to` (Unix seconds or `YYYY-MM-DD`) **Granularity** is automatic based on range: - `1d` → 5-minute intervals - `7d`–`90d` → hourly - `180d`+ → daily */
   price: (params) => get("market/price", params),
-  /** Get a technical indicator for a trading pair on a given exchange and interval. Set `from`/`to` for time-series mode, omit for latest value. Use `options` for indicator-specific tuning (e.g. `period:7`, `fast_period:8,slow_period:21,signal_period:5`, `period:10,stddev:1.5`). Indicators: `rsi`, `macd`, `ema`, `sma`, `bbands`, `stoch`, `adx`, `atr`, `cci`, `obv`, `vwap`, `dmi`, `ichimoku`, `supertrend`. */
+  /** Returns a technical indicator for a trading pair on a given exchange and interval. **Modes:** - Set `from`/`to` for time-series - Omit for latest value only **Indicator-specific tuning** via `options` (e.g. `period:7`, `fast_period:8,slow_period:21,signal_period:5`, `period:10,stddev:1.5`). **Available indicators:** `rsi`, `macd`, `ema`, `sma`, `bbands`, `stoch`, `adx`, `atr`, `cci`, `obv`, `vwap`, `dmi`, `ichimoku`, `supertrend`. */
   price_indicator: (params) => get("market/price-indicator", params),
-  /** List tokens ranked by metric. Available metrics: `market_cap`, `top_gainers`, `top_losers`, `volume`. Note: `top_gainers` and `top_losers` rank by 24h price change within the top 250 coins by market cap. For circulating supply, FDV, ATH/ATL, use `/project/detail?fields=token_info`. */
+  /** Returns tokens ranked by a specified metric. **Available metrics:** `market_cap`, `top_gainers`, `top_losers`, `volume`. **Note:** `top_gainers` and `top_losers` rank by 24h price change within the top 250 coins by market cap. For circulating supply, FDV, ATH/ATL, use `/project/detail?fields=token_info`. */
   ranking: (params) => get("market/ranking", params)
 };
 
+// src/data/categories/matching.ts
+init_client();
+var matching = {
+  /** Returns daily volume and open interest comparison for a specific matched market pair. Both `polymarket_condition_id` and `kalshi_market_ticker` are required. **Volume units:** Polymarket = USD, Kalshi = contracts. */
+  market_daily: (params) => get("prediction-market/matching/daily", params),
+  /** Given a Polymarket condition_id or Kalshi market_ticker, find the corresponding match on the other platform. Provide at least one of `polymarket_condition_id` or `kalshi_market_ticker`. When both are provided, results are filtered to pairs matching both (useful for verifying a specific pair). */
+  market_find: (params) => get("prediction-market/matching/find", params),
+  /** Returns one-to-one matched market pairs between Polymarket and Kalshi. Each pair maps a Polymarket condition_id to a Kalshi market_ticker with a confidence score. **Volume units differ:** Polymarket = USD, Kalshi = contracts ($1 binary options). **Data refresh:** seed-driven, updated periodically. */
+  market_pairs: (params) => get("prediction-market/matching/pairs", params)
+};
+
 // src/data/categories/news.ts
 init_client();
 var news = {
   /** Returns the full content of a single news article by its ID (returned as `id` in feed and search results). */
   detail: (params) => get("news/detail", params),
-  /** Browse crypto news from major sources. Filter by `source` (enum), `project`, and time range (`from`/`to`). Sort by `recency` (default) or `trending`. Use the detail endpoint with article `id` for full content. */
+  /** Returns crypto news from major sources. **Filters:** `source` (enum), `project`, and time range (`from`/`to`). **Sort:** `recency` (default) or `trending`. Use the detail endpoint with article `id` for full content. */
   feed: (params) => get("news/feed", params)
 };
 
 // src/data/categories/onchain.ts
 init_client();
 var onchain = {
-  /** List bridge protocols ranked by total USD volume over a time range. */
+  /** Returns bridge protocols ranked by total USD volume over a specified time range. */
   bridge_ranking: (params) => get("onchain/bridge/ranking", params),
-  /** Get the current gas price for an EVM chain via `eth_gasPrice` JSON-RPC. Returns gas price in both wei (raw) and Gwei (human-readable). **Supported chains:** `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`. */
+  /** Returns the current gas price for an EVM chain via `eth_gasPrice` JSON-RPC. **Included fields:** gas price in both wei (raw) and Gwei (human-readable). **Supported chains:** `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`. */
   gas_price: (params) => get("onchain/gas-price", params),
-  /** Execute a structured JSON query on blockchain data. No raw SQL needed — specify source, fields, filters, sort, and pagination. All tables live in the **agent** database. Use `GET /v1/onchain/schema` to discover available tables and their columns. - Source format: `agent.<table_name>` like `agent.ethereum_transactions` or `agent.ethereum_dex_trades` - Max 10,000 rows (default 20), 30s timeout. - **Always filter on block_date** — it is the partition key. Without it, queries scan billions of rows and will timeout. - **Data refresh:** ~24 hours. ## Example ```json { "source": "agent.ethereum_dex_trades", "fields": ["block_time", "project", "token_pair", "amount_usd", "taker"], "filters": [ {"field": "block_date", "op": "gte", "value": "2025-03-01"}, {"field": "project", "op": "eq", "value": "uniswap"}, {"field": "amount_usd", "op": "gte", "value": 100000} ], "sort": [{"field": "amount_usd", "order": "desc"}], "limit": 20 } ``` */
+  /** Executes a structured JSON query on blockchain data. No raw SQL needed — specify source, fields, filters, sort, and pagination. All tables live in the **agent** database. Use `GET /v1/onchain/schema` to discover available tables and their columns. **Key rules:** - **Source format:** `agent.<table_name>` (e.g. `agent.ethereum_transactions`, `agent.ethereum_dex_trades`) - Max 10,000 rows (default 20), 30s timeout - **Always filter on block_date** — it is the partition key. Without it, queries scan billions of rows and will timeout **Data refresh:** ~24 hours. ## Example ```json { "source": "agent.ethereum_dex_trades", "fields": ["block_time", "project", "token_pair", "amount_usd", "taker"], "filters": [ {"field": "block_date", "op": "gte", "value": "2025-03-01"}, {"field": "project", "op": "eq", "value": "uniswap"}, {"field": "amount_usd", "op": "gte", "value": 100000} ], "sort": [{"field": "amount_usd", "order": "desc"}], "limit": 20 } ``` */
   structured_query: (body) => post("onchain/query", body),
-  /** Get table metadata — database, table, column names, types, and comments for all available on-chain databases. */
+  /** Returns table metadata for all available on-chain databases. **Included fields:** database name, table name, column names, types, and comments. */
   schema: () => get("onchain/schema"),
-  /** Execute a raw SQL SELECT query against blockchain data. All tables live in the **agent** database. Use `GET /v1/onchain/schema` to discover available tables and their columns before writing queries. ## Rules - Only SELECT/WITH statements allowed (read-only). - All table references must be database-qualified: `agent.<table_name>`. - Max 10,000 rows (default 1,000), 30s timeout. - **Always filter on block_date or block_number** — partition key, without it queries will timeout. - Avoid `SELECT *` on large tables. Specify only the columns you need. - **Data refresh:** ~24 hours. ## Example ```sql SELECT block_time, token_pair, amount_usd, taker, tx_hash FROM agent.ethereum_dex_trades WHERE block_date >= today() - 7 AND project = 'uniswap' AND amount_usd > 100000 ORDER BY amount_usd DESC LIMIT 20 ``` */
+  /** Executes a raw SQL SELECT query against blockchain data. All tables live in the **agent** database. Use `GET /v1/onchain/schema` to discover available tables and their columns before writing queries. ## Rules - Only SELECT/WITH statements allowed (read-only) - All table references must be database-qualified: `agent.<table_name>` - Max 10,000 rows (default 1,000), 30s timeout - **Always filter on block_date or block_number** — partition key, without it queries will timeout - Avoid `SELECT *` on large tables — specify only the columns you need **Data refresh:** ~24 hours. ## Example ```sql SELECT block_time, token_pair, amount_usd, taker, tx_hash FROM agent.ethereum_dex_trades WHERE block_date >= today() - 7 AND project = 'uniswap' AND amount_usd > 100000 ORDER BY amount_usd DESC LIMIT 20 ``` */
   sql: (body) => post("onchain/sql", body),
-  /** Get transaction details by hash. All numeric fields are hex-encoded — use parseInt(hex, 16) to convert. **Supported chains:** `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`. Returns 404 if the transaction is not found. */
+  /** Returns transaction details by hash. All numeric fields are hex-encoded — use parseInt(hex, 16) to convert. **Supported chains:** `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`. Returns 404 if the transaction is not found. */
   tx: (params) => get("onchain/tx", params),
-  /** List DeFi yield pools ranked by APY or TVL. Returns the latest snapshot. Filter by protocol. */
+  /** Returns DeFi yield pools ranked by APY or TVL. Returns the latest snapshot. Filter by protocol. */
   yield_ranking: (params) => get("onchain/yield/ranking", params)
 };
 
 // src/data/categories/polymarket.ts
 init_client();
 var polymarket = {
-  /** Get trade and redemption activity for a Polymarket wallet. Data refresh: ~30 minutes */
+  /** Returns trade and redemption activity for a Polymarket wallet. **Data refresh:** ~30 minutes */
   activity: (params) => get("prediction-market/polymarket/activity", params),
-  /** Get Polymarket events with nested markets, optionally filtered by `event_slug`. Each event includes aggregated status, volume, and a list of markets with `side_a`/`side_b` outcomes. Data refresh: ~30 minutes */
+  /** Returns Polymarket events with nested markets, optionally filtered by `event_slug`. Each event includes aggregated status, volume, and a list of markets with `side_a`/`side_b` outcomes. **Data refresh:** ~30 minutes */
   events: (params) => get("prediction-market/polymarket/events", params),
-  /** Get Polymarket markets, optionally filtered by `market_slug`. Each market includes `side_a` and `side_b` outcomes. Current prices are available via `/polymarket/prices` using the `condition_id`. Data refresh: ~30 minutes */
+  /** Returns Polymarket markets, optionally filtered by `market_slug`. Each market includes `side_a` and `side_b` outcomes. Current prices are available via `/polymarket/prices` using the `condition_id`. **Data refresh:** ~30 minutes */
   markets: (params) => get("prediction-market/polymarket/markets", params),
-  /** Get daily open interest history for a Polymarket market. Data refresh: ~30 minutes */
+  /** Returns daily open interest history for a Polymarket market. **Data refresh:** ~30 minutes */
   open_interest: (params) => get("prediction-market/polymarket/open-interest", params),
-  /** Get wallet positions on Polymarket markets. Data refresh: ~30 minutes */
+  /** Returns wallet positions on Polymarket markets. **Data refresh:** ~30 minutes */
   positions: (params) => get("prediction-market/polymarket/positions", params),
-  /** Get aggregated price history for a Polymarket market. Use `interval=latest` for the most recent price snapshot. Data refresh: ~30 minutes */
+  /** Returns aggregated price history for a Polymarket market. Use `interval=latest` for the most recent price snapshot. **Data refresh:** ~30 minutes */
   prices: (params) => get("prediction-market/polymarket/prices", params),
-  /** Get top-ranked Polymarket markets by `volume_24h`, `volume_7d`, `open_interest`, or `trade_count`. Filter by `status` and `end_before`. Data refresh: ~30 minutes */
+  /** Returns top-ranked Polymarket markets. **Sort by:** `volume_24h`, `volume_7d`, `open_interest`, or `trade_count`. **Filters:** `status` and `end_before`. **Data refresh:** ~30 minutes */
   ranking: (params) => get("prediction-market/polymarket/ranking", params),
-  /** Get paginated trade records for a Polymarket market or wallet. Filter by `condition_id` (market) or `address` (wallet), plus `outcome_label`, `min_amount`, and date range. At least one of `condition_id` or `address` is required. Sort by `newest`, `oldest`, or `largest`. Data refresh: ~30 minutes */
+  /** Returns paginated trade records for a Polymarket market or wallet. **Filters:** `condition_id` (market) or `address` (wallet), plus `outcome_label`, `min_amount`, and date range. At least one of `condition_id` or `address` is required. **Sort:** `newest`, `oldest`, or `largest`. **Data refresh:** ~30 minutes */
   trades: (params) => get("prediction-market/polymarket/trades", params),
-  /** Get trading volume and trade count history for a Polymarket market. Data refresh: ~30 minutes */
+  /** Returns trading volume and trade count history for a Polymarket market. **Data refresh:** ~30 minutes */
   volumes: (params) => get("prediction-market/polymarket/volumes", params)
 };
 
 // src/data/categories/prediction_market.ts
 init_client();
 var prediction_market = {
-  /** Get daily notional volume and open interest aggregated by category across Kalshi and Polymarket. Filter by `source` or `category`. Data refresh: daily */
+  /** Returns daily notional volume and open interest aggregated by category across Kalshi and Polymarket. **Filters:** `source` or `category`. **Data refresh:** daily */
   category_metrics: (params) => get("prediction-market/category-metrics", params)
 };
 
 // src/data/categories/project.ts
 init_client();
 var project = {
-  /** Get time-series DeFi metrics for a project. Available metrics: `volume`, `fee`, `fees`, `revenue`, `tvl`, `users`. Lookup by UUID (`id`) or name (`q`). Filter by `chain` and date range (`from`/`to`). Returns 404 if the project is not found. **Note:** this endpoint only returns data for DeFi protocol projects (e.g. `aave`, `uniswap`, `lido`, `makerdao`). Use `q` with a DeFi protocol name. */
+  /** Returns time-series DeFi metrics for a project. **Available metrics:** `volume`, `fee`, `fees`, `revenue`, `tvl`, `users`. **Lookup:** by UUID (`id`) or name (`q`). Filter by `chain` and date range (`from`/`to`). Returns 404 if the project is not found. **Note:** this endpoint only returns data for DeFi protocol projects (e.g. `aave`, `uniswap`, `lido`, `makerdao`). Use `q` with a DeFi protocol name. */
   defi_metrics: (params) => get("project/defi/metrics", params),
-  /** Get top DeFi projects ranked by a protocol metric. Available metrics: `tvl`, `revenue`, `fees`, `volume`, `users`. */
+  /** Returns top DeFi projects ranked by a protocol metric. **Available metrics:** `tvl`, `revenue`, `fees`, `volume`, `users`. */
   defi_ranking: (params) => get("project/defi/ranking", params),
-  /** Get multiple project sub-resources in a single request. Use `fields` to select: `overview`, `token_info`, `tokenomics`, `funding`, `team`, `contracts`, `social`, `tge_status`. **Accepts project names directly** via `q` (e.g. `?q=aave`) — no need to call `/search/project` first. Also accepts UUID via `id`. Returns 404 if not found. For DeFi metrics (TVL, fees, revenue, volume, users) and per-chain breakdown, use `/project/defi/metrics`. */
+  /** Returns multiple project sub-resources in a single request. **Available fields** (via `fields`): `overview`, `token_info`, `tokenomics`, `funding`, `team`, `contracts`, `social`, `tge_status`. **Lookup:** accepts project names directly via `q` (e.g. `?q=aave`) — no need to call `/search/project` first. Also accepts UUID via `id`. Returns 404 if not found. For DeFi metrics (TVL, fees, revenue, volume, users) and per-chain breakdown, use `/project/defi/metrics`. */
   detail: (params) => get("project/detail", params)
 };
 
 // src/data/categories/search.ts
 init_client();
 var search = {
-  /** Search and filter airdrop opportunities by keyword, status, reward type, and task type. Returns paginated results with optional task details. */
+  /** Searches and filters airdrop opportunities. **Filters:** keyword, status, reward type, task type. Returns paginated results with optional task details. */
   airdrop: (params) => get("search/airdrop", params),
-  /** Search project events by keyword, optionally filtered by `type`. Valid types: `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, `twitter`. Lookup by UUID (`id`) or name (`q`). Returns 404 if the project is not found. */
+  /** Searches project events by keyword, optionally filtered by `type`. **Valid types:** `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, `twitter`. **Lookup:** by UUID (`id`) or name (`q`). Returns 404 if the project is not found. */
   events: (params) => get("search/events", params),
-  /** Search funds by keyword. Returns matching funds with name, tier, type, logo, and top invested projects. */
+  /** Searches funds by keyword. **Included fields:** name, tier, type, logo, top invested projects. */
   fund: (params) => get("search/fund", params),
-  /** Search Kalshi events by keyword and/or category. Filter by keyword matching event title, subtitle, or market title; or by category. At least one of `q` or `category` is required. Returns events with nested markets. Data refresh: ~30 minutes */
+  /** Searches Kalshi events by keyword and/or category. **Filters:** - Keyword matching event title, subtitle, or market title - Category At least one of `q` or `category` is required. Returns events with nested markets. **Data refresh:** ~30 minutes */
   kalshi: (params) => get("search/kalshi", params),
-  /** Search crypto news articles by keyword. Returns top 10 results ranked by relevance with highlighted matching fragments. */
+  /** Searches crypto news articles by keyword. Returns top 10 results ranked by relevance with highlighted matching fragments. */
   news: (params) => get("search/news", params),
-  /** Search Polymarket events by keyword, tags, and/or category. Filter by keyword matching market question, event title, or description; by comma-separated tag labels; or by Surf-curated category. At least one of `q`, `tags`, or `category` is required. Returns events with nested markets ranked by volume. Data refresh: ~30 minutes */
+  /** Searches Polymarket events by keyword, tags, and/or category. **Filters:** - Keyword matching market question, event title, or description - Comma-separated tag labels - Surf-curated category At least one of `q`, `tags`, or `category` is required. Returns events with nested markets ranked by volume. **Data refresh:** ~30 minutes */
   polymarket: (params) => get("search/polymarket", params),
-  /** Search crypto projects by keyword. Returns matching projects with name, description, chains, and logo. */
+  /** Searches crypto projects by keyword. **Included fields:** name, description, chains, logo. */
   project: (params) => get("search/project", params),
-  /** Search X (Twitter) users by keyword. Returns user profiles with handle, display name, bio, follower count, and avatar. */
+  /** Searches X (Twitter) users by keyword. **Included fields:** handle, display name, bio, follower count, avatar. */
   social_people: (params) => get("search/social/people", params),
-  /** Search X (Twitter) posts by keyword or `from:handle` syntax. Returns posts with author, content, engagement metrics, and timestamp. To load more results, check `meta.has_more`; if true, pass `meta.next_cursor` as the `cursor` query parameter in the next request. */
+  /** Searches X (Twitter) posts by keyword or `from:handle` syntax. **Included fields:** author, content, engagement metrics, timestamp. **Pagination:** check `meta.has_more`; if true, pass `meta.next_cursor` as the `cursor` query parameter in the next request. */
   social_posts: (params) => get("search/social/posts", params),
-  /** Search wallets by ENS name, address label, or address prefix. Returns matching wallet addresses with entity labels. */
+  /** Searches wallets by ENS name, address label, or address prefix. Returns matching wallet addresses with entity labels. */
   wallet: (params) => get("search/wallet", params),
-  /** Search web pages, articles, and content by keyword. Filter by domain with `site` like `coindesk.com`. Returns titles, URLs, and content snippets. */
+  /** Searches web pages, articles, and content by keyword. **Filters:** domain via `site` (e.g. `coindesk.com`). **Included fields:** titles, URLs, content snippets. */
   web: (params) => get("search/web", params)
 };
 
 // src/data/categories/social.ts
 init_client();
 var social = {
-  /** Get a **point-in-time snapshot** of social analytics: sentiment score, follower geo breakdown, and top smart followers. Use `fields` to select: `sentiment`, `follower_geo`, `smart_followers`. Lookup by X account ID (`x_id`) or project name (`q`, e.g. `uniswap`, `solana`). The `q` parameter must be a crypto project name, not a personal Twitter handle. Returns 404 if the project has no linked Twitter account. For sentiment **trends over time**, use `/social/mindshare` instead. */
+  /** Returns a **point-in-time snapshot** of social analytics for a project. **Available fields** (via `fields`): `sentiment`, `follower_geo`, `smart_followers`. **Lookup:** by X account ID (`x_id`) or project name (`q`, e.g. `uniswap`, `solana`). The `q` parameter must be a crypto project name, not a personal Twitter handle. Returns 404 if the project has no linked Twitter account. For sentiment **trends over time**, use `/social/mindshare` instead. */
   detail: (params) => get("social/detail", params),
-  /** Get mindshare (social view count) **time-series trend** for a project, aggregated by `interval`. Use this when the user asks about sentiment **trends**, mindshare **over time**, or social momentum changes. `interval` can be `5m`, `1h`, `1d`, or `7d`. Filter by date range with `from`/`to` (Unix seconds). Lookup by name (`q`). For a **point-in-time snapshot** of social analytics (sentiment score, follower geo, smart followers), use `/social/detail` instead. */
+  /** Returns mindshare (social view count) **time-series trend** for a project, aggregated by `interval`. **Intervals:** `5m`, `1h`, `1d`, `7d`. **Filters:** date range with `from`/`to` (Unix seconds). Lookup by name (`q`). Use this for sentiment **trends**, mindshare **over time**, or social momentum changes. For a **point-in-time snapshot** of social analytics (sentiment score, follower geo, smart followers), use `/social/detail` instead. */
   mindshare: (params) => get("social/mindshare", params),
-  /** Get top crypto projects ranked by mindshare (social view count), sourced directly from Argus real-time data (refreshed every 5 minutes). Filter by `tag` to scope to a category (e.g. `dex`, `l1`, `meme`). Use `time_range` (`24h`, `48h`, `7d`, `30d`) to control the ranking window. Supports `limit`/`offset` pagination. */
+  /** Returns top crypto projects ranked by mindshare (social view count), refreshed every 5 minutes. **Filters:** - `tag` — scope to a category (e.g. `dex`, `l1`, `meme`) - `time_range` — ranking window (`24h`, `48h`, `7d`, `30d`) Supports `limit`/`offset` pagination. */
   ranking: (params) => get("social/ranking", params),
-  /** Get smart follower count time-series for a project, sorted by date descending. Lookup by X account ID (`x_id`) or project name (`q`). The `q` parameter must be a project name (e.g. `uniswap`, `ethereum`), not a personal X handle — use `x_id` for individual accounts. Returns 404 if the project has no linked X account. */
+  /** Returns smart follower count time-series for a project, sorted by date descending. **Lookup:** by X account ID (`x_id`) or project name (`q`). The `q` parameter must be a project name (e.g. `uniswap`, `ethereum`), not a personal X handle — use `x_id` for individual accounts. Returns 404 if the project has no linked X account. */
   smart_followers_history: (params) => get("social/smart-followers/history", params),
-  /** Returns replies/comments on a specific tweet. Lookup by `tweet_id`. */
+  /** Returns replies/comments on a specific tweet. **Lookup:** by `tweet_id`. */
   tweet_replies: (params) => get("social/tweet/replies", params),
-  /** Get X (Twitter) posts by numeric post ID strings. Pass up to 100 comma-separated IDs via the `ids` query parameter. */
+  /** Returns X (Twitter) posts by numeric post ID strings. Pass up to 100 comma-separated IDs via the `ids` query parameter. */
   tweets: (params) => get("social/tweets", params),
-  /** Get an X (Twitter) user profile — display name, follower count, following count, and bio. Lookup by `handle` (without @). */
+  /** Returns an X (Twitter) user profile. **Included fields:** display name, follower count, following count, and bio. **Lookup:** by `handle` (without @). */
   user: (params) => get("social/user", params),
-  /** Returns a list of followers for the specified handle on X (Twitter). Lookup by `handle` (without @). */
+  /** Returns a list of followers for the specified handle on X (Twitter). **Lookup:** by `handle` (without @). */
   user_followers: (params) => get("social/user/followers", params),
-  /** Returns a list of users that the specified handle follows on X (Twitter). Lookup by `handle` (without @). */
+  /** Returns a list of users that the specified handle follows on X (Twitter). **Lookup:** by `handle` (without @). */
   user_following: (params) => get("social/user/following", params),
-  /** Get recent X (Twitter) posts by a specific user, ordered by recency. Lookup by `handle` (without @). Use `filter=original` to exclude retweets. To load more results, check `meta.has_more`; if true, pass `meta.next_cursor` as the `cursor` query parameter in the next request. */
+  /** Returns recent X (Twitter) posts by a specific user, ordered by recency. **Lookup:** by `handle` (without @). Use `filter=original` to exclude retweets. **Pagination:** check `meta.has_more`; if true, pass `meta.next_cursor` as the `cursor` query parameter in the next request. */
   user_posts: (params) => get("social/user/posts", params),
-  /** Returns recent replies by the specified handle on X (Twitter). Lookup by `handle` (without @). */
+  /** Returns recent replies by the specified handle on X (Twitter). **Lookup:** by `handle` (without @). */
   user_replies: (params) => get("social/user/replies", params)
 };
 
 // src/data/categories/token.ts
 init_client();
 var token = {
-  /** Get recent DEX swap events for a token contract address. Covers DEXes like `uniswap`, `sushiswap`, `curve`, and `balancer` on `ethereum` and `base`. Returns trading pair, amounts, USD value, and taker address. Data refresh: ~24 hours · Chain: Ethereum, Base */
+  /** Returns recent DEX swap events for a token contract address. **Covered DEXes:** `uniswap`, `sushiswap`, `curve`, `balancer`. **Included fields:** trading pair, amounts, USD value, taker address. **Data refresh:** ~24 hours · **Chains:** Ethereum, Base */
   dex_trades: (params) => get("token/dex-trades", params),
-  /** Get top token holders for a contract address — wallet address, balance, and percentage. Lookup by `address` and `chain`. Supports EVM chains and Solana. */
+  /** Returns top token holders for a contract address. **Included fields:** wallet address, balance, and percentage. **Lookup:** by `address` and `chain`. Supports EVM chains and Solana. */
   holders: (params) => get("token/holders", params),
-  /** Get token unlock time-series — unlock events with amounts and allocation breakdowns. Lookup by project UUID (`id`) or token `symbol`. Filter by date range with `from`/`to`. Defaults to the current calendar month when omitted. Returns 404 if no token found. */
+  /** Returns token unlock time-series with amounts and allocation breakdowns. **Lookup:** by project UUID (`id`) or token `symbol`. Filter by date range with `from`/`to` — defaults to the current calendar month when omitted. Returns 404 if no token found. */
   tokenomics: (params) => get("token/tokenomics", params),
-  /** Get recent transfer events **for a specific token** (ERC-20/TRC-20 contract). Pass the **token contract address** in `address` — returns every on-chain transfer of that token regardless of sender/receiver. Each record includes sender, receiver, raw amount, and block timestamp. Use this to analyze a token's on-chain activity (e.g. large movements, distribution patterns). Lookup: `address` (token contract) + `chain`. Sort by `asc` or `desc`. Data refresh: ~24 hours · Chain: Ethereum, Base, TRON (Solana uses a different source with no delay) */
+  /** Returns recent transfer events **for a specific token** (ERC-20/TRC-20 contract). Pass the **token contract address** in `address` — returns every on-chain transfer of that token regardless of sender/receiver. **Included fields:** sender, receiver, raw amount, block timestamp. Use this to analyze a token's on-chain activity (e.g. large movements, distribution patterns). **Lookup:** `address` (token contract) + `chain`. Sort by `asc` or `desc`. **Data refresh:** ~24 hours · **Chains:** Ethereum, Base, TRON (Solana uses a different source with no delay) */
   transfers: (params) => get("token/transfers", params)
 };
 
+// src/data/categories/v2.ts
+init_client();
+var v2 = {
+  /** Historical orderbook snapshots for a Kalshi market. Returns yes-side bid/ask levels. Timestamps in milliseconds, prices in cents. Data refresh: ~5 minutes */
+  kalshi_orderbooks: (params) => get("gateway/v2/kalshi/orderbooks", params),
+  /** OHLCV candlestick data for a Polymarket market. Prices normalized to YES side. Data refresh: ~30 minutes */
+  polymarket_candlesticks: (params) => get("gateway/v2/polymarket/candlesticks/{condition_id}", params),
+  /** Cumulative volume time series for a Polymarket token. Data refresh: ~30 minutes */
+  polymarket_volume_timeseries: (params) => get("gateway/v2/polymarket/markets/{token_id}/volume", params),
+  /** Historical orderbook snapshots for a Polymarket token. Returns raw bid/ask depth levels. Timestamps in milliseconds. Data refresh: ~5 minutes */
+  polymarket_orderbooks: (params) => get("gateway/v2/polymarket/orderbooks", params),
+  /** Volume breakdown by outcome (YES/NO) for a Polymarket market. Data refresh: ~30 minutes */
+  polymarket_volume_chart: (params) => get("gateway/v2/polymarket/volume-chart/{condition_id}", params)
+};
+
 // src/data/categories/wallet.ts
 init_client();
 var wallet = {
-  /** Get multiple wallet sub-resources in a single request. Lookup by `address`. Use `fields` to select: `balance`, `tokens`, `labels`, `nft`. Partial failures return available fields with per-field error info. Returns 422 if `fields` is invalid. */
+  /** Returns multiple wallet sub-resources in a single request. **Available fields** (via `fields`): `balance`, `tokens`, `labels`, `nft`. **Lookup:** by `address`. Partial failures return available fields with per-field error info. Returns 422 if `fields` is invalid. */
   detail: (params) => get("wallet/detail", params),
-  /** Get full transaction history for a wallet — swaps, transfers, and contract interactions. Lookup by `address`. Filter by `chain` — supports `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `avalanche`, `fantom`, `base`. */
+  /** Returns full transaction history for a wallet — swaps, transfers, and contract interactions. **Lookup:** by `address`. Filter by `chain` — supports `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `avalanche`, `fantom`, `base`. */
   history: (params) => get("wallet/history", params),
-  /** Get entity labels for multiple wallet addresses. Pass up to 100 comma-separated addresses via the `addresses` query parameter. Returns entity name, type, and labels per address. */
+  /** Returns entity labels for multiple wallet addresses. Pass up to 100 comma-separated addresses via the `addresses` query parameter. **Included fields:** entity name, type, and labels per address. */
   labels_batch: (params) => get("wallet/labels/batch", params),
-  /** Get a time-series of the wallet's total net worth in USD. Returns ~288 data points at 5-minute intervals covering the last 24 hours. Fixed window — no custom time range supported. */
+  /** Returns a time-series of the wallet's total net worth in USD. Returns ~288 data points at 5-minute intervals covering the last 24 hours. Fixed window — no custom time range supported. */
   net_worth: (params) => get("wallet/net-worth", params),
-  /** Get all DeFi protocol positions for a wallet — lending, staking, LP, and farming with token breakdowns and USD values. Lookup by `address`. */
+  /** Returns all DeFi protocol positions for a wallet — lending, staking, LP, and farming with token breakdowns and USD values. **Lookup:** by `address`. */
   protocols: (params) => get("wallet/protocols", params),
-  /** Get recent token transfers **sent or received by a wallet**. Pass the **wallet address** in `address` — returns all ERC-20/SPL token transfers where this wallet is the sender or receiver. Each record includes token contract, counterparty, raw amount, and block timestamp. Use this to audit a wallet's token flow (e.g. inflows, outflows, airdrop receipts). Lookup: `address` (wallet, raw 0x hex or base58 — ENS not supported). Filter by `chain` — supports `ethereum`, `base`, `solana`. Data refresh: ~24 hours · Chain: Ethereum, Base (Solana uses a different source with no delay) */
+  /** Returns recent token transfers **sent or received by a wallet**. Pass the **wallet address** in `address` — returns all ERC-20/SPL token transfers where this wallet is the sender or receiver. **Included fields:** token contract, counterparty, raw amount, block timestamp. Use this to audit a wallet's token flow (e.g. inflows, outflows, airdrop receipts). **Lookup:** `address` (wallet, raw 0x hex or base58 — ENS not supported). Filter by `chain` — supports `ethereum`, `base`, `solana`. **Data refresh:** ~24 hours · **Chains:** Ethereum, Base (Solana uses a different source with no delay) */
   transfers: (params) => get("wallet/transfers", params)
 };
 
 // src/data/categories/web.ts
 init_client();
 var web = {
-  /** Fetch a web page and convert it to clean, LLM-friendly markdown. Use `target_selector` to extract specific page sections and `remove_selector` to strip unwanted elements. Returns 400 if the URL is invalid or unreachable. */
+  /** Fetches a web page and converts it to clean, LLM-friendly markdown. **Options:** - `target_selector` — extract specific page sections - `remove_selector` — strip unwanted elements Returns 400 if the URL is invalid or unreachable. */
   fetch: (params) => get("web/fetch", params)
 };
 
@@ -780,6 +799,7 @@ var dataApi = {
   fund,
   kalshi,
   market,
+  matching,
   news,
   onchain,
   polymarket,
@@ -788,6 +808,7 @@ var dataApi = {
   search,
   social,
   token,
+  v2,
   wallet,
   web
 };