fix: document watchOrderBook limit params

smartmita · smartmita · commit 940eaf14ff23 · 2026-05-22T22:03:21.000+08:00
diff --git a/core/api-doc-config.generated.json b/core/api-doc-config.generated.json
@@ -537,6 +537,12 @@
                     "type": "number",
                     "optional": true,
                     "description": "Optional limit for orderbook depth"
+                },
+                {
+                    "name": "params",
+                    "type": "Record<string, any>",
+                    "optional": true,
+                    "description": "Optional exchange-specific parameters"
                 }
             ],
             "returns": {
@@ -560,6 +566,12 @@
                     "type": "number",
                     "optional": true,
                     "description": "Optional limit for orderbook depth"
+                },
+                {
+                    "name": "params",
+                    "type": "Record<string, any>",
+                    "optional": true,
+                    "description": "Optional exchange-specific parameters"
                 }
             ],
             "returns": {
@@ -953,4 +965,4 @@
         "python": "import pmxt\nimport os\n\nexchange = pmxt.Polymarket(\n    private_key=os.getenv('POLYMARKET_PRIVATE_KEY')\n)\n\n# 1. Check balance\nbalances = exchange.fetch_balance()\nif balances:\n    balance = balances[0]\n    print(f'Available: ${balance.available}')\n\n# 2. Search for a market\nmarkets = exchange.fetch_markets(query='Trump')\nmarket = markets[0]\noutcome = market.yes\n\nprint(f'{market.title}')\nprint(f'Price: {outcome.price * 100:.1f}%')\n\n# 3. Place a limit order\norder = exchange.create_order(\n    market_id=market.market_id,\n    outcome_id=outcome.outcome_id,\n    side='buy',\n    type='limit',\n    amount=10,\n    price=0.50\n)\n\nprint(f'Order placed: {order.id}')\n\n# 4. Check order status\nupdated_order = exchange.fetch_order(order.id)\nprint(f'Status: {updated_order.status}')\nprint(f'Filled: {updated_order.filled}/{updated_order.amount}')\n\n# 5. Cancel if needed\nif updated_order.status == 'open':\n    exchange.cancel_order(order.id)\n    print('Order cancelled')\n\n# 6. Check positions\npositions = exchange.fetch_positions()\nfor pos in positions:\n    pnl_sign = '+' if pos.unrealized_pnl > 0 else ''\n    print(f'{pos.outcome_label}: {pnl_sign}${pos.unrealized_pnl:.2f}')",
         "typescript": "import pmxt from 'pmxtjs';\n\nconst exchange = new pmxt.Polymarket({\n  privateKey: process.env.POLYMARKET_PRIVATE_KEY\n});\n\n// 1. Check balance\nconst [balance] = await exchange.fetchBalance();\nconsole.log(`Available: $${balance.available}`);\n\n// 2. Search for a market\nconst markets = await exchange.fetchMarkets({ query: 'Trump' });\nconst market = markets[0];\nconst outcome = market.yes;\n\nconsole.log(market.title);\nconsole.log(`Price: ${(outcome.price * 100).toFixed(1)}%`);\n\n// 3. Place a limit order\nconst order = await exchange.createOrder({\n  marketId: market.marketId,\n  outcomeId: outcome.outcomeId,\n  side: 'buy',\n  type: 'limit',\n  amount: 10,\n  price: 0.50\n});\n\nconsole.log(`Order placed: ${order.id}`);\n\n// 4. Check order status\nconst updatedOrder = await exchange.fetchOrder(order.id);\nconsole.log(`Status: ${updatedOrder.status}`);\nconsole.log(`Filled: ${updatedOrder.filled}/${updatedOrder.amount}`);\n\n// 5. Cancel if needed\nif (updatedOrder.status === 'open') {\n  await exchange.cancelOrder(order.id);\n  console.log('Order cancelled');\n}\n\n// 6. Check positions\nconst positions = await exchange.fetchPositions();\npositions.forEach(pos => {\n  console.log(`${pos.outcomeLabel}: ${pos.unrealizedPnL > 0 ? '+' : ''}$${pos.unrealizedPnL.toFixed(2)}`);\n});"
     }
-}
+}
diff --git a/core/src/BaseExchange.ts b/core/src/BaseExchange.ts
@@ -1248,9 +1248,10 @@ export abstract class PredictionMarketExchange {
      *
      * @param outcomeId - The Outcome ID to watch
      * @param limit - Optional limit for orderbook depth
+     * @param params - Optional exchange-specific parameters
      * @returns Promise that resolves with the current orderbook state
      */
-    async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, limit?: number, params: Record<string, any> = {}): Promise<OrderBook> {
         throw new Error(`watchOrderBook() is not supported by ${this.name}`);
     }
 
