Update Polymarket documentation (2026-02-19)
- 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
@@ -2,15 +2,40 @@
|
||||
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Message Format
|
||||
# Sports WebSocket
|
||||
|
||||
> Structure of sports result update messages
|
||||
> Live sports scores and game state
|
||||
|
||||
Once connected to the Sports WebSocket, clients receive JSON messages whenever a sports event updates. Messages are broadcast to all connected clients automatically.
|
||||
The Sports WebSocket provides real-time sports results updates, including scores, periods, and game status. No authentication required.
|
||||
|
||||
***
|
||||
## Endpoint
|
||||
|
||||
## sport\_result Message
|
||||
```
|
||||
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:
|
||||
|
||||
@@ -20,68 +45,13 @@ Emitted when:
|
||||
* A match ends
|
||||
* Possession changes (NFL and CFB only)
|
||||
|
||||
### Structure
|
||||
|
||||
<ParamField path="gameId" type="number">
|
||||
Unique identifier for the game
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="leagueAbbreviation" type="string">
|
||||
League identifier (e.g., `"nfl"`, `"nba"`, `"cs2"`)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="homeTeam" type="string">
|
||||
Home team name or abbreviation
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="awayTeam" type="string">
|
||||
Away team name or abbreviation
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="status" type="string">
|
||||
Game status (e.g., `"InProgress"`, `"finished"`)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="live" type="boolean">
|
||||
`true` if the match is currently in progress
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="ended" type="boolean">
|
||||
`true` if the match has concluded
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="score" type="string">
|
||||
Current score (format varies by sport)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="period" type="string">
|
||||
Current period (e.g., `"Q4"`, `"2H"`, `"2/3"`)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="elapsed" type="string">
|
||||
Time elapsed in current period (e.g., `"05:09"`)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="finishedTimestamp" type="string">
|
||||
Timestamp when the match ended (only present when `ended: true`)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="turn" type="string">
|
||||
Team abbreviation with possession (NFL/CFB only)
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
The `turn` field is only present for NFL and CFB games and indicates which team currently has the ball.
|
||||
</Note>
|
||||
|
||||
### Example Messages
|
||||
|
||||
**NFL (in progress):**
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"gameId": 19439,
|
||||
"leagueAbbreviation": "nfl",
|
||||
"slug": "nfl-lac-buf-2025-01-26",
|
||||
"homeTeam": "LAC",
|
||||
"awayTeam": "BUF",
|
||||
"status": "InProgress",
|
||||
@@ -94,39 +64,27 @@ Emitted when:
|
||||
}
|
||||
```
|
||||
|
||||
**Esports - CS2 (finished):**
|
||||
**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
|
||||
"ended": true,
|
||||
"finished_timestamp": "2025-07-20T18:30:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
***
|
||||
The `finished_timestamp` field is an ISO 8601 timestamp only present when `ended: true`.
|
||||
|
||||
## Slug Format
|
||||
|
||||
The `slug` field follows a consistent naming convention:
|
||||
|
||||
```
|
||||
{league}-{team1}-{team2}-{date}
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
* `nfl-buf-kc-2025-01-26` — NFL: Buffalo Bills vs Kansas City Chiefs
|
||||
* `nba-lal-bos-2025-02-15` — NBA: LA Lakers vs Boston Celtics
|
||||
* `mlb-nyy-bos-2025-04-01` — MLB: NY Yankees vs Boston Red Sox
|
||||
|
||||
***
|
||||
The `slug` field follows the format `{league}-{team1}-{team2}-{date}` (e.g., `nfl-buf-kc-2025-01-26`).
|
||||
|
||||
## Period Values
|
||||
|
||||
@@ -139,25 +97,119 @@ The `slug` field follows a consistent naming convention:
|
||||
| `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`, etc. | End of inning (MLB) |
|
||||
| `End 1`, `End 2`, ... | End of inning (MLB) |
|
||||
| `1/3`, `2/3`, `3/3` | Map number in Bo3 series (Esports) |
|
||||
| `1/5`, `2/5`, etc. | Map number in Bo5 series (Esports) |
|
||||
| `1/5`, `2/5`, ... | Map number in Bo5 series (Esports) |
|
||||
|
||||
***
|
||||
## Game Status Values
|
||||
|
||||
## Handling Updates
|
||||
Game status values vary by sport:
|
||||
|
||||
When processing messages, use the `gameId` field as the unique identifier to update your local state:
|
||||
### NFL
|
||||
|
||||
```javascript theme={null}
|
||||
// Update or insert based on gameId
|
||||
setSportsData(prev => {
|
||||
const existing = prev.find(item => item.gameId === data.gameId);
|
||||
if (existing) {
|
||||
return prev.map(item =>
|
||||
item.gameId === data.gameId ? data : item
|
||||
);
|
||||
}
|
||||
return [...prev, data];
|
||||
});
|
||||
```
|
||||
| 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 |
|
||||
|
||||
@@ -2,65 +2,214 @@
|
||||
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Overview
|
||||
# Sports WebSocket
|
||||
|
||||
> Real-time sports results via WebSocket
|
||||
> Live sports scores and game state
|
||||
|
||||
The Polymarket Sports WebSocket API provides real-time sports results updates. Clients connect to receive live match data including scores, periods, and game status as events happen.
|
||||
The Sports WebSocket provides real-time sports results updates, including scores, periods, and game status. No authentication required.
|
||||
|
||||
**Endpoint:**
|
||||
## Endpoint
|
||||
|
||||
```
|
||||
wss://sports-api.polymarket.com/ws
|
||||
```
|
||||
|
||||
<Note>
|
||||
No authentication is required. This is a public broadcast channel that streams updates for all active sports events.
|
||||
</Note>
|
||||
No subscription message required — connect and start receiving data for all active sports events.
|
||||
|
||||
## How It Works
|
||||
## Heartbeat
|
||||
|
||||
Once connected, clients automatically receive JSON messages whenever a sports event updates. There is no subscription message required—simply connect and start receiving data.
|
||||
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;
|
||||
}
|
||||
|
||||
## Connection Management
|
||||
// Handle JSON messages...
|
||||
};
|
||||
```
|
||||
|
||||
### Automatic Ping/Pong Heartbeat
|
||||
## Message Type
|
||||
|
||||
The server sends PING messages at regular intervals. Clients **must** respond with PONG to maintain the connection.
|
||||
Each message is a JSON object with game state fields.
|
||||
|
||||
| Parameter | Default | Description |
|
||||
| ------------- | ---------- | --------------------------------------------- |
|
||||
| PING Interval | 5 seconds | How often the server sends PING messages |
|
||||
| PONG Timeout | 10 seconds | How long the server waits for a PONG response |
|
||||
### sport\_result
|
||||
|
||||
<Warning>
|
||||
If your client doesn't respond to PING within 10 seconds, the connection will be closed automatically.
|
||||
</Warning>
|
||||
Emitted when:
|
||||
|
||||
### Connection Health
|
||||
* A match goes live
|
||||
* The score changes
|
||||
* The period changes (e.g., halftime, overtime)
|
||||
* A match ends
|
||||
* Possession changes (NFL and CFB only)
|
||||
|
||||
* Server sends `PING` → Client must respond with `PONG`
|
||||
* No response within timeout → Connection terminated
|
||||
* Clients should implement automatic reconnection with exponential backoff
|
||||
**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"
|
||||
}
|
||||
```
|
||||
|
||||
## Session Affinity
|
||||
**Esports — CS2 (finished):**
|
||||
|
||||
The server uses cookie-based session affinity (`sports-results` cookie) to ensure clients maintain connection to the same backend instance. This is handled automatically by the browser.
|
||||
```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`.
|
||||
|
||||
## Next Steps
|
||||
The `slug` field follows the format `{league}-{team1}-{team2}-{date}` (e.g., `nfl-buf-kc-2025-01-26`).
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Message Format" icon="brackets-curly" href="/developers/sports-websocket/message-format">
|
||||
Understand the structure of sports update messages
|
||||
</Card>
|
||||
## Period Values
|
||||
|
||||
<Card title="Quickstart" icon="code" href="/developers/sports-websocket/quickstart">
|
||||
Implementation examples in JavaScript and TypeScript
|
||||
</Card>
|
||||
</CardGroup>
|
||||
| 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 |
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Quickstart
|
||||
# Sports WebSocket
|
||||
|
||||
> Connect to the Sports WebSocket and receive live updates
|
||||
> Live sports scores and game state
|
||||
|
||||
Connect to the Sports WebSocket to receive real-time sports results. No authentication required—just connect and handle incoming messages.
|
||||
The Sports WebSocket provides real-time sports results updates, including scores, periods, and game status. No authentication required.
|
||||
|
||||
## Endpoint
|
||||
|
||||
@@ -14,244 +14,202 @@ Connect to the Sports WebSocket to receive real-time sports results. No authenti
|
||||
wss://sports-api.polymarket.com/ws
|
||||
```
|
||||
|
||||
***
|
||||
No subscription message required — connect and start receiving data for all active sports events.
|
||||
|
||||
## JavaScript Example
|
||||
## Heartbeat
|
||||
|
||||
<CodeGroup>
|
||||
```javascript JavaScript theme={null}
|
||||
const ws = new WebSocket('wss://sports-api.polymarket.com/ws');
|
||||
|
||||
ws.onopen = () => {
|
||||
console.log('Connected to Sports WebSocket');
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
// Respond to server PING
|
||||
if (event.data === 'ping') {
|
||||
ws.send('pong');
|
||||
return;
|
||||
}
|
||||
|
||||
// Parse and handle sports updates
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Update:', data.slug, data.score, data.period);
|
||||
};
|
||||
|
||||
ws.onclose = () => {
|
||||
console.log('Disconnected');
|
||||
// Reconnect after 1 second
|
||||
setTimeout(() => location.reload(), 1000);
|
||||
};
|
||||
|
||||
ws.onerror = (error) => {
|
||||
console.error('WebSocket error:', error);
|
||||
};
|
||||
```
|
||||
|
||||
```typescript React Hook theme={null}
|
||||
import { useEffect, useRef, useState } from 'react';
|
||||
|
||||
interface SportsUpdate {
|
||||
slug: string;
|
||||
live: boolean;
|
||||
ended: boolean;
|
||||
score: string;
|
||||
period: string;
|
||||
elapsed: string;
|
||||
last_update: string;
|
||||
finished_timestamp?: string;
|
||||
turn?: string;
|
||||
}
|
||||
|
||||
export function useSportsWebSocket() {
|
||||
const [updates, setUpdates] = useState<Map<string, SportsUpdate>>(new Map());
|
||||
const wsRef = useRef<WebSocket | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
const ws = new WebSocket('wss://sports-api.polymarket.com/ws');
|
||||
wsRef.current = ws;
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
if (event.data === 'ping') {
|
||||
ws.send('pong');
|
||||
return;
|
||||
}
|
||||
const data: SportsUpdate = JSON.parse(event.data);
|
||||
setUpdates(prev => new Map(prev).set(data.slug, data));
|
||||
};
|
||||
|
||||
ws.onclose = () => setTimeout(() => location.reload(), 1000);
|
||||
|
||||
return () => ws.close();
|
||||
}, []);
|
||||
|
||||
return Array.from(updates.values());
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
***
|
||||
|
||||
## Critical: PING/PONG Handling
|
||||
|
||||
The server sends PING messages every 5 seconds. Your client **must** respond with PONG to stay connected.
|
||||
The server sends `ping` every 5 seconds. Respond with `pong` within 10 seconds or the connection will close.
|
||||
|
||||
```javascript theme={null}
|
||||
// CORRECT - Handle PING messages
|
||||
ws.onmessage = (event) => {
|
||||
if (event.data === 'ping') {
|
||||
ws.send('pong'); // Respond immediately
|
||||
if (event.data === "ping") {
|
||||
ws.send("pong");
|
||||
return;
|
||||
}
|
||||
// Handle other messages...
|
||||
const data = JSON.parse(event.data);
|
||||
handleUpdate(data);
|
||||
|
||||
// Handle JSON messages...
|
||||
};
|
||||
```
|
||||
|
||||
```javascript theme={null}
|
||||
// WRONG - Ignoring PING messages will disconnect you
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data); // Fails on "ping" string!
|
||||
handleUpdate(data);
|
||||
};
|
||||
```
|
||||
## Message Type
|
||||
|
||||
<Warning>
|
||||
If you don't respond to PING within 10 seconds, your connection will be terminated.
|
||||
</Warning>
|
||||
Each message is a JSON object with game state fields.
|
||||
|
||||
***
|
||||
### sport\_result
|
||||
|
||||
## Connection State Management
|
||||
Emitted when:
|
||||
|
||||
Always check connection state before sending:
|
||||
* A match goes live
|
||||
* The score changes
|
||||
* The period changes (e.g., halftime, overtime)
|
||||
* A match ends
|
||||
* Possession changes (NFL and CFB only)
|
||||
|
||||
```javascript theme={null}
|
||||
if (ws.readyState === WebSocket.OPEN) {
|
||||
ws.send('pong');
|
||||
} else {
|
||||
console.warn('WebSocket not connected');
|
||||
**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):**
|
||||
|
||||
## Browser Tab Visibility
|
||||
|
||||
Connections may drop when browser tabs become inactive. Handle visibility changes:
|
||||
|
||||
```javascript theme={null}
|
||||
document.addEventListener('visibilitychange', () => {
|
||||
if (!document.hidden && ws.readyState !== WebSocket.OPEN) {
|
||||
console.log('Tab became visible, reconnecting...');
|
||||
connect();
|
||||
}
|
||||
});
|
||||
```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`.
|
||||
|
||||
## Troubleshooting
|
||||
The `slug` field follows the format `{league}-{team1}-{team2}-{date}` (e.g., `nfl-buf-kc-2025-01-26`).
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Connection drops after exactly 10 seconds">
|
||||
Your PING/PONG handler isn't working correctly.
|
||||
## Period Values
|
||||
|
||||
**Check:**
|
||||
| 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) |
|
||||
|
||||
* You're responding to `"ping"` string messages (not JSON)
|
||||
* You're sending `"pong"` as a string response
|
||||
* No errors are preventing the PONG from being sent
|
||||
## Game Status Values
|
||||
|
||||
```javascript theme={null}
|
||||
// Debug PING/PONG handling
|
||||
ws.onmessage = (event) => {
|
||||
console.log('Received:', event.data);
|
||||
if (event.data === 'ping') {
|
||||
console.log('Sending PONG response');
|
||||
ws.send('pong');
|
||||
return;
|
||||
}
|
||||
// Handle JSON messages...
|
||||
};
|
||||
```
|
||||
</Accordion>
|
||||
Game status values vary by sport:
|
||||
|
||||
<Accordion title="Connection keeps dropping frequently">
|
||||
This may be network instability or main thread blocking.
|
||||
### NFL
|
||||
|
||||
**Solutions:**
|
||||
| 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 |
|
||||
|
||||
* Implement exponential backoff for reconnection
|
||||
* Ensure your message handler doesn't block the main thread
|
||||
* Check network stability
|
||||
### NHL
|
||||
|
||||
```javascript theme={null}
|
||||
handleReconnect() {
|
||||
this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
|
||||
setTimeout(() => this.connect(), this.reconnectDelay);
|
||||
}
|
||||
```
|
||||
</Accordion>
|
||||
| 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 |
|
||||
|
||||
<Accordion title="Messages not updating UI">
|
||||
Ensure you're updating state correctly based on the `slug` identifier.
|
||||
### MLB
|
||||
|
||||
```javascript theme={null}
|
||||
// Use slug as unique key
|
||||
setSportsData(prev => {
|
||||
const index = prev.findIndex(item => item.slug === data.slug);
|
||||
if (index >= 0) {
|
||||
const updated = [...prev];
|
||||
updated[index] = data;
|
||||
return updated;
|
||||
}
|
||||
return [...prev, data];
|
||||
});
|
||||
```
|
||||
</Accordion>
|
||||
| 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 |
|
||||
|
||||
<Accordion title="Memory leaks with multiple connections">
|
||||
Clean up properly when disconnecting:
|
||||
### NBA / CBB
|
||||
|
||||
```javascript theme={null}
|
||||
const cleanup = () => {
|
||||
if (reconnectTimeout) {
|
||||
clearTimeout(reconnectTimeout);
|
||||
}
|
||||
if (ws) {
|
||||
ws.close();
|
||||
ws = null;
|
||||
}
|
||||
};
|
||||
| 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 |
|
||||
|
||||
// React: cleanup in useEffect return
|
||||
// Vanilla: call on page unload
|
||||
window.addEventListener('beforeunload', cleanup);
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
### 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 |
|
||||
|
||||
## Debugging Tips
|
||||
### Soccer
|
||||
|
||||
Enable verbose logging to diagnose connection issues:
|
||||
| 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 |
|
||||
|
||||
```javascript theme={null}
|
||||
ws.onopen = () => console.log('[connected]');
|
||||
ws.onclose = (e) => console.log('[closed]', e.code, e.reason);
|
||||
ws.onerror = (e) => console.error('[error]', e);
|
||||
ws.onmessage = (e) => console.log('[message]', e.data);
|
||||
```
|
||||
### Esports
|
||||
|
||||
Monitor connection state:
|
||||
| Status | Description |
|
||||
| ------------- | ----------------------- |
|
||||
| `not_started` | Match not yet started |
|
||||
| `running` | Match currently playing |
|
||||
| `finished` | Match completed |
|
||||
| `postponed` | Match postponed |
|
||||
| `canceled` | Match canceled |
|
||||
|
||||
```javascript theme={null}
|
||||
setInterval(() => {
|
||||
const states = ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'];
|
||||
console.log('WebSocket state:', states[ws.readyState]);
|
||||
}, 5000);
|
||||
```
|
||||
### Tennis
|
||||
|
||||
| Status | Description |
|
||||
| ------------ | ----------------------- |
|
||||
| `scheduled` | Match not yet started |
|
||||
| `inprogress` | Match currently playing |
|
||||
| `suspended` | Match suspended |
|
||||
| `finished` | Match completed |
|
||||
| `postponed` | Match postponed |
|
||||
| `cancelled` | Match canceled |
|
||||
|
||||
Reference in New Issue
Block a user