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

package/dist/server/index.d.cts

@@ -1,10 +1,9 @@
 import express from 'express';
 
 /**
- * Express server runtime — replaces scaffold server.js + routes/proxy.js.
+ * Express server runtime — replaces scaffold server.js.
  *
  * Handles:
- *   - /proxy/* passthrough (env-aware: sandbox → OutboundProxy, deployed → hermod)
  *   - Auto-loading routes from routes/*.js → /api/{name}
  *   - Cron job system from cron.json
  *   - DB schema sync on startup
@@ -12,18 +11,16 @@ import express from 'express';
  */
 
 interface ServerOptions {
-    /** Port to listen on (default: PORT env, fallback 3001) */
+    /** Port to listen on. Falls back to the PORT env var when omitted. */
     port?: number;
     /** Directory containing route files (default: ./routes) */
     routesDir?: string;
     /** Directory containing cron.json (default: .) */
     cronDir?: string;
-    /** Enable /proxy/* passthrough (default: true) */
-    proxy?: boolean;
 }
 declare function createServer(options?: ServerOptions): {
     app: express.Express;
-    port: number;
+    port: number | undefined;
     start(): Promise<void>;
 };
 
@@ -184,7 +181,7 @@ interface ExchangeLongShortRatioParams {
     from?: string;
     /** Max number of records. For longer history, paginate using the last returned timestamp as the next from value. — @default '50' */
     limit?: number;
-    /** Exchange identifier — @default 'binance' */
+    /** Exchange identifier — @default 'bitget' */
     exchange?: 'binance' | 'okx' | 'bybit' | 'bitget';
 }
 interface ExchangeMarketsItem {
@@ -1271,6 +1268,130 @@ interface KalshiVolumesParams {
     /** Predefined time range: `7d`, `30d`, `90d`, `180d`, or `1y` — @default '30d' */
     time_range?: '7d' | '30d' | '90d' | '180d' | '1y';
 }
+interface MatchingMarketDailyItem {
+    /** Kalshi open interest (contracts) */
+    kalshi_oi_contracts: number;
+    /** Kalshi daily volume (contracts) */
+    kalshi_volume_contracts: number;
+    /** Polymarket open interest (USD) */
+    polymarket_oi_usd: number;
+    /** Polymarket daily volume (USD) */
+    polymarket_volume_usd: number;
+    /** Unix timestamp (midnight UTC) */
+    timestamp: number;
+}
+interface MatchingMarketDailyParams {
+    /** Polymarket condition ID */
+    polymarket_condition_id: string;
+    /** Kalshi market ticker */
+    kalshi_market_ticker: string;
+    /** Time range — @default '30d' */
+    time_range?: '1d' | '7d' | '30d' | '90d' | '180d' | '1y' | 'all';
+    /** Maximum rows — @default '200' */
+    limit?: number;
+    /** Pagination offset — @default '0' */
+    offset?: number;
+}
+interface MatchingMarketFindItem {
+    /** Market category */
+    category: string;
+    /** Match confidence score (75-100) */
+    confidence: number;
+    kalshi: MatchingMarketFindItemKalshi;
+    /** Match type: exact or related */
+    match_type: string;
+    polymarket: MatchingMarketFindItemPolymarket;
+}
+interface MatchingMarketFindItemKalshi {
+    /** Kalshi event ticker */
+    event_ticker: string;
+    /** Kalshi market ticker */
+    market_ticker: string;
+    /** Open interest in contracts */
+    open_interest: number;
+    /** Market status */
+    status: string;
+    /** Market title */
+    title: string;
+    /** Total volume in contracts */
+    volume_contracts: number;
+}
+interface MatchingMarketFindItemPolymarket {
+    /** Polymarket condition identifier */
+    condition_id: string;
+    /** Event slug identifier */
+    event_slug: string;
+    /** Whether the market is currently active */
+    is_active: boolean;
+    /** Market question text */
+    question: string;
+    /** Total trading volume (USD) */
+    volume_usd: number;
+}
+interface MatchingMarketFindParams {
+    /** Polymarket condition ID to find match for */
+    polymarket_condition_id?: string;
+    /** Kalshi market ticker to find match for */
+    kalshi_market_ticker?: string;
+    /** Maximum rows to return — @default '20' */
+    limit?: number;
+    /** Pagination offset — @default '0' */
+    offset?: number;
+}
+interface MatchingMarketPairsItem {
+    /** Market category */
+    category: string;
+    /** Match confidence score (75-100) */
+    confidence: number;
+    kalshi: MatchingMarketPairsItemKalshi;
+    /** Match type: exact or related */
+    match_type: string;
+    polymarket: MatchingMarketPairsItemPolymarket;
+}
+interface MatchingMarketPairsItemKalshi {
+    /** Kalshi event ticker */
+    event_ticker: string;
+    /** Kalshi market ticker */
+    market_ticker: string;
+    /** Open interest in contracts */
+    open_interest: number;
+    /** Market status */
+    status: string;
+    /** Market title */
+    title: string;
+    /** Total volume in contracts */
+    volume_contracts: number;
+}
+interface MatchingMarketPairsItemPolymarket {
+    /** Polymarket condition identifier */
+    condition_id: string;
+    /** Event slug identifier */
+    event_slug: string;
+    /** Whether the market is currently active */
+    is_active: boolean;
+    /** Market question text */
+    question: string;
+    /** Total trading volume (USD) */
+    volume_usd: number;
+}
+interface MatchingMarketPairsParams {
+    /** Filter by category */
+    category?: 'crypto' | 'culture' | 'economics' | 'financials' | 'politics' | 'stem' | 'sports';
+    /** Filter by match type */
+    match_type?: 'exact' | 'related';
+    /** Only return pairs where both markets are currently active — @default 'False' */
+    active_only?: boolean;
+    /** Minimum confidence score (0-100) — @default '0' */
+    min_confidence?: number;
+    /** Sort field — @default 'confidence' */
+    sort_by?: 'confidence' | 'polymarket_volume' | 'kalshi_volume';
+    /** Sort order — @default 'desc' */
+    order?: 'asc' | 'desc';
+    /** Maximum rows to return — @default '20' */
+    limit?: number;
+    /** Pagination offset — @default '0' */
+    offset?: number;
+}
 interface PolymarketActivityItem {
     /** Market condition identifier */
     condition_id: string;
@@ -3270,19 +3391,74 @@ interface WebFetchParams {
     /** Request timeout in milliseconds — @default '30000' */
     timeout?: number;
 }
+interface V2KalshiOrderbooksItem {
+}
+interface V2KalshiOrderbooksParams {
+    /** Kalshi market ticker */
+    ticker: string;
+    /** Start time in Unix milliseconds. 0 means 7 days ago. */
+    start_time?: number;
+    /** End time in Unix milliseconds. 0 means current time. */
+    end_time?: number;
+    /** Maximum number of snapshots to return — @default '100' */
+    limit?: number;
+    /** Base64 cursor for pagination */
+    pagination_key?: string;
+}
+interface V2PolymarketCandlesticksItem {
+}
+interface V2PolymarketCandlesticksParams {
+    /** Start time (Unix seconds). 0 means no lower bound. */
+    start_time?: number;
+    /** End time (Unix seconds). 0 means current time. */
+    end_time?: number;
+    /** Candle interval in minutes: 1=1min, 60=1hour, 1440=1day — @default '60' */
+    interval?: number;
+}
+interface V2PolymarketVolumeTimeseriesItem {
+}
+interface V2PolymarketVolumeTimeseriesParams {
+    /** Time granularity for aggregation — @default 'day' */
+    granularity?: 'day' | 'week' | 'month' | 'year' | 'all';
+    /** Start time (Unix seconds). 0 means no lower bound. */
+    start_time?: number;
+    /** End time (Unix seconds). 0 means current time. */
+    end_time?: number;
+}
+interface V2PolymarketOrderbooksItem {
+}
+interface V2PolymarketOrderbooksParams {
+    /** Token identifier */
+    token_id: string;
+    /** Start time in Unix milliseconds. 0 means 7 days ago. */
+    start_time?: number;
+    /** End time in Unix milliseconds. 0 means current time. */
+    end_time?: number;
+    /** Maximum number of snapshots to return — @default '100' */
+    limit?: number;
+    /** Base64 cursor for pagination */
+    pagination_key?: string;
+}
+interface V2PolymarketVolumeChartItem {
+}
+interface V2PolymarketVolumeChartParams {
+    /** Time granularity for volume aggregation — @default 'hour' */
+    granularity?: 'hour' | 'day' | 'week';
+    /** Start time (Unix seconds). 0 means no lower bound. */
+    start_time?: number;
+    /** End time (Unix seconds). 0 means current time. */
+    end_time?: number;
+}
 
 /**
- * Environment-aware data API client.
+ * 1.0 data API client.
  *
- * Reads env vars to determine routing (prefixed vars take priority):
- *   - SURF_SANDBOX_PROXY_BASE → sandbox (OutboundProxy handles auth)
- *   - SURF_DEPLOYED_GATEWAY_URL + SURF_DEPLOYED_APP_TOKEN → deployed (hermod with Bearer)
- *   - Neither → public (api.ask.surf, caller provides own auth)
+ * Reads:
+ *   - SURF_API_BASE_URL (default: https://api.asksurf.ai/gateway/v1)
+ *   - SURF_API_KEY      (required)
  *
- * Backward-compatible aliases:
- *   DATA_PROXY_BASE → SURF_SANDBOX_PROXY_BASE
- *   GATEWAY_URL     → SURF_DEPLOYED_GATEWAY_URL
- *   APP_TOKEN       → SURF_DEPLOYED_APP_TOKEN
+ * All requests are sent directly to the configured API base URL using
+ * Authorization: Bearer <SURF_API_KEY>.
  */
 /** Low-level GET — escape hatch for endpoints not yet in the SDK. */
 declare function get<T = any>(path: string, params?: Record<string, any>): Promise<T>;
@@ -3330,6 +3506,11 @@ declare const dataApi: {
         price_indicator: (params: MarketPriceIndicatorParams) => Promise<ApiResponse<MarketPriceIndicatorItem>>;
         ranking: (params?: MarketRankingParams) => Promise<ApiResponse<MarketRankingItem>>;
     };
+    matching: {
+        market_daily: (params: MatchingMarketDailyParams) => Promise<ApiResponse<MatchingMarketDailyItem>>;
+        market_find: (params?: MatchingMarketFindParams) => Promise<ApiResponse<MatchingMarketFindItem>>;
+        market_pairs: (params?: MatchingMarketPairsParams) => Promise<ApiResponse<MatchingMarketPairsItem>>;
+    };
     news: {
         detail: (params: NewsDetailParams) => Promise<ApiObjectResponse<NewsDetailData>>;
         feed: (params?: NewsFeedParams) => Promise<ApiResponse<NewsFeedItem>>;
@@ -3394,6 +3575,13 @@ declare const dataApi: {
         tokenomics: (params?: TokenTokenomicsParams) => Promise<ApiResponse<TokenTokenomicsItem>>;
         transfers: (params: TokenTransfersParams) => Promise<ApiResponse<TokenTransfersItem>>;
     };
+    v2: {
+        kalshi_orderbooks: (params: V2KalshiOrderbooksParams) => Promise<ApiResponse<V2KalshiOrderbooksItem>>;
+        polymarket_candlesticks: (params?: V2PolymarketCandlesticksParams) => Promise<ApiResponse<V2PolymarketCandlesticksItem>>;
+        polymarket_volume_timeseries: (params?: V2PolymarketVolumeTimeseriesParams) => Promise<ApiResponse<V2PolymarketVolumeTimeseriesItem>>;
+        polymarket_orderbooks: (params: V2PolymarketOrderbooksParams) => Promise<ApiResponse<V2PolymarketOrderbooksItem>>;
+        polymarket_volume_chart: (params?: V2PolymarketVolumeChartParams) => Promise<ApiResponse<V2PolymarketVolumeChartItem>>;
+    };
     wallet: {
         detail: (params: WalletDetailParams) => Promise<ApiObjectResponse<WalletDetailData>>;
         history: (params: WalletHistoryParams) => Promise<ApiResponse<WalletHistoryItem>>;

package/dist/server/index.d.ts

@@ -1,10 +1,9 @@
 import express from 'express';
 
 /**
- * Express server runtime — replaces scaffold server.js + routes/proxy.js.
+ * Express server runtime — replaces scaffold server.js.
  *
  * Handles:
- *   - /proxy/* passthrough (env-aware: sandbox → OutboundProxy, deployed → hermod)
  *   - Auto-loading routes from routes/*.js → /api/{name}
  *   - Cron job system from cron.json
  *   - DB schema sync on startup
@@ -12,18 +11,16 @@ import express from 'express';
  */
 
 interface ServerOptions {
-    /** Port to listen on (default: PORT env, fallback 3001) */
+    /** Port to listen on. Falls back to the PORT env var when omitted. */
     port?: number;
     /** Directory containing route files (default: ./routes) */
     routesDir?: string;
     /** Directory containing cron.json (default: .) */
     cronDir?: string;
-    /** Enable /proxy/* passthrough (default: true) */
-    proxy?: boolean;
 }
 declare function createServer(options?: ServerOptions): {
     app: express.Express;
-    port: number;
+    port: number | undefined;
     start(): Promise<void>;
 };
 
@@ -184,7 +181,7 @@ interface ExchangeLongShortRatioParams {
     from?: string;
     /** Max number of records. For longer history, paginate using the last returned timestamp as the next from value. — @default '50' */
     limit?: number;
-    /** Exchange identifier — @default 'binance' */
+    /** Exchange identifier — @default 'bitget' */
     exchange?: 'binance' | 'okx' | 'bybit' | 'bitget';
 }
 interface ExchangeMarketsItem {
@@ -1271,6 +1268,130 @@ interface KalshiVolumesParams {
     /** Predefined time range: `7d`, `30d`, `90d`, `180d`, or `1y` — @default '30d' */
     time_range?: '7d' | '30d' | '90d' | '180d' | '1y';
 }
+interface MatchingMarketDailyItem {
+    /** Kalshi open interest (contracts) */
+    kalshi_oi_contracts: number;
+    /** Kalshi daily volume (contracts) */
+    kalshi_volume_contracts: number;
+    /** Polymarket open interest (USD) */
+    polymarket_oi_usd: number;
+    /** Polymarket daily volume (USD) */
+    polymarket_volume_usd: number;
+    /** Unix timestamp (midnight UTC) */
+    timestamp: number;
+}
+interface MatchingMarketDailyParams {
+    /** Polymarket condition ID */
+    polymarket_condition_id: string;
+    /** Kalshi market ticker */
+    kalshi_market_ticker: string;
+    /** Time range — @default '30d' */
+    time_range?: '1d' | '7d' | '30d' | '90d' | '180d' | '1y' | 'all';
+    /** Maximum rows — @default '200' */
+    limit?: number;
+    /** Pagination offset — @default '0' */
+    offset?: number;
+}
+interface MatchingMarketFindItem {
+    /** Market category */
+    category: string;
+    /** Match confidence score (75-100) */
+    confidence: number;
+    kalshi: MatchingMarketFindItemKalshi;
+    /** Match type: exact or related */
+    match_type: string;
+    polymarket: MatchingMarketFindItemPolymarket;
+}
+interface MatchingMarketFindItemKalshi {
+    /** Kalshi event ticker */
+    event_ticker: string;
+    /** Kalshi market ticker */
+    market_ticker: string;
+    /** Open interest in contracts */
+    open_interest: number;
+    /** Market status */
+    status: string;
+    /** Market title */
+    title: string;
+    /** Total volume in contracts */
+    volume_contracts: number;
+}
+interface MatchingMarketFindItemPolymarket {
+    /** Polymarket condition identifier */
+    condition_id: string;
+    /** Event slug identifier */
+    event_slug: string;
+    /** Whether the market is currently active */
+    is_active: boolean;
+    /** Market question text */
+    question: string;
+    /** Total trading volume (USD) */
+    volume_usd: number;
+}
+interface MatchingMarketFindParams {
+    /** Polymarket condition ID to find match for */
+    polymarket_condition_id?: string;
+    /** Kalshi market ticker to find match for */
+    kalshi_market_ticker?: string;
+    /** Maximum rows to return — @default '20' */
+    limit?: number;
+    /** Pagination offset — @default '0' */
+    offset?: number;
+}
+interface MatchingMarketPairsItem {
+    /** Market category */
+    category: string;
+    /** Match confidence score (75-100) */
+    confidence: number;
+    kalshi: MatchingMarketPairsItemKalshi;
+    /** Match type: exact or related */
+    match_type: string;
+    polymarket: MatchingMarketPairsItemPolymarket;
+}
+interface MatchingMarketPairsItemKalshi {
+    /** Kalshi event ticker */
+    event_ticker: string;
+    /** Kalshi market ticker */
+    market_ticker: string;
+    /** Open interest in contracts */
+    open_interest: number;
+    /** Market status */
+    status: string;
+    /** Market title */
+    title: string;
+    /** Total volume in contracts */
+    volume_contracts: number;
+}
+interface MatchingMarketPairsItemPolymarket {
+    /** Polymarket condition identifier */
+    condition_id: string;
+    /** Event slug identifier */
+    event_slug: string;
+    /** Whether the market is currently active */
+    is_active: boolean;
+    /** Market question text */
+    question: string;
+    /** Total trading volume (USD) */
+    volume_usd: number;
+}
+interface MatchingMarketPairsParams {
+    /** Filter by category */
+    category?: 'crypto' | 'culture' | 'economics' | 'financials' | 'politics' | 'stem' | 'sports';
+    /** Filter by match type */
+    match_type?: 'exact' | 'related';
+    /** Only return pairs where both markets are currently active — @default 'False' */
+    active_only?: boolean;
+    /** Minimum confidence score (0-100) — @default '0' */
+    min_confidence?: number;
+    /** Sort field — @default 'confidence' */
+    sort_by?: 'confidence' | 'polymarket_volume' | 'kalshi_volume';
+    /** Sort order — @default 'desc' */
+    order?: 'asc' | 'desc';
+    /** Maximum rows to return — @default '20' */
+    limit?: number;
+    /** Pagination offset — @default '0' */
+    offset?: number;
+}
 interface PolymarketActivityItem {
     /** Market condition identifier */
     condition_id: string;
@@ -3270,19 +3391,74 @@ interface WebFetchParams {
     /** Request timeout in milliseconds — @default '30000' */
     timeout?: number;
 }
+interface V2KalshiOrderbooksItem {
+}
+interface V2KalshiOrderbooksParams {
+    /** Kalshi market ticker */
+    ticker: string;
+    /** Start time in Unix milliseconds. 0 means 7 days ago. */
+    start_time?: number;
+    /** End time in Unix milliseconds. 0 means current time. */
+    end_time?: number;
+    /** Maximum number of snapshots to return — @default '100' */
+    limit?: number;
+    /** Base64 cursor for pagination */
+    pagination_key?: string;
+}
+interface V2PolymarketCandlesticksItem {
+}
+interface V2PolymarketCandlesticksParams {
+    /** Start time (Unix seconds). 0 means no lower bound. */
+    start_time?: number;
+    /** End time (Unix seconds). 0 means current time. */
+    end_time?: number;
+    /** Candle interval in minutes: 1=1min, 60=1hour, 1440=1day — @default '60' */
+    interval?: number;
+}
+interface V2PolymarketVolumeTimeseriesItem {
+}
+interface V2PolymarketVolumeTimeseriesParams {
+    /** Time granularity for aggregation — @default 'day' */
+    granularity?: 'day' | 'week' | 'month' | 'year' | 'all';
+    /** Start time (Unix seconds). 0 means no lower bound. */
+    start_time?: number;
+    /** End time (Unix seconds). 0 means current time. */
+    end_time?: number;
+}
+interface V2PolymarketOrderbooksItem {
+}
+interface V2PolymarketOrderbooksParams {
+    /** Token identifier */
+    token_id: string;
+    /** Start time in Unix milliseconds. 0 means 7 days ago. */
+    start_time?: number;
+    /** End time in Unix milliseconds. 0 means current time. */
+    end_time?: number;
+    /** Maximum number of snapshots to return — @default '100' */
+    limit?: number;
+    /** Base64 cursor for pagination */
+    pagination_key?: string;
+}
+interface V2PolymarketVolumeChartItem {
+}
+interface V2PolymarketVolumeChartParams {
+    /** Time granularity for volume aggregation — @default 'hour' */
+    granularity?: 'hour' | 'day' | 'week';
+    /** Start time (Unix seconds). 0 means no lower bound. */
+    start_time?: number;
+    /** End time (Unix seconds). 0 means current time. */
+    end_time?: number;
+}
 
 /**
- * Environment-aware data API client.
+ * 1.0 data API client.
  *
- * Reads env vars to determine routing (prefixed vars take priority):
- *   - SURF_SANDBOX_PROXY_BASE → sandbox (OutboundProxy handles auth)
- *   - SURF_DEPLOYED_GATEWAY_URL + SURF_DEPLOYED_APP_TOKEN → deployed (hermod with Bearer)
- *   - Neither → public (api.ask.surf, caller provides own auth)
+ * Reads:
+ *   - SURF_API_BASE_URL (default: https://api.asksurf.ai/gateway/v1)
+ *   - SURF_API_KEY      (required)
  *
- * Backward-compatible aliases:
- *   DATA_PROXY_BASE → SURF_SANDBOX_PROXY_BASE
- *   GATEWAY_URL     → SURF_DEPLOYED_GATEWAY_URL
- *   APP_TOKEN       → SURF_DEPLOYED_APP_TOKEN
+ * All requests are sent directly to the configured API base URL using
+ * Authorization: Bearer <SURF_API_KEY>.
  */
 /** Low-level GET — escape hatch for endpoints not yet in the SDK. */
 declare function get<T = any>(path: string, params?: Record<string, any>): Promise<T>;
@@ -3330,6 +3506,11 @@ declare const dataApi: {
         price_indicator: (params: MarketPriceIndicatorParams) => Promise<ApiResponse<MarketPriceIndicatorItem>>;
         ranking: (params?: MarketRankingParams) => Promise<ApiResponse<MarketRankingItem>>;
     };
+    matching: {
+        market_daily: (params: MatchingMarketDailyParams) => Promise<ApiResponse<MatchingMarketDailyItem>>;
+        market_find: (params?: MatchingMarketFindParams) => Promise<ApiResponse<MatchingMarketFindItem>>;
+        market_pairs: (params?: MatchingMarketPairsParams) => Promise<ApiResponse<MatchingMarketPairsItem>>;
+    };
     news: {
         detail: (params: NewsDetailParams) => Promise<ApiObjectResponse<NewsDetailData>>;
         feed: (params?: NewsFeedParams) => Promise<ApiResponse<NewsFeedItem>>;
@@ -3394,6 +3575,13 @@ declare const dataApi: {
         tokenomics: (params?: TokenTokenomicsParams) => Promise<ApiResponse<TokenTokenomicsItem>>;
         transfers: (params: TokenTransfersParams) => Promise<ApiResponse<TokenTransfersItem>>;
     };
+    v2: {
+        kalshi_orderbooks: (params: V2KalshiOrderbooksParams) => Promise<ApiResponse<V2KalshiOrderbooksItem>>;
+        polymarket_candlesticks: (params?: V2PolymarketCandlesticksParams) => Promise<ApiResponse<V2PolymarketCandlesticksItem>>;
+        polymarket_volume_timeseries: (params?: V2PolymarketVolumeTimeseriesParams) => Promise<ApiResponse<V2PolymarketVolumeTimeseriesItem>>;
+        polymarket_orderbooks: (params: V2PolymarketOrderbooksParams) => Promise<ApiResponse<V2PolymarketOrderbooksItem>>;
+        polymarket_volume_chart: (params?: V2PolymarketVolumeChartParams) => Promise<ApiResponse<V2PolymarketVolumeChartItem>>;
+    };
     wallet: {
         detail: (params: WalletDetailParams) => Promise<ApiObjectResponse<WalletDetailData>>;
         history: (params: WalletHistoryParams) => Promise<ApiResponse<WalletHistoryItem>>;