@surf-ai/sdk 0.1.5-beta → 0.1.6-beta

package/dist/server/index.js

@@ -88,18 +88,14 @@ function setupProxy(app, port) {
     app.use(createProxyMiddleware({
       target,
       changeOrigin: true,
-      selfHandleResponse: true,
       pathFilter: "/proxy",
       on: {
         proxyReq: (proxyReq, req) => {
           console.log(`[proxy] >> ${req.method} ${req.originalUrl}`);
         },
-        proxyRes: 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;
-        }),
+        proxyRes: (proxyRes, req) => {
+          console.log(`[proxy] << ${proxyRes.statusCode} ${req.method} ${req.originalUrl}`);
+        },
         error: (err, req, res) => {
           console.error(`[proxy] !! ${req.method} ${req.originalUrl} error: ${err.message}`);
           if (!res.headersSent) res.status(502).json({ error: err.message });
@@ -430,223 +426,247 @@ function setupCron(app, cronDir) {
 
 // src/data/categories/exchange.ts
 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
 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
 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
 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
+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
 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
 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
 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
 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
 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
 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
 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
 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
+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
 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
 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)
 };
 
@@ -660,6 +680,7 @@ var dataApi = {
   fund,
   kalshi,
   market,
+  matching,
   news,
   onchain,
   polymarket,
@@ -668,6 +689,7 @@ var dataApi = {
   search,
   social,
   token,
+  v2,
   wallet,
   web
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surf-ai/sdk",
-  "version": "0.1.5-beta",
+  "version": "0.1.6-beta",
   "description": "Surf platform SDK — data API client, server runtime, React hooks, and database helpers",
   "type": "module",
   "exports": {