Polymarket Real-Time Data Client

repository·main·Indexed 42 days ago

https://github.com/polymarket/real-time-data-client

A TypeScript/JavaScript client (v1.4.2) providing a wrapper to connect to Polymarket's real-time data streaming WebSocket service. It allows developers to subscribe to activity, comments, and price updates for crypto and equity assets. The client handles connection lifecycles, automatic heartbeats, and supports authentication via ClobApiKeyCreds and GammaAuth for protected topics.

Tokens: 3.9K
Snippets: 14
Records: 24
Agent score: 52%

What's inside Polymarket Real-Time Data Client

How initial data dumps work for prices
main
For crypto_prices, crypto_prices_chainlink, and equity_prices topics, if you provide a filter (e.g., {"symbol":"BTCUSDT"}) during subscription, the server will automatically send an initial snapshot of recent data upon connection. This snapshot contains an array of price data objects, each with a timestamp and value.
https://github.com/polymarket/real-time-data-client/blob/main/README.md

Quickstart: Connect and receive messages with RealTimeDataClient

main

To use the RealTimeDataClient, instantiate it with onMessage and onConnect callbacks, then call .connect(). Use the onConnect callback to perform subscriptions via client.subscribe().

import { RealTimeDataClient } from "../src/client";
import { Message } from "../src/model";

const onMessage = (message: Message): void => {
    console.log(message.topic, message.type, message.payload);
};

const onConnect = (client: RealTimeDataClient): void => {
    // Subscribe to a topic
    client.subscribe({
        subscriptions: [
            {
                topic: "comments",
                type: "*", // "*" can be used to connect to all the types of the topic
                filters: `{"parentEntityID":100,"parentEntityType":"Event"}`,
            },
        ],
    });
};

new RealTimeDataClient({ onMessage, onConnect }).connect();

Initialize and use the RealTimeDataClient
main
To use the real-time data stream, instantiate the RealTimeDataClient class with an optional RealTimeDataClientArgs object and call .connect(). You can provide callbacks to handle connection events, incoming messages, and status changes.
Configuration Options (RealTimeDataClientArgs)
- onConnect?: (client: RealTimeDataClient) => void: Called when the connection is successfully established.
- onMessage?: (client: RealTimeDataClient, message: Message) => void: Called when a message containing a payload is received.
- onStatusChange?: (status: ConnectionStatus) => void: Called when the connection status changes (e.g., CONNECTING, CONNECTED, DISCONNECTED).
- host?: string: The WebSocket server URL. Defaults to wss://ws-live-data.polymarket.com.
- pingInterval?: number: Interval in milliseconds for sending pings to keep the connection alive. Defaults to 5000.
- autoReconnect?: boolean: If true, the client will attempt to reconnect automatically if the connection is lost. Defaults to true.
```
import { RealTimeDataClient } from '@polymarket/real-time-data-client';

const client = new RealTimeDataClient({
  onConnect: (client) => {
    console.log('Connected!');
    // You can subscribe here
  },
  onMessage: (client, message) => {
    console.log('Received message:', message);
  },
  onStatusChange: (status) => {
    console.log('Status changed to:', status);
  }
});

client.connect();
```
https://github.com/polymarket/real-time-data-client/blob/main/src/client.ts

Authenticate with ClobAuth

main

For topics requiring authentication (like clob_user), provide clob_auth credentials within the subscription object. The clob_auth object uses the ClobApiKeyCreds interface.

client.subscribe({
    subscriptions: [
        {
            topic: "clob_user",
            type: "*",
            clob_auth: {
                key: "xxxxxx-xxxx-xxxxx-xxxx-xxxxxx",
                secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                passphrase: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            },
        },
    ],
});

Disconnect the RealTimeDataClient
main
Call client.disconnect() to close the connection to the WebSocket server.
```
client.disconnect();
```
https://github.com/polymarket/real-time-data-client/blob/main/README.md
Unsubscribe from message streams
main
To stop receiving a specific type of message within a topic, call client.subscribe() with the specific topic and type. If you previously subscribed to all types using "*", specifying a single type will unsubscribe only from that type.
Example of unsubscribing from 'trades' in the 'activity' topic:
```
client.subscribe({
    subscriptions: [
        {
            topic: "activity",
            type: "trades",
        },
    ],
});
```
https://github.com/polymarket/real-time-data-client/blob/main/README.md
Subscribe to message streams
main
Use client.subscribe() to listen to specific topics and message types. You can use the wildcard "*" for the type field to subscribe to all message types within a topic.
To subscribe to 'trades' messages from the 'activity' topic and all 'comments' messages:
```
client.subscribe({
    subscriptions: [
        {
            topic: "activity",
            type: "trades",
        },
    ],
});

client.subscribe({
    subscriptions: [
        {
            topic: "comments",
            type: "*",
        },
    ],
});
```
https://github.com/polymarket/real-time-data-client/blob/main/README.md

