feat(router): add SQL query support to both SDKs

- Add SqlResult, SqlMeta, SqlColumn types in TypeScript and Python
- Add sql(query: string) method to Router class
- Export types from both SDKs
- Full type safety

Fixes #1032

Author: AbhilashG12

sdks/python/pmxt/__init__.py

@@ -24,6 +24,7 @@
 from .router import Router
 from .feed_client import FeedClient
 from .server_manager import ServerManager
+from .router import SqlResult, SqlMeta, SqlColumn
 from .errors import (
     PmxtError,
     BadRequest,
@@ -269,4 +270,8 @@ def restart_server() -> None:
     "OrderSide",
     "OrderType",
     "CandleInterval",
+    # SQL
+    'SqlResult',
+    'SqlMeta', 
+    'SqlColumn',
 ]

sdks/python/pmxt/router.py

@@ -23,6 +23,29 @@
     UnifiedEvent,
 )
 from pmxt_internal.exceptions import ApiException
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class SqlColumn:
+    """Column metadata for SQL query results."""
+    name: str
+    type: str
+
+
+@dataclass
+class SqlMeta:
+    """Metadata about SQL query results."""
+    columns: List[SqlColumn]
+    rows: int
+
+
+@dataclass
+class SqlResult:
+    """Result of a SQL query."""
+    data: List[Dict[str, Any]]
+    meta: SqlMeta
 
 
 def _parse_market(raw: Any) -> Any:
@@ -434,6 +457,75 @@ def fetch_matched_event_clusters(
 
         raw = self._get_catalog_path("/v0/matched-event-clusters", params)
         return [_parse_event_cluster(c) for c in _extract_response_list(raw)]
+    
+    # ------------------------------------------------------------------
+    # SQL Query
+    # ------------------------------------------------------------------
+
+    def sql(self, query: str) -> SqlResult:
+        """
+        Execute a SQL query against the ClickHouse database.
+
+        This endpoint provides direct SQL access to the prediction market
+        catalog, enabling complex analytics, custom queries, and data export.
+
+        Args:
+            query: SQL query string
+
+        Returns:
+            SqlResult: Query results with data and metadata
+
+        Example:
+            ```python
+            router = Router(pmxt_api_key="...")
+            result = router.sql("SELECT * FROM markets LIMIT 10")
+            for row in result.data:
+                print(row["question"])
+            ```
+        """
+        url = f"{self._resolve_sidecar_host()}/v0/sql"
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        headers.update(self._get_auth_headers())
+
+        body = json.dumps({"query": query})
+
+        try:
+            response = self._fetch_with_retry(
+                lambda: self._api_client.call_api(
+                    method="POST",
+                    url=url,
+                    header_params=headers,
+                    body=body,
+                )
+            )
+            response.read()
+            data = json.loads(response.data)
+
+            result_data = data.get("data", [])
+            meta_data = data.get("meta", {})
+
+            columns = []
+            for col in meta_data.get("columns", []):
+                columns.append(SqlColumn(
+                    name=col.get("name", ""),
+                    type=col.get("type", "string")
+                ))
+
+            meta = SqlMeta(
+                columns=columns,
+                rows=meta_data.get("rows", len(result_data))
+            )
+
+            return SqlResult(data=result_data, meta=meta)
+
+        except ApiException as e:
+            raise self._parse_api_exception(e) from None
+        except Exception as e:
+            raise self._parse_api_exception(e) from None
+
 
     # ------------------------------------------------------------------
     # Price comparison

sdks/typescript/pmxt/router.ts

@@ -31,6 +31,26 @@ function withQuestionAlias<T extends UnifiedMarket>(market: T): T {
     return market;
 }
 
+
+/**
+ * SQL query result from ClickHouse
+ */
+export interface SqlColumn {
+    name: string;
+    type: string;
+}
+
+export interface SqlMeta {
+    columns: SqlColumn[];
+    rows: number;
+}
+
+export interface SqlResult {
+    data: Record<string, unknown>[];
+    meta: SqlMeta;
+}
+
+
 function convertMarket(raw: any): UnifiedMarket {
     const outcomes = (raw.outcomes || []).map((o: any) => ({
         outcomeId: o.outcomeId,
@@ -376,6 +396,76 @@ export class Router extends Exchange {
         }
     }
 
+        // ------------------------------------------------------------------
+    // SQL Query
+    // ------------------------------------------------------------------
+
+    /**
+     * Execute a SQL query against the ClickHouse database.
+     * 
+     * This endpoint provides direct SQL access to the prediction market
+     * catalog, enabling complex analytics, custom queries, and data export.
+     * 
+     * @param query - SQL query string
+     * @returns Query results with data and metadata
+     * 
+     * @example
+     * ```typescript
+     * const router = new Router({ pmxtApiKey: "..." });
+     * 
+     * // Simple query
+     * const result = await router.sql('SELECT * FROM markets LIMIT 10');
+     * console.log(result.data); // Array of market rows
+     * console.log(result.meta.columns); // Column metadata
+     * 
+     * // Complex analytics
+     * const result = await router.sql(`
+     *   SELECT 
+     *     sourceExchange,
+     *     COUNT(*) as marketCount,
+     *     AVG(volume24h) as avgVolume
+     *   FROM markets
+     *   WHERE resolutionDate > NOW() - INTERVAL 7 DAY
+     *   GROUP BY sourceExchange
+     *   ORDER BY avgVolume DESC
+     * `);
+     * ```
+     * 
+     * @throws {PmxtError} If the query fails or is not allowed
+     */
+    async sql(query: string): Promise<SqlResult> {
+        await this.initPromise;
+        
+        try {
+            const json = await this.sidecarReadRequest(
+                'sql',
+                { query },
+                [{ query }]
+            );
+            
+            const data = this.handleResponse(json);
+            
+            if (!data) {
+                return { data: [], meta: { columns: [], rows: 0 } };
+            }
+            
+            // Handle different response shapes
+            const resultData = data.data || data;
+            const resultMeta = data.meta || { columns: [], rows: 0 };
+            
+            return {
+                data: Array.isArray(resultData) ? resultData : [],
+                meta: {
+                    columns: resultMeta.columns || [],
+                    rows: resultMeta.rows || (Array.isArray(resultData) ? resultData.length : 0)
+                }
+            };
+        } catch (error) {
+            if (error instanceof Error) throw error;
+            throw new Error(`SQL query failed: ${error}`);
+        }
+    }
+
     /**
      * Fetch connected clusters of semantically matched markets across venues.
      *