fix: add Polymarket V2 balance cache endpoint

changelog.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.43.0] - 2026-05-22
+
+### Added
+
+- **fetchOrderBook**: Historical order book support via `params.since` and `params.until`. CCXT-compatible signature `(outcomeId, limit?, params?)` across all exchanges and SDK.
+  - `{ since }` — single L2 snapshot at or before the given timestamp (hosted API only, backed by ClickHouse archive).
+  - `{ since, until }` — array of fully reconstructed L2 books from tick-level deltas. Default 100 snapshots, max 1000.
+  - Full reconstruction for all 4 archived venues: Polymarket (absolute deltas), Kalshi (additive deltas), Limitless, Opinion.
+- **OrderBook.datetime**: ISO 8601 datetime field on the `OrderBook` type (CCXT-compatible).
+
+### Changed
+
+- **fetchOrderBook** signature widened from `(outcomeId, side?)` to `(outcomeId, limit?, params?)`. Backwards compatible — `side` moved to `params.side`. All 14 exchange implementations, Router, and SDK updated.
+- SDK `fetchOrderBook` return type widened to `OrderBook | OrderBook[]` (array when `since` + `until` are both provided).
+
 ## [2.42.7] - 2026-05-22
 
 ### Fixed

core/specs/polymarket/PolymarketClobAPI.yaml

@@ -989,6 +989,32 @@ paths:
               schema:
                 $ref: '#/components/schemas/OrdersScoring'
 
+  # ----------------------------------------------------------------------------
+  # Balance / Allowance Methods (CLOB V2 pUSD balance cache sync)
+  # ----------------------------------------------------------------------------
+  /balance-allowance/update:
+    get:
+      operationId: updateBalanceAllowance
+      summary: Update balance and allowance cache
+      tags: [Balances]
+      description: |
+        Refresh the CLOB backend's cached pUSD balance and allowance state after
+        an API-only trader wraps USDC/USDC.e into pUSD or updates approvals.
+        Polymarket CLOB V2 requires this sync before the exchange reflects the
+        latest pUSD collateral state for order placement.
+      security:
+        - L2Auth: []
+      parameters:
+        - $ref: '#/components/parameters/L2Headers'
+      responses:
+        '200':
+          description: Balance and allowance cache update result
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+
   # ----------------------------------------------------------------------------
   # Geoblock Method (From "Geographic Restrictions" text)
   # ----------------------------------------------------------------------------
@@ -1006,4 +1032,4 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/GeoblockResponse'
+                $ref: '#/components/schemas/GeoblockResponse'

core/src/exchanges/polymarket/api-clob.ts

@@ -1,6 +1,6 @@
 /**
- * Auto-generated from /home/zihao/pmxt/core/specs/polymarket/PolymarketClobAPI.yaml
- * Generated at: 2026-05-10T23:00:51.405Z
+ * Auto-generated from /Users/samueltinnerholm/Documents/GitHub/pmxt/core/specs/polymarket/PolymarketClobAPI.yaml
+ * Generated at: 2026-05-22T18:49:00.795Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export const polymarketClobSpec = {
@@ -515,6 +515,25 @@ export const polymarketClobSpec = {
                 ]
             }
         },
+        "/balance-allowance/update": {
+            "get": {
+                "operationId": "updateBalanceAllowance",
+                "summary": "Update balance and allowance cache",
+                "tags": [
+                    "Balances"
+                ],
+                "security": [
+                    {
+                        "L2Auth": []
+                    }
+                ],
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/L2Headers"
+                    }
+                ]
+            }
+        },
         "/geoblock": {
             "get": {
                 "operationId": "getGeoblock",

core/test/pipeline/polymarket-v2-spec.test.ts

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import path from 'path';
+
+import { polymarketClobSpec } from '../../src/exchanges/polymarket/api-clob';
+import { parseOpenApiSpec } from '../../src/utils/openapi';
+
+describe('Polymarket CLOB V2 spec drift coverage', () => {
+    test('exposes the pUSD balance/allowance cache sync endpoint as an L2-authenticated implicit API method', () => {
+        const descriptor = parseOpenApiSpec(polymarketClobSpec);
+
+        expect(descriptor.endpoints.updateBalanceAllowance).toMatchObject({
+            method: 'GET',
+            path: '/balance-allowance/update',
+            isPrivate: true,
+            operationId: 'updateBalanceAllowance',
+        });
+    });
+
+    test('keeps the Polymarket on-chain balance lookup on pUSD instead of legacy USDC.e', () => {
+        const source = fs.readFileSync(
+            path.join(__dirname, '../../src/exchanges/polymarket/index.ts'),
+            'utf8',
+        );
+
+        expect(source).toContain('0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB');
+        expect(source).not.toContain('0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174');
+    });
+});