@surf-ai/sdk 1.0.0-alpha.9 → 1.0.2

package/README.md

@@ -16,7 +16,7 @@ SDK 1.0 uses a single direct-auth model.
 | --- | --- | --- |
 | `SURF_API_BASE_URL` | `https://api.asksurf.ai/gateway/v1` | Full Surf API base URL |
 | `SURF_API_KEY` | none | Bearer token used for upstream requests and protected runtime endpoints |
-| `PORT` | none | Express server port when `createServer({ port })` is not provided |
+| `BACKEND_PORT` | none | Express server port when `createServer({ port })` is not provided |
 
 All upstream SDK requests use:
 
@@ -140,4 +140,4 @@ exports.users = pgTable('users', {
 - The runtime no longer mounts `/proxy/*`.
 - The `@surf-ai/sdk/react` subpath has been removed.
 - Route modules must export the handler directly with `module.exports = router`.
-- `createServer()` requires a port from `options.port` or `process.env.PORT`.
+- `createServer()` requires a port from `options.port` or `process.env.BACKEND_PORT`.

package/dist/db/index.d.cts

@@ -32,18 +32,15 @@ declare function watchSchema(schemaPath: string, options?: {
 }): () => void;
 
 /**
- * @surf-ai/sdk/db — Drizzle ORM + Neon PostgreSQL database helpers.
+ * @surf-ai/sdk/db — Database helpers via HTTP proxy to Neon PostgreSQL.
  *
- * Replaces scaffold lib/db.js and db/index.js.
+ * All queries go through the Surf API proxy. There is no locally-instantiated
+ * Drizzle ORM client — `drizzle-orm/pg-core` is used only to declare the
+ * schema; reads and writes go through dbQuery().
  *
  * Usage:
- *   const { db, dbQuery, dbProvision } = require('@surf-ai/sdk/db')
- *
- *   // In a backend route:
- *   const users = await db.select().from(schema.users)
- *
- *   // Raw SQL:
- *   const result = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
+ *   const { dbQuery } = require('@surf-ai/sdk/db')
+ *   const { rows } = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
  */
 
 /**
@@ -58,14 +55,25 @@ declare function dbProvision(): Promise<{
 }>;
 /**
  * Execute a SQL query via db/query.
- * Uses pg-proxy driver under the hood — Drizzle ORM calls this automatically.
  *
- * @param options.arrayMode - When true, rows are returned as positional arrays
- *   instead of objects. Required for Drizzle ORM pg-proxy compatibility.
+ * Returns a pg-style result — use `result.rows` for the row data:
+ *   const { rows } = await dbQuery('SELECT * FROM users')
+ *   const [row] = (await dbQuery('INSERT ... RETURNING *', [...])).rows
+ *
+ * @param options.arrayMode - When true, each row is a positional array instead
+ *   of an object keyed by column name. Default false (object rows).
  */
 declare function dbQuery(sql: string, params?: any[], options?: {
     arrayMode?: boolean;
-}): Promise<any>;
+}): Promise<{
+    rows: any[];
+    rowCount?: number;
+    fields?: Array<{
+        name: string;
+        type: string;
+    }>;
+    truncated?: boolean;
+}>;
 /**
  * List tables in the user's database.
  */

package/dist/db/index.d.ts