Reference: Messages hierarchy and topics

main

The following table defines the available topics, message types, and required filters for the real-time data stream.

Topic	Type	Auth	Filters	Schema
`activity`	`trades`	-	`{"event_slug":"string"}` OR `{"market_slug":"string"}`	`Trade`
`activity`	`orders_matched`	-	`{"event_slug":"string"}` OR `{"market_slug":"string"}`	`Trade`
`comments`	`comment_created`	-	`{"parentEntityID":number,"parentEntityType":"Event / Series"}`	`Comment`
`comments`	`comment_removed`	-	`{"parentEntityID":number,"parentEntityType":"Event / Series"}`	`Comment`
`comments`	`reaction_created`	-	`{"parentEntityID":number,"parentEntityType":"Event / Series"}`	`Reaction`
`comments`	`reaction_removed`	-	`{"parentEntityID":number,"parentEntityType":"Event / Series"}`	`Reaction`
`crypto_prices`	`update`	-	`{"symbol":string}`	`CryptoPrice`
`crypto_prices_chainlink`	`update`	-	`{"symbol":string}`	`CryptoPrice`
`equity_prices`	`update`	-	`{"symbol":string}`	`EquityPrice`

Reference: CryptoPrice and EquityPrice schemas
main
Both CryptoPrice and EquityPrice use the following schema:
Name Type Description
symbol string Symbol of the asset
timestamp number Timestamp in milliseconds for the update
value number Value at the time of update
Initial data dump on connection: When a connection is established and a filter is used, the server provides an initial snapshot of recent data for CryptoPrice and EquityPrice in this format:
Name Type Description
symbol string Symbol of the asset
data array Array of price data objects, each containing timestamp and value
https://github.com/polymarket/real-time-data-client/blob/main/README.md

Name	Type	Description
`symbol`	string	Symbol of the asset
`timestamp`	number	Timestamp in milliseconds for the update
`value`	number	Value at the time of update

Name	Type	Description
`symbol`	string	Symbol of the asset
`data`	array	Array of price data objects, each containing `timestamp` and `value`

Reference: Comment message schema

main

The Comment message schema for the comments topic contains the following fields:

Name	Type	Description
`id`	string	Unique identifier of comment
`body`	string	Content of the comment
`parentEntityType`	string	Type of the parent entity (Event or Series)
`parentEntityID`	number	ID of the parent entity
`parentCommentID`	string	ID of the parent comment
`userAddress`	string	Address of the user
`replyAddress`	string	Address of the reply user
`createdAt`	string	Creation timestamp
`updatedAt`	string	Last update timestamp

Reference: Trade message schema

main

The Trade message schema for the activity topic contains the following fields:

Name	Type	Description
`asset`	string	ERC1155 token ID of conditional token being traded
`bio`	string	Bio of the user of the trade
`conditionId`	string	Id of market which is also the CTF condition ID
`eventSlug`	string	Slug of the event
`icon`	string	URL to the market icon image
`name`	string	Name of the user of the trade
`outcome`	string	Human readable outcome of the market
`outcomeIndex`	integer	Index of the outcome
`price`	float	Price of the trade
`profileImage`	string	URL to the user profile image
`proxyWallet`	string	Address of the user proxy wallet
`pseudonym`	string	Pseudonym of the user
`side`	string	Side of the trade (`BUY`/`SELL`)
`size`	integer	Size of the trade
`slug`	string	Slug of the market
`timestamp`	integer	Timestamp of the trade
`title`	string	Title of the event
`transactionHash`	string	Hash of the transaction

Reference: Reaction message schema

main

The Reaction message schema for the comments topic contains the following fields:

Name	Type	Description
`id`	string	Unique identifier of reaction
`commentID`	number	ID of the comment
`reactionType`	string	Type of the reaction
`icon`	string	Icon representing the reaction
`userAddress`	string	Address of the user
`createdAt`	string	Creation timestamp

Polymarket Real-Time Data Client

What's inside Polymarket Real-Time Data Client

Configuration Options (RealTimeDataClientArgs)

Configuration Options (`RealTimeDataClientArgs`)