@polymarket/real-time-data-client

Real time data client

This client provides a wrapper to connect to the real-time-data-streaming WebSocket service.

How to use it

Here is a quick example about how to connect to the service and start receiving messages (you can find more in the folder examples/):

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"}`, // empty means no filter
            },
        ],
    });
};

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

How to subscribe and unsubscribe from messages

Once the connection is stablished and you have a client: RealTimeDataClient object, you can subscribe and unsubscribe to many messages streamings using the same connection.

Subscribe

Subscribe to 'trades' messages from the topic 'activity' and to the all comments messages.

client.subscribe({
    subscriptions: [
        {
            topic: "activity",
            type: "trades",
        },
    ],
});

client.subscribe({
    subscriptions: [
        {
            topic: "comments",
            type: "*", // "*"" can be used to connect to all the types of the topic
        },
    ],
});

Unsubscribe

Unsubscribe from the new trades messages of the topic 'activity'. If 'activity' has more messages types and I used '*' to connect to all of them, this will only unsubscribe from the type 'trades'.

client.subscribe({
    subscriptions: [
        {
            topic: "activity",
            type: "trades",
        },
    ],
});

Disconnect

The client object provides a method to disconnect from the WebSocket server:

client.disconnect();

Messages hierarchy

Topic	Type	Auth	Filters (if it is empty the messages won't be filtered)	Schema	Subscription Handler
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
rfq	request_created	-	-	Request
rfq	request_edited	-	-	Request
rfq	request_canceled	-	-	Request
rfq	request_expired	-	-	Request
rfq	quote_created	-	-	Quote
rfq	quote_edited	-	-	Quote
rfq	quote_canceled	-	-	Quote
rfq	quote_expired	-	-	Quote
crypto_prices	update	-	{"symbol":string}	CryptoPrice	CryptoPriceHistorical
clob_user	order	ClobAuth	-	Order
clob_user	trade	ClobAuth	-	Trade
clob_market	price_change	-	["100","200",...]	PriceChanges
clob_market	agg_orderbook	-	["100","200",...]	AggOrderbook	AggOrderbook
clob_market	last_trade_price	-	["100","200",...]	LastTradePrice
clob_market	tick_size_change	-	["100","200",...]	TickSizeChange
clob_market	market_created	-	-	ClobMarket
clob_market	market_resolved	-	-	ClobMarket

Auth

ClobAuth

/**
 * API key credentials for CLOB authentication.
 */
export interface ClobApiKeyCreds {
    /** API key used for authentication */
    key: string;

    /** API secret associated with the key */
    secret: string;

    /** Passphrase required for authentication */
    passphrase: string;
}

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

Message types

Activity

Trade

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

Comments

Comment

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

Reaction

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

RFQ

Request

Name	Type	Description
requestId	string	Unique identifier for the request
proxyAddress	string	User proxy address
market	string	Id of market which is also the CTF condition ID
token	string	ERC1155 token ID of conditional token being traded
complement	string	Complement ERC1155 token ID of conditional token being traded
state	string	Current state of the request
side	string	Indicates buy or sell side
sizeIn	number	Input size of the request
sizeOut	number	Output size of the request
price	number	Price from in/out sizes
expiry	number	Expiry timestamp (UNIX format)

Quote

Name	Type	Description
quoteId	string	Unique identifier for the quote
requestId	string	Associated request identifier
proxyAddress	string	User proxy address
token	string	ERC1155 token ID of conditional token being traded
state	string	Current state of the quote
side	string	Indicates buy or sell side
sizeIn	number	Input size of the quote
sizeOut	number	Output size of the quote
sizeOut	number	Output size of the request
condition	string	Id of market which is also the CTF condition ID
complement	string	Complement ERC1155 token ID of conditional token being traded
expiry	number	Expiry timestamp (UNIX format)

CryptoPrice

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

Filters

• {"symbol":"btcusdt"}
• {"symbol":"ethusdt"}
• {"symbol":"xrpusdt"}
• {"symbol":"solusdt"}

Initial data dump on connection

When the connection is stablished, if a filter is used, the server will dump an initial snapshoot of recent data

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

CLOB User

Order

Name	Type	Description
asset_id	string	Order's ERC1155 token ID of conditional token
created_at	string (timestamp)	Order's creation UNIX timestamp
expiration	string (timestamp)	Order's expiration UNIX timestamp
id	string	Unique order hash identifier
maker_address	string	Maker’s address (funder)
market	string	Condition ID or market identifier
order_type	string	Type of order: GTC, GTD, FOK, FAK
original_size	string	Original size of the order at placement
outcome	string	Order outcome: YES / NO
owner	string	UUID of the order owner
price	string	Order price (e.g., in decimals like 0.5)
side	string	Side of the trade: BUY or SELL
size_matched	string	Amount of order that has been matched
status	string	Status of the order (e.g., MATCHED)
type	string	Type of update: PLACEMENT, CANCELLATION, FILL, etc.

Trade

Name	Type	Description
asset_id	string	ERC1155 token ID of the conditional token involved in the trade
fee_rate_bps	string	Fee rate in basis points (bps)
id	string	Unique identifier for the match record
last_update	string (timestamp)	Last update timestamp (UNIX)
maker_address	string	Maker’s address
maker_orders	array	List of maker orders (see nested schema below)
market	string	Condition ID or market identifier
match_time	string (timestamp)	Match execution timestamp (UNIX)
outcome	string	Outcome of the market: YES / NO
owner	string	UUID of the taker (owner of the matched order)
price	string	Matched price (in decimal format, e.g., 0.5)
side	string	Taker side of the trade: BUY or SELL
size	string	Total matched size
status	string	Status of the match: e.g., MINED
taker_order_id	string	ID of the taker's order
transaction_hash	string	Transaction hash where the match was settled

maker_orders

Name	Type	Description
asset_id	string	ERC1155 token ID of the conditional token of the maker's order
fee_rate_bps	string	Maker's fee rate in basis points
maker_address	string	Maker’s address
matched_amount	string	Amount matched from the maker's order
order_id	string	ID of the maker's order
outcome	string	Outcome targeted by the maker's order (YES / NO)
owner	string	UUID of the maker
price	string	Order price
side	string	Side of the maker: BUY or SELL

CLOB market

PriceChanges

Name	Type	Description
market	string	Condition ID
price_changes	array	Price changes by book
timestamp	string (timestamp)	Timestamp in milliseconds since epoch (UNIX time * 1000)

PriceChange

Name	Type	Description
asset_id	string	Asset identifier
hash	string	Unique hash ID of the book snapshot
price	string	Price quoted (e.g., 0.5)
side	string	Side of the quote: BUY or SELL
size	string	Size or volume available at the quoted price (e.g., 0, 100)
best_ask	string	Best ask price
best_bid	string	Best bid price

AggOrderbook

Name	Type	Description
asks	array	List of ask aggregated orders (sell side), each with price and size
asset_id	string	Asset Id identifier
bids	array	List of aggregated bid orders (buy side), each with price and size
hash	string	Unique hash ID for this orderbook snapshot
market	string	Market or condition ID
min_order_size	string	Minimum allowed order size
neg_risk	boolean	NegRisk or not
tick_size	string	Minimum tick size
timestamp	string (timestamp)	Timestamp in milliseconds since epoch (UNIX time * 1000)

asks/bids scheema

Name	Type	Description
price	string	Price level
size	string	Size at that price

Initial data dump on connection

When the connection is stablished, if a filter is used, the server will dump an initial snapshoot of recent data

LastTradePrice

Name	Type	Description
asset_id	string	Asset Id identifier
fee_rate_bps	string	Fee rate in basis points (bps)
market	string	Market or condition ID
price	string	Trade price (e.g., 0.5)
side	string	Side of the order: BUY or SELL
size	string	Size of the trade

TickSizeChange

Name	Type	Description
market	string	Market or condition ID
asset_id	string	Array of two ERC1155 asset ID
old_tick_size	string	Previous tick size before the change
new_tick_size	string	Updated tick size after the change

ClobMarket

Name	Type	Description
market	string	Market or condition ID
asset_ids	[2]string	Array of two ERC1155 asset ID identifiers associated with market
min_order_size	string	Minimum size allowed for an order
tick_size	string	Minimum allowable price increment
neg_risk	boolean	Indicates if the market is negative risk