gavindiaz/PolymarketDocumentation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Polymarket documentation (2026-02-19)

Browse Source 
- Added new documentation URLs from llms.txt index
- Updated TARGET.md with 244 total documentation pages
- Scraped new pages for trading, concepts, and API reference sections
- Updated changelog and new index pages
This commit is contained in:
AI Agent
2026-02-19 14:31:02 +01:00
parent 81f77eff3c
commit b2a29fe51f
250 changed files with 33306 additions and 9659 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/market-data/fetching-markets.md
+160
View File
@@ -0,0 +1,160 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetching Markets
> Three strategies for discovering and querying markets
<Tip>
Both the events and markets endpoints are paginated. See
[pagination](#pagination) for details.
</Tip>
There are three main strategies for retrieving market data, each optimized for different use cases:
1. **By Slug** — Best for fetching specific individual markets or events
2. **By Tags** — Ideal for filtering markets by category or sport
3. **Via Events Endpoint** — Most efficient for retrieving all active markets
***
## Fetch by Slug
**Use case:** When you need to retrieve a specific market or event that you already know about.
Individual markets and events are best fetched using their unique slug identifier. The slug can be found directly in the Polymarket frontend URL.
### How to Extract the Slug
From any Polymarket URL, the slug is the path segment after `/event/`:
```
https://polymarket.com/event/fed-decision-in-october
↑
Slug: fed-decision-in-october
```
### Examples
```bash theme={null}
# Fetch an event by slug (query parameter)
curl "https://gamma-api.polymarket.com/events?slug=fed-decision-in-october"
# Or use the path endpoint
curl "https://gamma-api.polymarket.com/events/slug/fed-decision-in-october"
```
```bash theme={null}
# Fetch a market by slug (query parameter)
curl "https://gamma-api.polymarket.com/markets?slug=fed-decision-in-october"
# Or use the path endpoint
curl "https://gamma-api.polymarket.com/markets/slug/fed-decision-in-october"
```
***
## Fetch by Tags
**Use case:** When you want to filter markets by category, sport, or topic.
Tags provide a way to categorize and filter markets. You can discover available tags and then use them to filter your requests.
### Discover Available Tags
**General tags:** `GET /tags` (Gamma API)
**Sports tags and metadata:** `GET /sports` (Gamma API)
The `/sports` endpoint returns metadata for sports including tag IDs, images, resolution sources, and series information.
### Filter by Tag
Once you have tag IDs, use the `tag_id` parameter in both events and markets endpoints:
```bash theme={null}
# Fetch events for a specific tag
curl "https://gamma-api.polymarket.com/events?tag_id=100381&limit=10&active=true&closed=false"
```
### Additional Tag Filtering
You can also:
* Use `related_tags=true` to include related tag markets
* Exclude specific tags with `exclude_tag_id`
```bash theme={null}
# Include related tags
curl "https://gamma-api.polymarket.com/events?tag_id=100381&related_tags=true&active=true&closed=false"
```
***
## Fetch All Active Markets
**Use case:** When you need to retrieve all available active markets, typically for broader analysis or market discovery.
The most efficient approach is to use the events endpoint with `active=true&closed=false`, as events contain their associated markets.
```bash theme={null}
curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=100"
```
### Key Parameters
| Parameter | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `order` | Field to order by (`volume_24hr`, `volume`, `liquidity`, `start_date`, `end_date`, `competitive`, `closed_time`) |
| `ascending` | Sort direction (`true` for ascending, `false` for descending). Default: `false` |
| `active` | Filter by active status (`true` for live tradable events) |
| `closed` | Filter by closed status |
| `limit` | Results per page |
| `offset` | Number of results to skip for pagination |
```bash theme={null}
# Get the highest volume active events
curl "https://gamma-api.polymarket.com/events?active=true&closed=false&order=volume_24hr&ascending=false&limit=100"
```
***
## Pagination
All list endpoints return paginated responses with `limit` and `offset` parameters:
```bash theme={null}
# Page 1: First 50 results
curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=50&offset=0"
# Page 2: Next 50 results
curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=50&offset=50"
# Page 3: Next 50 results
curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=50&offset=100"
```
***
## Best Practices
1. **For individual markets:** Use the slug method for direct lookups
2. **For category browsing:** Use tag filtering to reduce API calls
3. **For complete market discovery:** Use the events endpoint with pagination
4. **Always include `active=true&closed=false`** unless you specifically need historical data
5. **Use the events endpoint** and work backwards — events contain their associated markets, reducing the number of API calls needed
***
## Next Steps
<CardGroup cols={2}>
<Card title="API Reference" icon="code" href="/api-reference/introduction">
Full endpoint documentation with parameters and response schemas.
</Card>
<Card title="Subgraph" icon="share-nodes" href="/market-data/subgraph">
Query onchain data directly from the Polymarket subgraph.
</Card>
</CardGroup>
docs/market-data/overview.md
+111
View File
@@ -0,0 +1,111 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Fetch market data with no authentication required
All market data is available through public REST endpoints. No API key, no authentication, no wallet required.
```bash theme={null}
curl "https://gamma-api.polymarket.com/events?limit=5"
```
***
## Data Model
Polymarket structures data using two organizational models. The most fundamental element is always markets—events simply provide additional organization.
<Steps>
<Step title="Event">
A top-level object representing a question (e.g., "Who will win the 2024
Presidential Election?"). Contains one or more markets.
</Step>
<Step title="Market">
A specific tradable binary outcome within an event. Maps to a pair of CLOB
token IDs, a market address, a question ID, and a condition ID.
</Step>
</Steps>
### Single-Market Events vs Multi-Market Events
| Type | Example |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| Single-market event | "Will Bitcoin reach \$100k?" → 1 market (Yes/No) |
| Multi-market event | "Where will Barron Trump attend College?" → Markets for Georgetown, NYU, UPenn, Harvard, Other |
### Outcomes and Prices
Each market has `outcomes` and `outcomePrices` arrays that map 1:1. Prices represent implied probabilities:
```json theme={null}
{
"outcomes": "[\"Yes\", \"No\"]",
"outcomePrices": "[\"0.20\", \"0.80\"]"
}
// Index 0: "Yes" → 0.20 (20% probability)
// Index 1: "No" → 0.80 (80% probability)
```
<Info>Markets can be traded via the CLOB if `enableOrderBook` is `true`.</Info>
***
## Available Data
Endpoints are split across three APIs. See the [API Reference](/api-reference/introduction) for full endpoint documentation with parameters and response schemas.
### Gamma API (`gamma-api.polymarket.com`) — Events, Markets & Discovery
| Endpoint | Description |
| -------------------- | ------------------------------------------- |
| `GET /events` | List events with filtering and pagination |
| `GET /events/{id}` | Get a single event by ID |
| `GET /markets` | List markets with filtering and pagination |
| `GET /markets/{id}` | Get a single market by ID |
| `GET /public-search` | Search across events, markets, and profiles |
| `GET /tags` | Ranked tags/categories |
| `GET /series` | Series (grouped events) |
| `GET /sports` | Sports metadata |
| `GET /teams` | Teams |
### CLOB API (`clob.polymarket.com`) — Prices & Orderbooks
| Endpoint | Description |
| --------------------- | --------------------------------- |
| `GET /price` | Price for a single token |
| `GET /prices` | Prices for multiple tokens |
| `GET /book` | Order book for a token |
| `POST /books` | Order books for multiple tokens |
| `GET /prices-history` | Historical price data for a token |
| `GET /midpoint` | Midpoint price for a token |
| `GET /spread` | Spread for a token |
### Data API (`data-api.polymarket.com`) — Positions, Trades & Analytics
| Endpoint | Description |
| -------------------------------------- | ---------------------------- |
| `GET /positions?user={address}` | Current positions for a user |
| `GET /closed-positions?user={address}` | Closed positions for a user |
| `GET /activity?user={address}` | Onchain activity for a user |
| `GET /value?user={address}` | Total position value |
| `GET /oi` | Open interest for a market |
| `GET /holders` | Top holders of a market |
| `GET /trades` | Trade history |
***
## Next Steps
<CardGroup cols={2}>
<Card title="Fetching Markets" icon="magnifying-glass" href="/market-data/fetching-markets">
Three strategies for discovering and querying markets.
</Card>
<Card title="API Reference" icon="code" href="/api-reference/introduction">
Full endpoint documentation with parameters and response schemas.
</Card>
</CardGroup>
docs/market-data/subgraph.md
+97
View File
@@ -0,0 +1,97 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Subgraph
> Query onchain Polymarket data using GraphQL
Polymarket's subgraphs provide indexed onchain data via GraphQL. Use them to query positions, volume, liquidity data, orders, activity, and market data.
## Available Subgraphs
| Subgraph | Description | Endpoint |
| ----------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Positions** | User token balances | [GraphQL Playground](https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/positions-subgraph/0.0.7/gn) |
| **Orders** | Order book and trade events | [GraphQL Playground](https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/orderbook-subgraph/0.0.1/gn) |
| **Activity** | Splits, merges, redemptions | [GraphQL Playground](https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/activity-subgraph/0.0.4/gn) |
| **Open Interest** | Market and global OI | [GraphQL Playground](https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/oi-subgraph/0.0.6/gn) |
| **PNL** | User position P\&L | [GraphQL Playground](https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/pnl-subgraph/0.0.14/gn) |
<Note>
Subgraphs are hosted by [Goldsky](https://goldsky.com). Each endpoint includes
an interactive GraphQL playground for exploring the schema.
</Note>
## Querying
Send GraphQL queries via POST request to any subgraph endpoint.
```bash theme={null}
curl -X POST \
https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/orderbook-subgraph/0.0.1/gn \
-H "Content-Type: application/json" \
-d '{
"query": "query MyQuery { orderbooks { id tradesQuantity } }"
}'
```
## Schema Reference
### Positions
| Query | Description |
| ---------------------------------------- | ------------------------------ |
| `userBalance` / `userBalances` | User token balances |
| `netUserBalance` / `netUserBalances` | Aggregated net balances |
| `tokenIdCondition` / `tokenIdConditions` | Token ID to condition mappings |
| `condition` / `conditions` | Market conditions |
### Orders
| Query | Description |
| ---------------------------------------------- | ----------------------- |
| `marketData` / `marketDatas` | Market-level data |
| `orderFilledEvent` / `orderFilledEvents` | Order fill events |
| `ordersMatchedEvent` / `ordersMatchedEvents` | Order match events |
| `orderbook` / `orderbooks` | Orderbook state |
| `ordersMatchedGlobal` / `ordersMatchedGlobals` | Global match statistics |
### Activity
| Query | Description |
| ------------------------------------------------------ | -------------------- |
| `split` / `splits` | USDC to token splits |
| `merge` / `merges` | Token to USDC merges |
| `redemption` / `redemptions` | Position redemptions |
| `negRiskConversion` / `negRiskConversions` | Neg risk conversions |
| `negRiskEvent` / `negRiskEvents` | Neg risk event data |
| `fixedProductMarketMaker` / `fixedProductMarketMakers` | FPMM data |
| `position` / `positions` | Position records |
| `condition` / `conditions` | Market conditions |
### Open Interest
| Query | Description |
| -------------------------------------------- | ------------------------ |
| `condition` / `conditions` | Market conditions |
| `negRiskEvent` / `negRiskEvents` | Neg risk event data |
| `marketOpenInterest` / `marketOpenInterests` | Per-market open interest |
| `globalOpenInterest` / `globalOpenInterests` | Global open interest |
### PNL
| Query | Description |
| -------------------------------- | ------------------------------- |
| `userPosition` / `userPositions` | User position P\&L data |
| `negRiskEvent` / `negRiskEvents` | Neg risk event data |
| `condition` / `conditions` | Market conditions |
| `fpmm` / `fpmms` | Fixed product market maker data |
## Source Code
The subgraph is open source. Review the schema and mappings on GitHub:
<Card title="polymarket-subgraph" icon="github" href="https://github.com/Polymarket/polymarket-subgraph">
View source code, schema definitions, and deployment configuration.
</Card>
docs/market-data/websocket/market-channel.md
+201
View File
@@ -0,0 +1,201 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Market Channel
> Real-time orderbook, price, and trade data
Public channel for market data updates (level 2 price data). Subscribe with asset IDs to receive orderbook snapshots, price changes, trade executions, and market events.
## Endpoint
```
wss://ws-subscriptions-clob.polymarket.com/ws/market
```
## Subscription
```json theme={null}
{
"assets_ids": ["<token_id_1>", "<token_id_2>"],
"type": "market",
"custom_feature_enabled": true
}
```
Set `custom_feature_enabled: true` to receive `best_bid_ask`, `new_market`, and `market_resolved` events.
## Message Types
Each message includes an `event_type` field identifying the type.
### book
Emitted when first subscribed to a market and when there is a trade that affects the book.
```json theme={null}
{
"event_type": "book",
"asset_id": "65818619657568813474341868652308942079804919287380422192892211131408793125422",
"market": "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
"bids": [
{ "price": ".48", "size": "30" },
{ "price": ".49", "size": "20" },
{ "price": ".50", "size": "15" }
],
"asks": [
{ "price": ".52", "size": "25" },
{ "price": ".53", "size": "60" },
{ "price": ".54", "size": "10" }
],
"timestamp": "123456789000",
"hash": "0x0...."
}
```
### price\_change
Emitted when a new order is placed or an order is cancelled.
```json theme={null}
{
"market": "0x5f65177b394277fd294cd75650044e32ba009a95022d88a0c1d565897d72f8f1",
"price_changes": [
{
"asset_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
"price": "0.5",
"size": "200",
"side": "BUY",
"hash": "56621a121a47ed9333273e21c83b660cff37ae50",
"best_bid": "0.5",
"best_ask": "1"
},
{
"asset_id": "52114319501245915516055106046884209969926127482827954674443846427813813222426",
"price": "0.5",
"size": "200",
"side": "SELL",
"hash": "1895759e4df7a796bf4f1c5a5950b748306923e2",
"best_bid": "0",
"best_ask": "0.5"
}
],
"timestamp": "1757908892351",
"event_type": "price_change"
}
```
A `size` of `"0"` means the price level has been removed from the book.
### tick\_size\_change
Emitted when the minimum tick size of a market changes. This happens when the book's price reaches the limits: price > 0.96 or price \< 0.04.
```json theme={null}
{
"event_type": "tick_size_change",
"asset_id": "65818619657568813474341868652308942079804919287380422192892211131408793125422",
"market": "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
```
### last\_trade\_price
Emitted when a maker and taker order is matched, creating a trade event.
```json theme={null}
{
"asset_id": "114122071509644379678018727908709560226618148003371446110114509806601493071694",
"event_type": "last_trade_price",
"fee_rate_bps": "0",
"market": "0x6a67b9d828d53862160e470329ffea5246f338ecfffdf2cab45211ec578b0347",
"price": "0.456",
"side": "BUY",
"size": "219.217767",
"timestamp": "1750428146322"
}
```
### best\_bid\_ask
<Note>Requires `custom_feature_enabled: true`.</Note>
Emitted when the best bid or ask prices for a market change.
```json theme={null}
{
"event_type": "best_bid_ask",
"market": "0x0005c0d312de0be897668695bae9f32b624b4a1ae8b140c49f08447fcc74f442",
"asset_id": "85354956062430465315924116860125388538595433819574542752031640332592237464430",
"best_bid": "0.73",
"best_ask": "0.77",
"spread": "0.04",
"timestamp": "1766789469958"
}
```
### new\_market
<Note>Requires `custom_feature_enabled: true`.</Note>
Emitted when a new market is created.
```json theme={null}
{
"id": "1031769",
"question": "Will NVIDIA (NVDA) close above $240 end of January?",
"market": "0x311d0c4b6671ab54af4970c06fcf58662516f5168997bdda209ec3db5aa6b0c1",
"slug": "nvda-above-240-on-january-30-2026",
"description": "This market will resolve to \"Yes\" if the official closing price...",
"assets_ids": [
"76043073756653678226373981964075571318267289248134717369284518995922789326425",
"31690934263385727664202099278545688007799199447969475608906331829650099442770"
],
"outcomes": ["Yes", "No"],
"event_message": {
"id": "125819",
"ticker": "nvda-above-in-january-2026",
"slug": "nvda-above-in-january-2026",
"title": "Will NVIDIA (NVDA) close above ___ end of January?",
"description": "This market will resolve to \"Yes\" if the official closing price..."
},
"timestamp": "1766790415550",
"event_type": "new_market"
}
```
### market\_resolved
<Note>Requires `custom_feature_enabled: true`.</Note>
Emitted when a market is resolved.
```json theme={null}
{
"id": "1031769",
"question": "Will NVIDIA (NVDA) close above $240 end of January?",
"market": "0x311d0c4b6671ab54af4970c06fcf58662516f5168997bdda209ec3db5aa6b0c1",
"slug": "nvda-above-240-on-january-30-2026",
"description": "This market will resolve to \"Yes\" if the official closing price...",
"assets_ids": [
"76043073756653678226373981964075571318267289248134717369284518995922789326425",
"31690934263385727664202099278545688007799199447969475608906331829650099442770"
],
"outcomes": ["Yes", "No"],
"winning_asset_id": "76043073756653678226373981964075571318267289248134717369284518995922789326425",
"winning_outcome": "Yes",
"event_message": {
"id": "125819",
"ticker": "nvda-above-in-january-2026",
"slug": "nvda-above-in-january-2026",
"title": "Will NVIDIA (NVDA) close above ___ end of January?",
"description": "This market will resolve to \"Yes\" if the official closing price..."
},
"timestamp": "1766790415550",
"event_type": "market_resolved"
}
```
docs/market-data/websocket/overview.md
+181
View File
@@ -0,0 +1,181 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Real-time market data and trading updates via WebSocket
Polymarket provides WebSocket channels for near real-time streaming of orderbook data, trades, and personal order activity. There are four available channels: `market`, `user`, `sports`, and `RTDS` (Real-Time Data Socket).
## Channels
| Channel | Endpoint | Auth |
| ----------------------------------- | ------------------------------------------------------ | -------- |
| Market | `wss://ws-subscriptions-clob.polymarket.com/ws/market` | No |
| User | `wss://ws-subscriptions-clob.polymarket.com/ws/user` | Yes |
| Sports | `wss://sports-api.polymarket.com/ws` | No |
| [RTDS](/market-data/websocket/rtds) | `wss://ws-live-data.polymarket.com` | Optional |
### Market Channel
| Type | Description | Custom Feature |
| ------------------ | ----------------------- | -------------- |
| `book` | Full orderbook snapshot | No |
| `price_change` | Price level updates | No |
| `tick_size_change` | Tick size changes | No |
| `last_trade_price` | Trade executions | No |
| `best_bid_ask` | Best prices update | Yes |
| `new_market` | New market created | Yes |
| `market_resolved` | Market resolution | Yes |
Types marked "Custom Feature" require `custom_feature_enabled: true` in your subscription.
### User Channel
| Type | Description |
| ------- | --------------------------------------------- |
| `trade` | Trade lifecycle updates (MATCHED → CONFIRMED) |
| `order` | Order placements, updates, and cancellations |
### Sports
| Type | Description |
| -------------- | ------------------------------------- |
| `sport_result` | Live game scores, periods, and status |
## Subscribing
Send a subscription message after connecting to specify which data you want to receive.
### Market Channel
```json theme={null}
{
"assets_ids": [
"21742633143463906290569050155826241533067272736897614950488156847949938836455",
"48331043336612883890938759509493159234755048973500640148014422747788308965732"
],
"type": "market",
"custom_feature_enabled": true
}
```
| Field | Type | Description |
| ------------------------ | --------- | ----------------------------------------------------------------- |
| `assets_ids` | string\[] | Token IDs to subscribe to |
| `type` | string | Channel identifier |
| `custom_feature_enabled` | boolean | Enable `best_bid_ask`, `new_market`, and `market_resolved` events |
### User Channel
```json theme={null}
{
"auth": {
"apiKey": "your-api-key",
"secret": "your-api-secret",
"passphrase": "your-passphrase"
},
"markets": ["0x1234...condition_id"],
"type": "user"
}
```
<Note>
The `auth` fields (`apiKey`, `secret`, `passphrase`) are **only required for
the user channel**. For the market channel, these fields are optional and can
be omitted.
</Note>
| Field | Type | Description |
| --------- | --------- | -------------------------------------------------- |
| `auth` | object | API credentials (`apiKey`, `secret`, `passphrase`) |
| `markets` | string\[] | Condition IDs to receive events for |
| `type` | string | Channel identifier |
<Note>
The user channel subscribes by **condition IDs** (market identifiers), not
asset IDs. Each market has one condition ID but two asset IDs (Yes and No
tokens).
</Note>
### Sports Channel
No subscription message required. Connect and start receiving data for all active sports events.
## Dynamic Subscription
Modify subscriptions without reconnecting.
### Subscribe to more assets
```json theme={null}
{
"assets_ids": ["new_asset_id_1", "new_asset_id_2"],
"operation": "subscribe",
"custom_feature_enabled": true
}
```
### Unsubscribe from assets
```json theme={null}
{
"assets_ids": ["asset_id_to_remove"],
"operation": "unsubscribe"
}
```
For the user channel, use `markets` instead of `assets_ids`:
```json theme={null}
{
"markets": ["0x1234...condition_id"],
"operation": "subscribe"
}
```
## Heartbeats
### Market & User Channels
Send `PING` every 10 seconds. The server responds with `PONG`.
```
PING
```
### Sports Channel
The server sends `ping` every 5 seconds. Respond with `pong` within 10 seconds.
```
pong
```
<Warning>
If you don't respond to the server's ping within 10 seconds, the connection
will be closed.
</Warning>
## Troubleshooting
<Accordion title="Connection closes immediately after opening">
Send a valid subscription message immediately after connecting. The server may
close connections that don't subscribe within a timeout period.
</Accordion>
<Accordion title="Connection drops after ~10 seconds">
You're not sending heartbeats. Send `PING` every 10 seconds for market/user
channels, or respond to server `ping` with `pong` for the sports channel.
</Accordion>
<Accordion title="Not receiving any messages">
1. Verify your asset IDs or condition IDs are correct 2. Check that the
markets are active (not resolved) 3. Set `custom_feature_enabled: true` if
expecting `best_bid_ask`, `new_market`, or `market_resolved` events
</Accordion>
<Accordion title="Authentication failed (user channel)">
Verify your API credentials are correct and haven't expired.
</Accordion>
docs/market-data/websocket/rtds.md
+361
View File
@@ -0,0 +1,361 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Real-Time Data Socket
> Stream comments and crypto prices via WebSocket
The Polymarket Real-Time Data Socket (RTDS) is a WebSocket-based streaming service that provides real-time updates for **comments** and **crypto prices**.
<Card title="TypeScript client" icon="github" href="https://github.com/Polymarket/real-time-data-client">
Official RTDS TypeScript client (`real-time-data-client`).
</Card>
## Endpoint
```
wss://ws-live-data.polymarket.com
```
Some user-specific streams may require `gamma_auth` with your wallet address.
## Subscribing
Send a JSON message to subscribe to data streams:
```json theme={null}
{
"action": "subscribe",
"subscriptions": [
{
"topic": "topic_name",
"type": "message_type",
"filters": "optional_filter_string",
"gamma_auth": {
"address": "wallet_address"
}
}
]
}
```
To unsubscribe, send the same structure with `"action": "unsubscribe"`.
Subscriptions can be added, removed, and modified without disconnecting. Send `PING` messages every 5 seconds to maintain the connection.
<Note>Only the subscription types documented below are supported.</Note>
## Message Structure
All messages follow this structure:
```json theme={null}
{
"topic": "string",
"type": "string",
"timestamp": "number",
"payload": "object"
}
```
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------------------------- |
| `topic` | string | The subscription topic (e.g., `crypto_prices`, `comments`) |
| `type` | string | The message type/event (e.g., `update`, `reaction_created`) |
| `timestamp` | number | Unix timestamp in milliseconds when the message was sent |
| `payload` | object | Event-specific data object |
## Crypto Prices
Real-time cryptocurrency price data from two sources: **Binance** and **Chainlink**. No authentication required.
### Binance Source (`crypto_prices`)
Subscribe to all symbols:
```json theme={null}
{
"action": "subscribe",
"subscriptions": [
{
"topic": "crypto_prices",
"type": "update"
}
]
}
```
Subscribe to specific symbols with a comma-separated filter:
```json theme={null}
{
"action": "subscribe",
"subscriptions": [
{
"topic": "crypto_prices",
"type": "update",
"filters": "solusdt,btcusdt,ethusdt"
}
]
}
```
Symbols use lowercase concatenated format (e.g., `solusdt`, `btcusdt`).
**Solana price update:**
```json theme={null}
{
"topic": "crypto_prices",
"type": "update",
"timestamp": 1753314064237,
"payload": {
"symbol": "solusdt",
"timestamp": 1753314064213,
"value": 189.55
}
}
```
**Bitcoin price update:**
```json theme={null}
{
"topic": "crypto_prices",
"type": "update",
"timestamp": 1753314088421,
"payload": {
"symbol": "btcusdt",
"timestamp": 1753314088395,
"value": 67234.50
}
}
```
### Chainlink Source (`crypto_prices_chainlink`)
<Tip>
**Trading 15m Crypto Markets?** Get a sponsored Chainlink API key with onboarding support from Chainlink. Fill out [this form](https://pm-ds-request.streams.chain.link/).
</Tip>
Subscribe to all symbols:
```json theme={null}
{
"action": "subscribe",
"subscriptions": [
{
"topic": "crypto_prices_chainlink",
"type": "*",
"filters": ""
}
]
}
```
Subscribe to a specific symbol with a JSON filter:
```json theme={null}
{
"action": "subscribe",
"subscriptions": [
{
"topic": "crypto_prices_chainlink",
"type": "*",
"filters": "{\"symbol\":\"eth/usd\"}"
}
]
}
```
Symbols use slash-separated format (e.g., `eth/usd`, `btc/usd`).
**Ethereum price update:**
```json theme={null}
{
"topic": "crypto_prices_chainlink",
"type": "update",
"timestamp": 1753314064237,
"payload": {
"symbol": "eth/usd",
"timestamp": 1753314064213,
"value": 3456.78
}
}
```
**Bitcoin price update:**
```json theme={null}
{
"topic": "crypto_prices_chainlink",
"type": "update",
"timestamp": 1753314088421,
"payload": {
"symbol": "btc/usd",
"timestamp": 1753314088395,
"value": 67234.50
}
}
```
### Price Payload Fields
| Field | Type | Description |
| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbol` | string | Trading pair symbol. **Binance**: lowercase concatenated (e.g., `solusdt`, `btcusdt`). **Chainlink**: slash-separated (e.g., `eth/usd`, `btc/usd`) |
| `timestamp` | number | When the price was recorded, in Unix milliseconds |
| `value` | number | Current price value in the quote currency |
### Supported Symbols
**Binance Source** — lowercase concatenated format:
* `btcusdt` — Bitcoin to USDT
* `ethusdt` — Ethereum to USDT
* `solusdt` — Solana to USDT
* `xrpusdt` — XRP to USDT
**Chainlink Source** — slash-separated format:
* `btc/usd` — Bitcoin to USD
* `eth/usd` — Ethereum to USD
* `sol/usd` — Solana to USD
* `xrp/usd` — XRP to USD
## Comments
Real-time comment events on the Polymarket platform, including new comments, replies, reactions, and removals. May require Gamma authentication for user-specific data.
### Subscribe
```json theme={null}
{
"action": "subscribe",
"subscriptions": [
{
"topic": "comments",
"type": "comment_created"
}
]
}
```
### Message Types
| Type | Description |
| ------------------ | ------------------------------------- |
| `comment_created` | A user creates a new comment or reply |
| `comment_removed` | A comment is removed or deleted |
| `reaction_created` | A user adds a reaction to a comment |
| `reaction_removed` | A reaction is removed from a comment |
### comment\_created
Emitted when a user posts a new comment or replies to an existing one.
```json theme={null}
{
"topic": "comments",
"type": "comment_created",
"timestamp": 1753454975808,
"payload": {
"body": "That's a good point about the definition.",
"createdAt": "2025-07-25T14:49:35.801298Z",
"id": "1763355",
"parentCommentID": "1763325",
"parentEntityID": 18396,
"parentEntityType": "Event",
"profile": {
"baseAddress": "0xce533188d53a16ed580fd5121dedf166d3482677",
"displayUsernamePublic": true,
"name": "salted.caramel",
"proxyWallet": "0x4ca749dcfa93c87e5ee23e2d21ff4422c7a4c1ee",
"pseudonym": "Adored-Disparity"
},
"reactionCount": 0,
"replyAddress": "0x0bda5d16f76cd1d3485bcc7a44bc6fa7db004cdd",
"reportCount": 0,
"userAddress": "0xce533188d53a16ed580fd5121dedf166d3482677"
}
}
```
A reply to the above comment — note `parentCommentID` references the parent:
```json theme={null}
{
"topic": "comments",
"type": "comment_created",
"timestamp": 1753454985123,
"payload": {
"body": "I agree, the resolution criteria should be clearer.",
"createdAt": "2025-07-25T14:49:45.120000Z",
"id": "1763356",
"parentCommentID": "1763355",
"parentEntityID": 18396,
"parentEntityType": "Event",
"profile": {
"baseAddress": "0x1234567890abcdef1234567890abcdef12345678",
"displayUsernamePublic": true,
"name": "trader",
"proxyWallet": "0x9876543210fedcba9876543210fedcba98765432",
"pseudonym": "Bright-Analysis"
},
"reactionCount": 0,
"replyAddress": "0x0bda5d16f76cd1d3485bcc7a44bc6fa7db004cdd",
"reportCount": 0,
"userAddress": "0x1234567890abcdef1234567890abcdef12345678"
}
}
```
### Comment Payload Fields
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------- |
| `body` | string | The text content of the comment |
| `createdAt` | string | ISO 8601 timestamp when the comment was created |
| `id` | string | Unique identifier for this comment |
| `parentCommentID` | string | ID of the parent comment if this is a reply (null for top-level comments) |
| `parentEntityID` | number | ID of the parent entity (event, market, etc.) |
| `parentEntityType` | string | Type of parent entity (`Event`, `Market`) |
| `profile` | object | Profile information of the comment author |
| `reactionCount` | number | Current number of reactions on this comment |
| `replyAddress` | string | Polygon address for replies (may differ from userAddress) |
| `reportCount` | number | Current number of reports on this comment |
| `userAddress` | string | Polygon address of the comment author |
### Profile Object Fields
| Field | Type | Description |
| ----------------------- | ------- | ------------------------------------------ |
| `baseAddress` | string | User profile address |
| `displayUsernamePublic` | boolean | Whether the username is displayed publicly |
| `name` | string | User's display name |
| `proxyWallet` | string | Proxy wallet address used for transactions |
| `pseudonym` | string | Generated pseudonym for the user |
### Comment Hierarchy
Comments support nested threading:
* **Top-level comments**: `parentCommentID` is null or empty
* **Reply comments**: `parentCommentID` contains the ID of the parent comment
* All comments are associated with a `parentEntityID` and `parentEntityType` (`Event` or `Market`)
## Troubleshooting
<Accordion title="Connection drops unexpectedly">
Send `PING` messages every 5 seconds to keep the connection alive. Connection errors will trigger automatic reconnection attempts.
</Accordion>
<Accordion title="Not receiving messages after subscribing">
Verify your subscription message is valid JSON with the correct `action`, `topic`, and `type` fields. Invalid subscription messages may result in connection closure.
</Accordion>
<Accordion title="Authentication failures">
If subscribing to user-specific streams, ensure your `gamma_auth` object includes a valid wallet `address`. Authentication failures will prevent subscription to protected topics.
</Accordion>
docs/market-data/websocket/sports.md
+215
View File
@@ -0,0 +1,215 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sports WebSocket
> Live sports scores and game state
The Sports WebSocket provides real-time sports results updates, including scores, periods, and game status. No authentication required.
## Endpoint
```
wss://sports-api.polymarket.com/ws
```
No subscription message required — connect and start receiving data for all active sports events.
## Heartbeat
The server sends `ping` every 5 seconds. Respond with `pong` within 10 seconds or the connection will close.
```javascript theme={null}
ws.onmessage = (event) => {
if (event.data === "ping") {
ws.send("pong");
return;
}
// Handle JSON messages...
};
```
## Message Type
Each message is a JSON object with game state fields.
### sport\_result
Emitted when:
* A match goes live
* The score changes
* The period changes (e.g., halftime, overtime)
* A match ends
* Possession changes (NFL and CFB only)
**NFL (in progress):**
```json theme={null}
{
"gameId": 19439,
"leagueAbbreviation": "nfl",
"slug": "nfl-lac-buf-2025-01-26",
"homeTeam": "LAC",
"awayTeam": "BUF",
"status": "InProgress",
"score": "3-16",
"period": "Q4",
"elapsed": "5:18",
"live": true,
"ended": false,
"turn": "lac"
}
```
**Esports — CS2 (finished):**
```json theme={null}
{
"gameId": 1317359,
"leagueAbbreviation": "cs2",
"slug": "cs2-arcred-the-glecs-2025-07-20",
"homeTeam": "ARCRED",
"awayTeam": "The glecs",
"status": "finished",
"score": "000-000|2-0|Bo3",
"period": "2/3",
"live": false,
"ended": true,
"finished_timestamp": "2025-07-20T18:30:00.000Z"
}
```
The `finished_timestamp` field is an ISO 8601 timestamp only present when `ended: true`.
The `slug` field follows the format `{league}-{team1}-{team2}-{date}` (e.g., `nfl-buf-kc-2025-01-26`).
## Period Values
| Period | Description |
| ---------------------- | --------------------------------------- |
| `1H` | First half |
| `2H` | Second half |
| `1Q`, `2Q`, `3Q`, `4Q` | Quarters (NFL, NBA) |
| `HT` | Halftime |
| `FT` | Full time (match ended in regulation) |
| `FT OT` | Full time with overtime |
| `FT NR` | Full time, no result (draw or canceled) |
| `End 1`, `End 2`, ... | End of inning (MLB) |
| `1/3`, `2/3`, `3/3` | Map number in Bo3 series (Esports) |
| `1/5`, `2/5`, ... | Map number in Bo5 series (Esports) |
## Game Status Values
Game status values vary by sport:
### NFL
| Status | Description |
| -------------- | ---------------------------- |
| `Scheduled` | Game not yet started |
| `InProgress` | Game currently playing |
| `Final` | Game completed in regulation |
| `F/OT` | Final after overtime |
| `Suspended` | Game suspended |
| `Postponed` | Game postponed |
| `Delayed` | Game delayed |
| `Canceled` | Game canceled |
| `Forfeit` | Game forfeited |
| `NotNecessary` | Scheduled, but not needed |
### NHL
| Status | Description |
| -------------- | ---------------------------- |
| `Scheduled` | Game not yet started |
| `InProgress` | Game currently playing |
| `Final` | Game completed in regulation |
| `F/OT` | Final after overtime |
| `F/SO` | Final after shootout |
| `Suspended` | Game suspended |
| `Postponed` | Game postponed |
| `Delayed` | Game delayed |
| `Canceled` | Game canceled |
| `Forfeit` | Game forfeited |
| `NotNecessary` | Scheduled, but not needed |
### MLB
| Status | Description |
| -------------- | ------------------------- |
| `Scheduled` | Game not yet started |
| `InProgress` | Game currently playing |
| `Final` | Game completed |
| `Suspended` | Game suspended |
| `Delayed` | Game delayed |
| `Postponed` | Game postponed |
| `Canceled` | Game canceled |
| `Forfeit` | Game forfeited |
| `NotNecessary` | Scheduled, but not needed |
### NBA / CBB
| Status | Description |
| -------------- | ------------------------- |
| `Scheduled` | Game not yet started |
| `InProgress` | Game currently playing |
| `Final` | Game completed |
| `F/OT` | Final after overtime |
| `Suspended` | Game suspended |
| `Postponed` | Game postponed |
| `Delayed` | Game delayed |
| `Canceled` | Game canceled |
| `Forfeit` | Game forfeited |
| `NotNecessary` | Scheduled, but not needed |
### CFB
| Status | Description |
| ------------ | ---------------------- |
| `Scheduled` | Game not yet started |
| `InProgress` | Game currently playing |
| `Final` | Game completed |
| `F/OT` | Final after overtime |
| `Suspended` | Game suspended |
| `Postponed` | Game postponed |
| `Delayed` | Game delayed |
| `Canceled` | Game canceled |
| `Forfeit` | Game forfeited |
### Soccer
| Status | Description |
| ----------------- | ------------------------------------ |
| `Scheduled` | Game not yet started |
| `InProgress` | Game currently playing |
| `Break` | Halftime or other break |
| `Suspended` | Game suspended |
| `PenaltyShootout` | Penalty shootout in progress |
| `Final` | Game completed |
| `Awarded` | Result awarded due to ruling/forfeit |
| `Postponed` | Game postponed |
| `Canceled` | Game canceled |
### Esports
| Status | Description |
| ------------- | ----------------------- |
| `not_started` | Match not yet started |
| `running` | Match currently playing |
| `finished` | Match completed |
| `postponed` | Match postponed |
| `canceled` | Match canceled |
### Tennis
| Status | Description |
| ------------ | ----------------------- |
| `scheduled` | Match not yet started |
| `inprogress` | Match currently playing |
| `suspended` | Match suspended |
| `finished` | Match completed |
| `postponed` | Match postponed |
| `cancelled` | Match canceled |