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

Add scraped Polymarket documentation (117 files)

Browse Source
This commit is contained in:
Etherdrake
2026-02-14 12:59:26 +01:00
parent 26c6b35691
commit 9263557be6
119 changed files with 27955 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developers/sports-websocket/message-format.md
+163
View File
@@ -0,0 +1,163 @@
> ## 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.
# Message Format
> Structure of sports result update messages
Once connected to the Sports WebSocket, clients receive JSON messages whenever a sports event updates. Messages are broadcast to all connected clients automatically.
***
## sport\_result Message
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)
### 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",
"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",
"homeTeam": "ARCRED",
"awayTeam": "The glecs",
"status": "finished",
"score": "000-000|2-0|Bo3",
"period": "2/3",
"live": false,
"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
***
## 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`, etc. | 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) |
***
## Handling Updates
When processing messages, use the `gameId` field as the unique identifier to update your local state:
```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];
});
```
docs/developers/sports-websocket/overview.md
+66
View File
@@ -0,0 +1,66 @@
> ## 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 sports results via WebSocket
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.
**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>
## How It Works
Once connected, clients automatically receive JSON messages whenever a sports event updates. There is no subscription message required—simply connect and start receiving data.
***
## Connection Management
### Automatic Ping/Pong Heartbeat
The server sends PING messages at regular intervals. Clients **must** respond with PONG to maintain the connection.
| 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 |
<Warning>
If your client doesn't respond to PING within 10 seconds, the connection will be closed automatically.
</Warning>
### Connection Health
* Server sends `PING` → Client must respond with `PONG`
* No response within timeout → Connection terminated
* Clients should implement automatic reconnection with exponential backoff
***
## Session Affinity
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.
***
## Next Steps
<CardGroup cols={2}>
<Card title="Message Format" icon="brackets-curly" href="/developers/sports-websocket/message-format">
Understand the structure of sports update messages
</Card>
<Card title="Quickstart" icon="code" href="/developers/sports-websocket/quickstart">
Implementation examples in JavaScript and TypeScript
</Card>
</CardGroup>
docs/developers/sports-websocket/quickstart.md
+257
View File
@@ -0,0 +1,257 @@
> ## 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.
# Quickstart
> Connect to the Sports WebSocket and receive live updates
Connect to the Sports WebSocket to receive real-time sports results. No authentication required—just connect and handle incoming messages.
## Endpoint
```
wss://sports-api.polymarket.com/ws
```
***
## JavaScript Example
<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.
```javascript theme={null}
// CORRECT - Handle PING messages
ws.onmessage = (event) => {
if (event.data === 'ping') {
ws.send('pong'); // Respond immediately
return;
}
// Handle other messages...
const data = JSON.parse(event.data);
handleUpdate(data);
};
```
```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);
};
```
<Warning>
If you don't respond to PING within 10 seconds, your connection will be terminated.
</Warning>
***
## Connection State Management
Always check connection state before sending:
```javascript theme={null}
if (ws.readyState === WebSocket.OPEN) {
ws.send('pong');
} else {
console.warn('WebSocket not connected');
}
```
***
## 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();
}
});
```
***
## Troubleshooting
<AccordionGroup>
<Accordion title="Connection drops after exactly 10 seconds">
Your PING/PONG handler isn't working correctly.
**Check:**
* 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
```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>
<Accordion title="Connection keeps dropping frequently">
This may be network instability or main thread blocking.
**Solutions:**
* Implement exponential backoff for reconnection
* Ensure your message handler doesn't block the main thread
* Check network stability
```javascript theme={null}
handleReconnect() {
this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
setTimeout(() => this.connect(), this.reconnectDelay);
}
```
</Accordion>
<Accordion title="Messages not updating UI">
Ensure you're updating state correctly based on the `slug` identifier.
```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>
<Accordion title="Memory leaks with multiple connections">
Clean up properly when disconnecting:
```javascript theme={null}
const cleanup = () => {
if (reconnectTimeout) {
clearTimeout(reconnectTimeout);
}
if (ws) {
ws.close();
ws = null;
}
};
// React: cleanup in useEffect return
// Vanilla: call on page unload
window.addEventListener('beforeunload', cleanup);
```
</Accordion>
</AccordionGroup>
***
## Debugging Tips
Enable verbose logging to diagnose connection issues:
```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);
```
Monitor connection state:
```javascript theme={null}
setInterval(() => {
const states = ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'];
console.log('WebSocket state:', states[ws.readyState]);
}, 5000);
```