@@ -32,18 +32,15 @@ declare function watchSchema(schemaPath: string, options?: {
 }): () => void;
 
 /**
- * @surf-ai/sdk/db — Drizzle ORM + Neon PostgreSQL database helpers.
+ * @surf-ai/sdk/db — Database helpers via HTTP proxy to Neon PostgreSQL.
  *
- * Replaces scaffold lib/db.js and db/index.js.
+ * All queries go through the Surf API proxy. There is no locally-instantiated
+ * Drizzle ORM client — `drizzle-orm/pg-core` is used only to declare the
+ * schema; reads and writes go through dbQuery().
  *
  * Usage:
- *   const { db, dbQuery, dbProvision } = require('@surf-ai/sdk/db')
- *
- *   // In a backend route:
- *   const users = await db.select().from(schema.users)
- *
- *   // Raw SQL:
- *   const result = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
+ *   const { dbQuery } = require('@surf-ai/sdk/db')
+ *   const { rows } = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
  */
 
 /**
@@ -58,14 +55,25 @@ declare function dbProvision(): Promise<{
 }>;
 /**
  * Execute a SQL query via db/query.
- * Uses pg-proxy driver under the hood — Drizzle ORM calls this automatically.
  *
- * @param options.arrayMode - When true, rows are returned as positional arrays
- *   instead of objects. Required for Drizzle ORM pg-proxy compatibility.
+ * Returns a pg-style result — use `result.rows` for the row data:
+ *   const { rows } = await dbQuery('SELECT * FROM users')
+ *   const [row] = (await dbQuery('INSERT ... RETURNING *', [...])).rows
+ *
+ * @param options.arrayMode - When true, each row is a positional array instead
+ *   of an object keyed by column name. Default false (object rows).
  */
 declare function dbQuery(sql: string, params?: any[], options?: {
     arrayMode?: boolean;
-}): Promise<any>;
+}): Promise<{
+    rows: any[];
+    rowCount?: number;
+    fields?: Array<{
+        name: string;
+        type: string;
+    }>;
+    truncated?: boolean;
+}>;
 /**
  * List tables in the user's database.
  */

package/dist/server/index.cjs

@@ -542,7 +542,7 @@ var exchange = {
   long_short_ratio: (params) => get("exchange/long-short-ratio", params),
   /** 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),
-  /** 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. */
+  /** Returns a perpetual futures snapshot for a trading pair: funding rate, open interest, mark/index price. **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),
   /** 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)
@@ -550,11 +550,11 @@ var exchange = {
 
 // src/data/categories/fund.ts
 var fund = {
-  /** 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. */
+  /** Returns a crypto VC fund's full profile: description, jurisdiction, portfolio count, social links, and team members with roles. **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),
   /** 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),
-  /** Returns top-ranked funds by a specified metric. **Available metrics:** `tier` (lower is better), `portfolio_count` (number of invested projects). */
+  /** Returns top crypto VC funds ranked by tier or portfolio count. **Available metrics:** `tier` (lower is better), `portfolio_count` (number of invested projects). */
   ranking: (params) => get("fund/ranking", params)
 };
 
@@ -564,15 +564,15 @@ var kalshi = {
   events: (params) => get("prediction-market/kalshi/events", params),
   /** 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),
-  /** Returns daily open interest history for a Kalshi market, filtered by `time_range`. **Data refresh:** ~30 minutes */
+  /** Daily open interest time series for a Kalshi market. **Data refresh:** ~30 minutes */
   open_interest: (params) => get("prediction-market/kalshi/open-interest", params),
-  /** 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) */
+  /** Historical orderbook snapshots for a Kalshi market. Returns yes-side bid/ask levels. Timestamps in milliseconds, prices in cents. Data refresh: ~5 minutes */
+  orderbooks: (params) => get("prediction-market/kalshi/orderbooks", params),
+  /** Price time series for a Kalshi market with daily or hourly OHLC data, or latest price from recent trades. **Data refresh:** ~30 minutes */
   prices: (params) => get("prediction-market/kalshi/prices", params),
-  /** 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),
   /** 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),
-  /** Returns daily trading volume history for a Kalshi market, filtered by `time_range`. **Data refresh:** ~30 minutes */
+  /** Daily trading volume time series for a Kalshi market. **Data refresh:** ~30 minutes */
   volumes: (params) => get("prediction-market/kalshi/volumes", params)
 };
 
