@catalyst-team/poly-sdk 0.4.6 → 0.4.7

package/dist/src/realtime/realtime-data-client.d.ts

@@ -0,0 +1,274 @@
+/**
+ * RealTimeDataClient
+ *
+ * Custom WebSocket client for Polymarket real-time data.
+ * Replaces @polymarket/real-time-data-client with proper:
+ * - RFC 6455 ping/pong mechanism
+ * - Exponential backoff reconnection
+ * - Full subscription management
+ *
+ * WebSocket Protocol (from official docs):
+ * - URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
+ * - Initial subscription: { type: "MARKET", assets_ids: ["token_id_1", ...] }
+ * - Dynamic subscribe: { operation: "subscribe", assets_ids: ["token_id_1"] }
+ * - Dynamic unsubscribe: { operation: "unsubscribe", assets_ids: ["token_id_1"] }
+ *
+ * Event types: book, price_change, last_trade_price, tick_size_change, best_bid_ask
+ *
+ * @see https://docs.polymarket.com/developers/CLOB/websocket/wss-overview
+ * @see https://docs.polymarket.com/developers/CLOB/websocket/market-channel
+ */
+import { type RealTimeDataClientConfig, type RealTimeDataClientInterface, type SubscriptionMessage, type ClobApiKeyCreds, ConnectionStatus } from './types.js';
+export declare class RealTimeDataClient implements RealTimeDataClientInterface {
+    private ws;
+    private config;
+    private status;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private pingTimer;
+    private pongTimer;
+    private pongReceived;
+    private intentionalDisconnect;
+    constructor(config?: RealTimeDataClientConfig);
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): void;
+    /**
+     * Disconnect from the WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to market data
+     *
+     * For initial subscription (when first connecting or adding new tokens):
+     * { type: "MARKET", assets_ids: ["token_id_1", "token_id_2"] }
+     *
+     * For adding tokens to existing subscription:
+     * { operation: "subscribe", assets_ids: ["token_id_3"] }
+     *
+     * @deprecated Use subscribeMarket() for the new API format
+     */
+    subscribe(msg: {
+        subscriptions: SubscriptionMessage[];
+    }): void;
+    /**
+     * Unsubscribe from market data
+     *
+     * Format: { operation: "unsubscribe", assets_ids: ["token_id_1"] }
+     *
+     * @deprecated Use unsubscribeMarket() for the new API format
+     */
+    unsubscribe(msg: {
+        subscriptions: SubscriptionMessage[];
+    }): void;
+    /**
+     * Subscribe to market data (new API)
+     *
+     * @param assetsIds - Array of token IDs to subscribe to
+     * @param isInitial - If true, sends initial subscription format { type: "MARKET", ... }
+     *                    If false, sends dynamic format { operation: "subscribe", ... }
+     */
+    subscribeMarket(assetsIds: string[], isInitial?: boolean): void;
+    /**
+     * Unsubscribe from market data (new API)
+     *
+     * @param assetsIds - Array of token IDs to unsubscribe from
+     */
+    unsubscribeMarket(assetsIds: string[]): void;
+    /**
+     * Subscribe to user channel (requires authentication)
+     *
+     * User channel provides personal order and trade events.
+     * Note: This requires connecting to the USER WebSocket endpoint.
+     *
+     * Format: { type: "USER", auth: { apiKey, secret, passphrase }, markets?: [...] }
+     *
+     * @param auth - CLOB API credentials
+     * @param markets - Optional array of condition IDs to filter events
+     */
+    subscribeUser(auth: ClobApiKeyCreds, markets?: string[]): void;
+    /**
+     * Subscribe to Binance crypto prices
+     *
+     * Provides real-time price updates from Binance exchange.
+     *
+     * **Usage:**
+     * ```typescript
+     * const client = new RealTimeDataClient({ url: WS_ENDPOINTS.LIVE_DATA });
+     * client.connect();
+     * client.subscribeCryptoPrices(['btcusdt', 'ethusdt', 'solusdt', 'xrpusdt']);
+     * ```
+     *
+     * **Symbol Format:** Lowercase concatenated pairs (e.g., 'btcusdt', 'ethusdt', 'solusdt', 'xrpusdt')
+     *
+     * **Subscription Message Format:**
+     * ```json
+     * {
+     *   "action": "subscribe",
+     *   "subscriptions": [{
+     *     "topic": "crypto_prices",
+     *     "type": "*",
+     *     "filters": "{\"symbol\":\"btcusdt\"}"
+     *   }]
+     * }
+     * ```
+     *
+     * **Response Message Format:**
+     * ```json
+     * {
+     *   "topic": "crypto_prices",
+     *   "type": "update",
+     *   "timestamp": 1769846473135,
+     *   "payload": {
+     *     "symbol": "ethusdt",
+     *     "timestamp": 1769846473000,
+     *     "value": 2681.42,
+     *     "full_accuracy_value": "2681.42000000"
+     *   }
+     * }
+     * ```
+     *
+     * **Important Notes:**
+     * - Each symbol requires a separate subscription message
+     * - Use `type: "*"` (not `"update"`)
+     * - Filters must be JSON-stringified: `JSON.stringify({ symbol: "btcusdt" })`
+     * - This implementation matches the official @polymarket/real-time-data-client
+     *
+     * @param symbols - Array of Binance symbols in lowercase (e.g., ['btcusdt', 'ethusdt'])
+     * @see https://docs.polymarket.com/developers/RTDS/RTDS-crypto-prices
+     * @see https://github.com/Polymarket/real-time-data-client
+     */
+    subscribeCryptoPrices(symbols: string[]): void;
+    /**
+     * Unsubscribe from Binance crypto prices
+     *
+     * @param symbols - Array of Binance symbols to unsubscribe from
+     */
+    unsubscribeCryptoPrices(symbols: string[]): void;
+    /**
+     * Subscribe to Chainlink crypto prices
+     *
+     * Provides real-time price updates from Chainlink oracles (official settlement price source).
+     *
+     * **Usage:**
+     * ```typescript
+     * const client = new RealTimeDataClient({ url: WS_ENDPOINTS.LIVE_DATA });
+     * client.connect();
+     * client.subscribeCryptoChainlinkPrices(['btc/usd', 'eth/usd', 'sol/usd', 'xrp/usd']);
+     * ```
+     *
+     * **Symbol Format:** Lowercase slash-separated pairs (e.g., 'btc/usd', 'eth/usd', 'sol/usd', 'xrp/usd')
+     *
+     * **Subscription Message Format:**
+     * ```json
+     * {
+     *   "action": "subscribe",
+     *   "subscriptions": [{
+     *     "topic": "crypto_prices_chainlink",
+     *     "type": "*",
+     *     "filters": "{\"symbol\":\"btc/usd\"}"
+     *   }]
+     * }
+     * ```
+     *
+     * **Response Message Format:**
+     * ```json
+     * {
+     *   "topic": "crypto_prices_chainlink",
+     *   "type": "update",
+     *   "timestamp": 1769833333076,
+     *   "payload": {
+     *     "symbol": "btc/usd",
+     *     "timestamp": 1769833332000,
+     *     "value": 83915.04025109926,
+     *     "full_accuracy_value": "83915040251099250000000"
+     *   }
+     * }
+     * ```
+     *
+     * **Important Notes:**
+     * - Each symbol requires a separate subscription message
+     * - Use `type: "*"` for all message types
+     * - Filters must be JSON-stringified: `JSON.stringify({ symbol: "btc/usd" })`
+     * - Chainlink prices are used as the official settlement source for 15m crypto markets
+     * - Higher precision available via `full_accuracy_value` field
+     *
+     * @param symbols - Array of Chainlink symbols in lowercase (e.g., ['btc/usd', 'eth/usd'])
+     * @see https://docs.polymarket.com/developers/RTDS/RTDS-crypto-prices
+     * @see https://data.chain.link/streams - Official Chainlink data feeds
+     */
+    subscribeCryptoChainlinkPrices(symbols: string[]): void;
+    /**
+     * Unsubscribe from Chainlink crypto prices
+     *
+     * @param symbols - Array of Chainlink symbols to unsubscribe from
+     */
+    unsubscribeCryptoChainlinkPrices(symbols: string[]): void;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get current connection status
+     */
+    getStatus(): ConnectionStatus;
+    private send;
+    private handleOpen;
+    private handleMessage;
+    /**
+     * Parse incoming WebSocket messages into our Message format
+     *
+     * ## Market Channel Events (topic: 'clob_market')
+     * @see https://docs.polymarket.com/developers/CLOB/websocket/market-channel
+     *
+     * | Event Type        | Format                                                    | Trigger                          |
+     * |-------------------|-----------------------------------------------------------|----------------------------------|
+     * | book              | Array: [{ market, asset_id, bids, asks, timestamp, hash }]| Initial subscribe or trade       |
+     * | price_change      | { market, price_changes: [{ asset_id, price, size, ... }]}| Order placed or cancelled        |
+     * | last_trade_price  | { market, asset_id, price, side, size, fee_rate_bps, ... }| Trade execution                  |
+     * | tick_size_change  | { market, asset_id, old_tick_size, new_tick_size, ... }   | Price > 0.96 or < 0.04           |
+     * | best_bid_ask      | { market, asset_id, best_bid, best_ask, spread, ... }     | Best price change (feature-flag) |
+     * | new_market        | { id, question, market, slug, assets_ids, outcomes, ... } | Market creation (feature-flag)   |
+     * | market_resolved   | { ..., winning_asset_id, winning_outcome }                | Market resolved (feature-flag)   |
+     *
+     * ## User Channel Events (topic: 'clob_user')
+     * @see https://docs.polymarket.com/developers/CLOB/websocket/user-channel
+     *
+     * | Event Type | Format                                                          | Trigger                        |
+     * |------------|-----------------------------------------------------------------|--------------------------------|
+     * | trade      | { event_type: 'trade', status, side, price, size, maker_orders }| Order matched/mined/confirmed  |
+     * | order      | { event_type: 'order', type, side, price, original_size, ... }  | Order placed/updated/cancelled |
+     */
+    private parseMessages;
+    /**
+     * Normalize timestamp to milliseconds
+     * Polymarket sends timestamps in seconds, need to convert to milliseconds
+     */
+    private normalizeTimestamp;
+    private handleClose;
+    private handleError;
+    private handlePong;
+    /**
+     * Start periodic ping to keep connection alive
+     *
+     * Uses RFC 6455 WebSocket ping frames, which the server MUST respond to
+     * with pong frames. If no pong is received within pongTimeout, we
+     * consider the connection dead and reconnect.
+     */
+    private startPing;
+    private stopPing;
+    private setPongTimeout;
+    private clearPongTimeout;
+    private handleDeadConnection;
+    /**
+     * Handle reconnection with exponential backoff
+     * Delays: 1s, 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s, 512s (capped at maxReconnectAttempts)
+     */
+    private handleReconnect;
+    private cancelReconnect;
+    private cleanup;
+    private setStatus;
+    private log;
+}
+//# sourceMappingURL=realtime-data-client.d.ts.map

