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

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.github/workflows		.github/workflows
.vscode		.vscode
examples		examples
src		src
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

License

Polymarket/real-time-data-client

Folders and files

Latest commit

History

Repository files navigation

Real time data client

How to use it

How to subscribe and unsubscribe from messages

Subscribe

Unsubscribe

Disconnect

Messages hierarchy

Auth

ClobAuth

Message types

Activity

Trade

Comments

Comment

Reaction

RFQ

Request

Quote

CryptoPrice

Filters

Initial data dump on connection

CLOB User

Order

Trade

maker_orders

CLOB market

PriceChanges

PriceChange

AggOrderbook

asks/bids scheema

Initial data dump on connection

LastTradePrice

TickSizeChange

ClobMarket

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

`maker_orders`

`asks`/`bids` scheema

Packages