@@ -598,17 +598,15 @@ var market = {
   price: (params) => get("market/price", params),
   /** 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),
-  /** 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`. */
+  /** Returns a token leaderboard sorted by market cap, 24h change, or volume. Each entry includes price, market cap, FDV, supply, ATH/ATL, and 24h range. Supports category filtering (MEME, AI, L1, L2, DEFI, GAMING, etc.). **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. */
+  /** Returns daily volume and open interest comparison for a specific Polymarket <> Kalshi matched pair. Both `polymarket_condition_id` and `kalshi_market_ticker` are required. Use `matching-market-pairs` to discover matched pairs first. **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. */
+  /** Cross-platform prediction market pair matcher — finds the same event listed on both Polymarket and Kalshi, with live price spread data. This is prediction-market only (Polymarket and Kalshi). For crypto exchange markets, use `exchange-markets`. Filter by category, match type, confidence score, or look up a specific market's cross-platform counterpart via `polymarket_condition_id` or `kalshi_market_ticker`. Each pair includes current prices and spread percentage for arbitrage analysis. Sort by `spread_pct` to find the widest spreads. **Data refresh:** ~5 minutes */
   market_pairs: (params) => get("prediction-market/matching/pairs", params)
 };
 
@@ -628,51 +626,59 @@ var onchain = {
   gas_price: (params) => get("onchain/gas-price", params),
   /** 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),
-  /** Returns table metadata for all available on-chain databases. **Included fields:** database name, table name, column names, types, and comments. */
+  /** Returns the ClickHouse schema catalog (tables, columns, types) for on-chain analytics. Use this to discover available tables before writing SQL with `onchain-sql`. **Included fields:** database name, table name, column names, types, and comments. */
   schema: () => get("onchain/schema"),
   /** 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),
   /** 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),
-  /** Returns DeFi yield pools ranked by APY or TVL. Returns the latest snapshot. Filter by protocol. */
+  /** Returns individual DeFi yield pools/vaults ranked by APY or TVL, with APY breakdown (base vs reward) and pool contract address. Unlike `project-defi-ranking` which ranks whole protocols, this ranks specific pools within protocols. Filter by protocol name (e.g. `lido`, `aave`). Only pools with TVL >= $100k are included when sorted by APY. */
   yield_ranking: (params) => get("onchain/yield/ranking", params)
 };
 
 // src/data/categories/polymarket.ts
 var polymarket = {
-  /** Returns trade and redemption activity for a Polymarket wallet. **Data refresh:** ~30 minutes */
-  activity: (params) => get("prediction-market/polymarket/activity", params),
   /** 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),
+  /** Returns a ranked leaderboard of Polymarket traders by realized PnL, volume, or trade count. Sortable by `pnl`, `volume`, or `trade_count`. Each entry includes the wallet address and aggregate trading statistics. **Data refresh:** ~5 minutes. */
+  leaderboard: (params) => get("prediction-market/polymarket/leaderboard", params),
   /** 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),
-  /** Returns daily open interest history for a Polymarket market. **Data refresh:** ~30 minutes */
+  /** Daily open interest time series showing total value locked in a Polymarket market. **Data refresh:** ~30 minutes */
   open_interest: (params) => get("prediction-market/polymarket/open-interest", params),
-  /** Returns wallet positions on Polymarket markets. **Data refresh:** ~30 minutes */
+  /** Historical orderbook snapshots for a Polymarket token. Returns raw bid/ask depth levels. Timestamps in milliseconds. Data refresh: ~5 minutes */
+  orderbooks: (params) => get("prediction-market/polymarket/orderbooks", params),
+  /** Given a specific wallet address, returns that wallet's open positions on Polymarket markets. This is a single-wallet lookup — you must provide the wallet `address`. **Not what you need?** - To discover top/smart wallets across all of Polymarket, use `polymarket-smart-money` (view=positioning for aggregate signals, view=trades for individual whale trades). - To find top traders by PnL or volume, use `polymarket-leaderboard`. **Data refresh:** ~30 minutes */
   positions: (params) => get("prediction-market/polymarket/positions", params),
-  /** Returns aggregated price history for a Polymarket market. Use `interval=latest` for the most recent price snapshot. **Data refresh:** ~30 minutes */
+  /** OHLCV candlestick data for charting a Polymarket market — open, high, low, close, volume per candle. Use this for rendering price charts with candlestick or bar visualizations. For simple price time series (one price per interval), use `prices` instead. Data refresh: ~30 minutes */
+  price_ohlcv: (params) => get("prediction-market/polymarket/price-ohlcv/{condition_id}", params),
+  /** Simple price time series for a Polymarket market — one price point per interval. Use this for tracking price trends over time. For OHLCV candlestick data (open/high/low/close for charting libraries), use `price-ohlcv` instead. **Data refresh:** ~30 minutes */
   prices: (params) => get("prediction-market/polymarket/prices", params),
-  /** 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),
-  /** 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 */
+  /** Smart wallet analytics for Polymarket markets. view=positioning (default): Aggregate smart wallet direction per market — net bullish/bearish signal and conviction. view=trades: Individual $10K+ trades with wallet address, amount, outcome, price, and wallet age. **Data refresh:** ~5 minutes */
+  smart_money: (params) => get("prediction-market/polymarket/smart-money", params),
+  /** Trade and activity history for a Polymarket market or wallet. Filter by market (condition_id), wallet (address), outcome (Yes/No), minimum trade size, and time range. Use type=redemption for splits/merges/redemptions, type=all for everything. **Data refresh:** ~5 minutes */
   trades: (params) => get("prediction-market/polymarket/trades", params),
-  /** Returns trading volume and trade count history for a Polymarket market. **Data refresh:** ~30 minutes */
+  /** Volume split by YES/NO outcome sides per interval (hour/day/week), plus total volume and trade count. Use this to see directional volume bias. For aggregate volume without YES/NO breakdown, use `volumes` instead. Data refresh: ~30 minutes */
+  volume_split: (params) => get("prediction-market/polymarket/volume-split/{condition_id}", params),
+  /** Aggregate trading volume (USD) and trade count as a time series. Use this for volume trend analysis. For YES/NO volume breakdown by outcome side, use `volume-split` instead. **Data refresh:** ~30 minutes */
   volumes: (params) => get("prediction-market/polymarket/volumes", params)
 };
 
 // src/data/categories/prediction_market.ts
 var prediction_market = {
-  /** 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)
+  /** Trends, top markets, momentum distribution, and per-market momentum signals for prediction markets. **Platform-wide totals:** Omit `category` to get aggregated volume/OI/market-count across the entire prediction market (Polymarket + Kalshi combined). Use `platform` to filter to one exchange. This is the recommended way to answer questions like "What is Polymarket's total volume this week?" or "How does Kalshi volume compare to Polymarket?" **Category drill-down:** Provide `category` to scope all data to one category (e.g. crypto, politics). Combines volume/OI time series, top markets by open interest, momentum summary (price/volume signal distribution), and per-market momentum signals (price changes, volume direction, whale flows). **Note on top_markets:** When both `category` and `platform` are omitted, top markets are ranked globally by open interest. Because Polymarket OI is significantly larger than Kalshi OI, the list will skew heavily toward Polymarket. Use `platform` to get per-platform rankings. **Use `search` instead if** you want to browse/search individual markets. **Data refresh:** ~5 minutes. */
+  analytics: (params) => get("prediction-market/analytics", params),
+  /** Returns 30-day Pearson price correlation pairs between Polymarket markets within a category. Correlation data covers the top 100 markets by 7-day volume globally; lower-volume markets may not have correlation data. Filter by `condition_id` to find all markets correlated with a specific market, or set `min_correlation` to control the threshold. The `category` parameter is required. **Data refresh:** ~5 minutes. */
+  correlations: (params) => get("prediction-market/correlations", params)
 };
 
 // src/data/categories/project.ts
 var project = {
-  /** 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. */
+  /** Returns historical time-series for a single DeFi protocol metric (e.g. daily TVL). Each data point has a Unix timestamp and value. **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),
-  /** Returns top DeFi projects ranked by a protocol metric. **Available metrics:** `tvl`, `revenue`, `fees`, `volume`, `users`. */
+  /** Returns a DeFi protocol leaderboard (e.g. Aave, Uniswap, Lido) ranked by TVL, fees, revenue, or users. For individual pool/vault yields, use `onchain-yield-ranking` instead. **Available metrics:** `tvl`, `revenue`, `fees`, `volume`, `users`. */
   defi_ranking: (params) => get("project/defi/ranking", params),
-  /** 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`. */
+  /** Returns a crypto project's profile with selectable sub-resources: overview (description, chains, exchanges), token_info (price, market cap, supply), tokenomics, funding, team, contracts, social, tge_status. **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)
 };
 
@@ -684,12 +690,14 @@ var search = {
   events: (params) => get("search/events", params),
   /** Searches funds by keyword. **Included fields:** name, tier, type, logo, top invested projects. */
   fund: (params) => get("search/fund", params),
-  /** 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 */
+  /** **[DEPRECATED]** Use `GET /v1/search/prediction-market?platform=kalshi` instead. This endpoint will continue to work but will not receive new features. --- 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),
   /** Searches crypto news articles by keyword. Returns top 10 results ranked by relevance with highlighted matching fragments. */
   news: (params) => get("search/news", params),
-  /** 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 */
+  /** **[DEPRECATED]** Use `GET /v1/search/prediction-market?platform=polymarket` instead. This endpoint will continue to work but will not receive new features. --- 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),
+  /** Browse and search prediction markets across all supported platforms. Filter by platform, category, status, keyword search, and smart money direction. Each result includes volume, open interest, trade counts, and smart money signals. Supports single-market lookup via `condition_id` or `market_ticker`. **Data refresh:** ~5 minutes. */
+  prediction_market: (params) => get("search/prediction-market", params),
   /** Searches crypto projects by keyword. **Included fields:** name, description, chains, logo. */
   project: (params) => get("search/project", params),
   /** Searches X (Twitter) users by keyword. **Included fields:** handle, display name, bio, follower count, avatar. */
@@ -704,7 +712,7 @@ var search = {
 
 // src/data/categories/social.ts
 var social = {
-  /** 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. */
+  /** Returns Twitter/X analytics for a crypto project: sentiment score, follower geography, and smart follower breakdown (VCs, KOLs, developers). For individual user profiles use `social-user` instead. **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),
   /** 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),
@@ -716,7 +724,7 @@ var social = {
   tweet_replies: (params) => get("social/tweet/replies", params),
   /** 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),
-  /** Returns an X (Twitter) user profile. **Included fields:** display name, follower count, following count, and bio. **Lookup:** by `handle` (without @). */
+  /** Returns a basic X/Twitter profile (name, bio, avatar, follower/following counts) for any handle. For crypto project social analytics (sentiment, smart followers, geo), use `social-detail` instead. **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 @). */
   user_followers: (params) => get("social/user/followers", params),
@@ -740,25 +748,11 @@ var token = {
   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 = {
-  /** 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. */
+  /** Returns a wallet's cross-chain portfolio with selectable sub-resources (balance, tokens, labels, NFTs). Always includes per-chain USD breakdown across 15+ EVM chains. **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),
-  /** 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`. */
+  /** Returns all on-chain transactions for a wallet, classified by type (send, receive, swap, approve) with native token value. For ERC-20 token transfers with token identity and USD value, use `wallet-transfers` instead. **Lookup:** by `address`. Filter by `chain` — supports `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `avalanche`, `fantom`, `base`. */
   history: (params) => get("wallet/history", params),
   /** 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),
@@ -766,7 +760,7 @@ var wallet = {
   net_worth: (params) => get("wallet/net-worth", params),
   /** 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),
-  /** 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) */
+  /** Returns ERC-20/SPL token transfers with token identity, USD value, and flow direction (in/out). Unlike `wallet-history` which shows all tx types in native value, this focuses on token-level transfer activity. 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, token symbol, amount USD, counterparty, flow direction. Filter by specific token or flow direction (in/out). **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)
 };
 
@@ -795,7 +789,6 @@ var dataApi = {
   search,
   social,
   token,
-  v2,
   wallet,
   web
 };