package/dist/src/realtime/realtime-data-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-data-client.d.ts","sourceRoot":"","sources":["../../../src/realtime/realtime-data-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,eAAe,EAEpB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AASpB,qBAAa,kBAAmB,YAAW,2BAA2B;IACpE,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAIZ;IAEF,OAAO,CAAC,MAAM,CAAmD;IACjE,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,qBAAqB,CAAS;gBAE1B,MAAM,GAAE,wBAA6B;IAyBjD;;OAEG;IACH,OAAO,IAAI,IAAI;IAmBf;;OAEG;IACH,UAAU,IAAI,IAAI;IAalB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,GAAG,EAAE;QAAE,aAAa,EAAE,mBAAmB,EAAE,CAAA;KAAE,GAAG,IAAI;IAqB9D;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE;QAAE,aAAa,EAAE,mBAAmB,EAAE,CAAA;KAAE,GAAG,IAAI;IAqBhE;;;;;;OAMG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,UAAO,GAAG,IAAI;IAkB5D;;;;OAIG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAQ5C;;;;;;;;;;OAUG;IACH,aAAa,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IAa9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAmB9C;;;;OAIG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAmBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,8BAA8B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAmBvD;;;;OAIG;IACH,gCAAgC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAmBzD;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAQ7B,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,aAAa;IAiBrB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,aAAa;IA2KrB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,UAAU;IAUlB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAwBjB,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,oBAAoB;IAoB5B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,GAAG;CAKZ"}