@@ -1262,15 +1263,16 @@ export abstract class PredictionMarketExchange {
      *
      * @param outcomeIds - Array of Outcome IDs to watch
      * @param limit - Optional limit for orderbook depth
+     * @param params - Optional exchange-specific parameters
      * @returns Promise that resolves with order books keyed by ID
      */
-    async watchOrderBooks(outcomeIds: string[], limit?: number): Promise<Record<string, OrderBook>> {
+    async watchOrderBooks(outcomeIds: string[], limit?: number, params: Record<string, any> = {}): Promise<Record<string, OrderBook>> {
         // Default implementation: subscribe to each ID individually.
         // Exchanges with native batch support (e.g. Kalshi) override this
         // to send a single subscribe message for all tickers.
         const entries = await Promise.all(
             outcomeIds.map(async (oid): Promise<[string, OrderBook]> => {
-                const book = await this.watchOrderBook(oid, limit);
+                const book = await this.watchOrderBook(oid, limit, params);
                 return [oid, book];
             }),
         );
diff --git a/core/src/exchanges/baozi/index.ts b/core/src/exchanges/baozi/index.ts
@@ -405,7 +405,7 @@ export class BaoziExchange extends PredictionMarketExchange {
     // WebSocket
     // -----------------------------------------------------------------------
 
-    async watchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         if (!this.ws) {
             this.ws = new BaoziWebSocket();
         }
diff --git a/core/src/exchanges/gemini-titan/index.ts b/core/src/exchanges/gemini-titan/index.ts
@@ -224,7 +224,7 @@ export class GeminiTitanExchange extends PredictionMarketExchange {
         return this.geminiWs;
     }
 
-    async watchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         const { instrumentSymbol } = fromOutcomeId(outcomeId);
         return this.ensureWebSocket().watchOrderBook(instrumentSymbol);
     }
diff --git a/core/src/exchanges/kalshi/index.ts b/core/src/exchanges/kalshi/index.ts
@@ -341,7 +341,7 @@ export class KalshiExchange extends PredictionMarketExchange {
 
   private ws?: KalshiWebSocket;
 
-  async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
+  async watchOrderBook(outcomeId: string, limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
     const auth = this.ensureAuth();
     if (!this.ws) {
       const wsConfigWithUrl: KalshiWebSocketConfig = {
@@ -354,7 +354,7 @@ export class KalshiExchange extends PredictionMarketExchange {
     return this.ws.watchOrderBook(marketTicker);
   }
 
-  async watchOrderBooks(outcomeIds: string[], limit?: number): Promise<Record<string, OrderBook>> {
+  async watchOrderBooks(outcomeIds: string[], limit?: number, _params: Record<string, any> = {}): Promise<Record<string, OrderBook>> {
     const auth = this.ensureAuth();
     if (!this.ws) {
       const wsConfigWithUrl: KalshiWebSocketConfig = {
diff --git a/core/src/exchanges/limitless/index.ts b/core/src/exchanges/limitless/index.ts
@@ -450,7 +450,7 @@ export class LimitlessExchange extends PredictionMarketExchange {
     // WebSocket
     // ------------------------------------------------------------------------
 
-    async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         const slug = await this.resolveSlug(outcomeId);
         const ws = this.ensureWs();
         return ws.watchOrderBook(slug);
diff --git a/core/src/exchanges/myriad/index.ts b/core/src/exchanges/myriad/index.ts
@@ -243,7 +243,7 @@ export class MyriadExchange extends PredictionMarketExchange {
     // WebSocket (poll-based)
     // ------------------------------------------------------------------------
 
-    async watchOrderBook(outcomeId: string, _limit?: number): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         this.ensureAuth();
         if (!this.ws) {
             this.ws = new MyriadWebSocket(
diff --git a/core/src/exchanges/opinion/index.ts b/core/src/exchanges/opinion/index.ts
@@ -387,7 +387,7 @@ export class OpinionExchange extends PredictionMarketExchange {
     // WebSocket
     // -------------------------------------------------------------------------
 
-    async watchOrderBook(outcomeId: string): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         const ws = this.ensureWebSocket();
         const marketId = this.resolveMarketId(outcomeId);
         return ws.watchOrderBook(marketId);
diff --git a/core/src/exchanges/polymarket/index.ts b/core/src/exchanges/polymarket/index.ts
@@ -517,7 +517,7 @@ export class PolymarketExchange extends PredictionMarketExchange {
     // ----------------------------------------------------------------------------
 
 
-    async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         return this.ensureWs().watchOrderBook(outcomeId);
     }
 
diff --git a/core/src/exchanges/polymarket_us/index.ts b/core/src/exchanges/polymarket_us/index.ts
@@ -381,7 +381,7 @@ export class PolymarketUSExchange extends PredictionMarketExchange {
         return this.wsWrapper;
     }
 
-    override async watchOrderBook(outcomeId: string, _limit?: number): Promise<OrderBook> {
+    override async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         return this.run(() => this.ensureWs().watchOrderBook(outcomeId));
     }
 
diff --git a/core/src/exchanges/probable/index.ts b/core/src/exchanges/probable/index.ts
@@ -457,7 +457,7 @@ export class ProbableExchange extends PredictionMarketExchange {
     // WebSocket Streaming (public, no auth needed)
     // --------------------------------------------------------------------------
 
-    async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {
         if (!this.ws) {
             this.ws = new ProbableWebSocket(this.wsConfig);
         }
diff --git a/core/src/server/method-verbs.json b/core/src/server/method-verbs.json
@@ -306,6 +306,11 @@
         "name": "limit",
         "kind": "number",
         "optional": true
+      },
+      {
+        "name": "params",
+        "kind": "object",
+        "optional": true
       }
     ]
   },
@@ -321,6 +326,11 @@
         "name": "limit",
         "kind": "number",
         "optional": true
+      },
+      {
+        "name": "params",
+        "kind": "object",
+        "optional": true
       }
     ]
   },
diff --git a/core/test/pipeline/watch-order-book-api.test.ts b/core/test/pipeline/watch-order-book-api.test.ts
@@ -0,0 +1,52 @@
+import fs from 'fs';
+import path from 'path';
+
+const repoRoot = path.resolve(__dirname, '../../..');
+
+function read(relativePath: string): string {
+    return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+}
+
+describe('watchOrderBook API consistency', () => {
+    it('keeps the core signature CCXT-compatible with limit and params', () => {
+        const baseExchange = read('core/src/BaseExchange.ts');
+        const methodVerbs = read('core/src/server/method-verbs.json');
+        const generatedApiConfig = read('core/api-doc-config.generated.json');
+        const tsClient = read('sdks/typescript/pmxt/client.ts');
+        const pyClient = read('sdks/python/pmxt/client.py');
+        const methodVerbConfig = JSON.parse(methodVerbs);
+        const apiConfig = JSON.parse(generatedApiConfig);
+
+        expect(baseExchange).toContain(
+            'async watchOrderBook(outcomeId: string, limit?: number, params: Record<string, any> = {})',
+        );
+        expect(methodVerbConfig.watchOrderBook.args).toEqual([
+            { name: 'outcomeId', kind: 'string', optional: false },
+            { name: 'limit', kind: 'number', optional: true },
+            { name: 'params', kind: 'object', optional: true },
+        ]);
+        expect(apiConfig.methods.watchOrderBook.params.map((param: { name: string }) => param.name)).toEqual([
+            'id',
+            'limit',
+            'params',
+        ]);
+        expect(tsClient).toContain(
+            'async watchOrderBook(outcomeId: string | MarketOutcome, limit?: number, params: Record<string, any> = {})',
+        );
+        expect(pyClient).toContain('params: Optional[Dict[str, Any]] = None');
+    });
+
+    it('documents watchOrderBook limit and params in public docs and llms export', () => {
+        const docs = read('docs/api-reference/watch-order-book.mdx');
+        const llms = read('docs/llms-full.txt');
+
+        for (const source of [docs, llms]) {
+            expect(source).toContain(
+                '| `limit` | number | No | Optional depth limit for the streamed order book |',
+            );
+            expect(source).toContain(
+                '| `params` | object | No | Optional exchange-specific parameters |',
+            );
+        }
+    });
+});
diff --git a/docs/api-reference/watch-order-book.mdx b/docs/api-reference/watch-order-book.mdx
@@ -14,6 +14,8 @@ Supported venues: `polymarket`, `kalshi`, `limitless`, `opinion`.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `outcomeId` | string | Yes | The outcome token ID to watch |
+| `limit` | number | No | Optional depth limit for the streamed order book |
+| `params` | object | No | Optional exchange-specific parameters |
 
 ## Response
 
@@ -53,7 +55,7 @@ const exchange = new Polymarket({ pmxtApiKey: "YOUR_PMXT_API_KEY" });
 
 // Stream orderbook updates — each call returns the next snapshot
 while (true) {
-  const book = await exchange.watchOrderBook("OUTCOME_ID");
+  const book = await exchange.watchOrderBook("OUTCOME_ID", 50);
   if (!book.bids.length || !book.asks.length) continue;
   console.log(`Best bid: ${book.bids[0].price} (${book.bids[0].size} contracts)`);
   console.log(`Best ask: ${book.asks[0].price} (${book.asks[0].size} contracts)`);
diff --git a/docs/api-reference/watch-order-books.mdx b/docs/api-reference/watch-order-books.mdx
@@ -14,6 +14,8 @@ Supported venues: `polymarket`, `kalshi`, `limitless`, `opinion`.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `outcomeIds` | string[] | Yes | Array of outcome token IDs to watch |
+| `limit` | number | No | Optional depth limit for each streamed order book |
+| `params` | object | No | Optional exchange-specific parameters |
 
 ## Response
 
diff --git a/docs/api-reference/websocket.mdx b/docs/api-reference/websocket.mdx
@@ -19,7 +19,7 @@ All messages are JSON text frames. A single connection supports multiple concurr
 ### Subscribe
 
 ```json
-{ "id": "req-1", "action": "subscribe", "method": "watchOrderBook", "args": ["OUTCOME_ID"] }
+{ "id": "req-1", "action": "subscribe", "method": "watchOrderBook", "args": ["OUTCOME_ID", 50] }
 ```
 
 ### Data event
diff --git a/docs/llms-full.txt b/docs/llms-full.txt
@@ -4074,6 +4074,8 @@ Supported venues: `polymarket`, `kalshi`, `limitless`, `opinion`.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `outcomeId` | string | Yes | The outcome token ID to watch |
+| `limit` | number | No | Optional depth limit for the streamed order book |
+| `params` | object | No | Optional exchange-specific parameters |
 
 #### Response
 
diff --git a/sdks/python/API_REFERENCE.md b/sdks/python/API_REFERENCE.md
@@ -745,13 +745,14 @@ Watch order book updates in real-time via WebSocket.
 **Signature:**
 
 ```python
-def watch_order_book(id: str, limit: Optional[float] = None) -> OrderBook:
+def watch_order_book(id: str, limit: Optional[float] = None, params: Optional[dict] = None) -> OrderBook:
 ```
 
 **Parameters:**
 
 - `id` (str): The Outcome ID to watch
 - `limit` (float) - **Optional**: Optional limit for orderbook depth
+- `params` (dict) - **Optional**: Optional exchange-specific parameters
 
 **Returns:** [OrderBook](#orderbook) - Promise that resolves with the current orderbook state
 
diff --git a/sdks/python/pmxt/client.py b/sdks/python/pmxt/client.py
@@ -1733,7 +1733,13 @@ def _watch_via_ws(
             # Transport-level failure -- fall back to HTTP
             return None
 
-    def watch_order_book(self, outcome_id: Union[str, "MarketOutcome"] = _UNSET, limit: Optional[int] = None, **_compat_kwargs) -> OrderBook:
+    def watch_order_book(
+        self,
+        outcome_id: Union[str, "MarketOutcome"] = _UNSET,
+        limit: Optional[int] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **_compat_kwargs,
+    ) -> OrderBook:
         """
         Watch real-time order book updates via WebSocket.
 
@@ -1746,6 +1752,7 @@ def watch_order_book(self, outcome_id: Union[str, "MarketOutcome"] = _UNSET, lim
         Args:
             outcome_id: Outcome ID to watch
             limit: Optional depth limit for order book
+            params: Optional exchange-specific parameters
 
         Returns:
             Next order book update
@@ -1762,6 +1769,10 @@ def watch_order_book(self, outcome_id: Union[str, "MarketOutcome"] = _UNSET, lim
         args: List[Any] = [outcome_id]
         if limit is not None:
             args.append(limit)
+        if params:
+            if limit is None:
+                args.append(None)
+            args.append(params)
 
         # Try WebSocket transport first
         ws_data = self._watch_via_ws("watchOrderBook", args)
@@ -1833,6 +1844,7 @@ def watch_order_books(
         self,
         outcome_ids: List[Union[str, "MarketOutcome"]] = _UNSET,
         limit: Optional[int] = None,
+        params: Optional[Dict[str, Any]] = None,
         **_compat_kwargs,
     ) -> Dict[str, OrderBook]:
         """
@@ -1849,6 +1861,7 @@ def watch_order_books(
             outcome_ids: List of outcome IDs (or MarketOutcome objects)
                 to watch simultaneously.
             limit: Optional depth limit for each order book.
+            params: Optional exchange-specific parameters.
 
         Returns:
             Dict mapping ticker string to OrderBook.
@@ -1876,6 +1889,10 @@ def watch_order_books(
         args: List[Any] = [resolved_ids]
         if limit is not None:
             args.append(limit)
+        if params:
+            if limit is None:
+                args.append(None)
+            args.append(params)
 
         # Try WebSocket transport first
         ws = self._get_or_create_ws()
diff --git a/sdks/typescript/API_REFERENCE.md b/sdks/typescript/API_REFERENCE.md
@@ -748,20 +748,21 @@ Watch order book updates in real-time via WebSocket.
 **Signature:**
 
 ```typescript
-async watchOrderBook(id: string, limit?: number): Promise<OrderBook>
+async watchOrderBook(id: string, limit?: number, params: Record<string, any> = {}): Promise<OrderBook>
 ```
 
 **Parameters:**
 
 - `id` (string): The Outcome ID to watch
 - `limit` (number) - **Optional**: Optional limit for orderbook depth
+- `params` (object) - **Optional**: Optional exchange-specific parameters
 
 **Returns:** Promise<[OrderBook](#orderbook)> - Promise that resolves with the current orderbook state
 
 **Example:**
 
 ```typescript
-await exchange.watchOrderBook("12345", { limit: 10 })
+await exchange.watchOrderBook("12345", 10)
 ```
 
 
@@ -774,7 +775,7 @@ Watch multiple order books simultaneously via WebSocket.
 **Signature:**
 
 ```typescript
-async watchOrderBooks(ids: string[], limit?: number): Promise<Record<string, OrderBook>>
+async watchOrderBooks(ids: string[], limit?: number, params: Record<string, any> = {}): Promise<Record<string, OrderBook>>
 ```
 
 **Parameters:**
diff --git a/sdks/typescript/pmxt/client.ts b/sdks/typescript/pmxt/client.ts

Original file line number	Diff line number	Diff line change
`@@ -405,7 +405,7 @@ export class BaoziExchange extends PredictionMarketExchange {`
`405`	`405`	`// WebSocket`
`406`	`406`	`// -----------------------------------------------------------------------`
`407`	`407`
`408`		`- async watchOrderBook(outcomeId: string): Promise<OrderBook> {`
	`408`	`+ async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {`
`409`	`409`	`if (!this.ws) {`
`410`	`410`	`this.ws = new BaoziWebSocket();`
`411`	`411`	`}`
Original file line number	Diff line number	Diff line change
`@@ -224,7 +224,7 @@ export class GeminiTitanExchange extends PredictionMarketExchange {`
`224`	`224`	`return this.geminiWs;`
`225`	`225`	`}`
`226`	`226`
`227`		`- async watchOrderBook(outcomeId: string): Promise<OrderBook> {`
	`227`	`+ async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {`
`228`	`228`	`const { instrumentSymbol } = fromOutcomeId(outcomeId);`
`229`	`229`	`return this.ensureWebSocket().watchOrderBook(instrumentSymbol);`
`230`	`230`	`}`
Original file line number	Diff line number	Diff line change
`@@ -517,7 +517,7 @@ export class PolymarketExchange extends PredictionMarketExchange {`
`517`	`517`	`// ----------------------------------------------------------------------------`
`518`	`518`
`519`	`519`
`520`		`- async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {`
	`520`	`+ async watchOrderBook(outcomeId: string, limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {`
`521`	`521`	`return this.ensureWs().watchOrderBook(outcomeId);`
`522`	`522`	`}`
`523`	`523`
Original file line number	Diff line number	Diff line change
`@@ -381,7 +381,7 @@ export class PolymarketUSExchange extends PredictionMarketExchange {`
`381`	`381`	`return this.wsWrapper;`
`382`	`382`	`}`
`383`	`383`
`384`		`- override async watchOrderBook(outcomeId: string, _limit?: number): Promise<OrderBook> {`
	`384`	`+ override async watchOrderBook(outcomeId: string, _limit?: number, _params: Record<string, any> = {}): Promise<OrderBook> {`
`385`	`385`	`return this.run(() => this.ensureWs().watchOrderBook(outcomeId));`
`386`	`386`	`}`
`387`	`387`