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/quickstart/fetching-data.md
+196
View File
@@ -0,0 +1,196 @@
> ## 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 Market Data
> Fetch Polymarket data in minutes with no authentication required
Get market data with zero setup. No API key, no authentication, no wallet required.
***
## Understanding the Data Model
Before fetching data, understand how Polymarket structures its markets:
<Steps>
<Step title="Event">
The top-level object representing a question like "Will X happen?"
</Step>
<Step title="Market">
Each event contains one or more markets. Each market is a specific tradable binary outcome.
</Step>
<Step title="Outcomes & Prices">
Markets have `outcomes` and `outcomePrices` arrays that map 1:1. These prices represent implied probabilities.
</Step>
</Steps>
```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)
```
***
## Fetch Active Events
List all currently active events on Polymarket:
```bash theme={null}
curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=5"
```
<Accordion title="Example Response">
```json theme={null}
[
{
"id": "123456",
"slug": "will-bitcoin-reach-100k-by-2025",
"title": "Will Bitcoin reach $100k by 2025?",
"active": true,
"closed": false,
"tags": [
{ "id": "21", "label": "Crypto", "slug": "crypto" }
],
"markets": [
{
"id": "789",
"question": "Will Bitcoin reach $100k by 2025?",
"clobTokenIds": ["TOKEN_YES_ID", "TOKEN_NO_ID"],
"outcomes": "[\"Yes\", \"No\"]",
"outcomePrices": "[\"0.65\", \"0.35\"]"
}
]
}
]
```
</Accordion>
<Tip>
Always use `active=true&closed=false` to filter for live, tradable events.
</Tip>
***
## Market Discovery Best Practices
### For Sports Events
Use the `/sports` endpoint to discover leagues, then query by `series_id`:
```bash theme={null}
# Get all supported sports leagues
curl "https://gamma-api.polymarket.com/sports"
# Get events for a specific league (e.g., NBA series_id=10345)
curl "https://gamma-api.polymarket.com/events?series_id=10345&active=true&closed=false"
# Filter to just game bets (not futures) using tag_id=100639
curl "https://gamma-api.polymarket.com/events?series_id=10345&tag_id=100639&active=true&closed=false&order=startTime&ascending=true"
```
<Note>
`/sports` only returns automated leagues. For others (UFC, Boxing, F1, Golf, Chess), use tag IDs via `/events?tag_id=<tag_id>`.
</Note>
### For Non-Sports Topics
Use `/tags` to discover all available categories, then filter events:
```bash theme={null}
# Get all available tags
curl "https://gamma-api.polymarket.com/tags?limit=100"
# Query events by topic
curl "https://gamma-api.polymarket.com/events?tag_id=2&active=true&closed=false"
```
<Tip>
Each event response includes a `tags` array, useful for discovering categories from live data and building your own tag mapping.
</Tip>
***
## Get Market Details
Once you have an event, get details for a specific market using its ID or slug:
```bash theme={null}
curl "https://gamma-api.polymarket.com/markets?slug=will-bitcoin-reach-100k-by-2025"
```
The response includes `clobTokenIds`, you'll need these to fetch prices and place orders.
***
## Get Current Price
Query the CLOB for the current price of any token:
```bash theme={null}
curl "https://clob.polymarket.com/price?token_id=YOUR_TOKEN_ID&side=buy"
```
<Accordion title="Example Response">
```json theme={null}
{
"price": "0.65"
}
```
</Accordion>
***
## Get Orderbook Depth
See all bids and asks for a market:
```bash theme={null}
curl "https://clob.polymarket.com/book?token_id=YOUR_TOKEN_ID"
```
<Accordion title="Example Response">
```json theme={null}
{
"market": "0x...",
"asset_id": "YOUR_TOKEN_ID",
"bids": [
{ "price": "0.64", "size": "500" },
{ "price": "0.63", "size": "1200" }
],
"asks": [
{ "price": "0.66", "size": "300" },
{ "price": "0.67", "size": "800" }
]
}
```
</Accordion>
***
## More Data APIs
<CardGroup cols={2}>
<Card title="Gamma API" icon="database" href="/developers/gamma-markets-api/overview">
Deep dive into market discovery
</Card>
<Card title="Data API" icon="table" href="/developers/misc-endpoints/data-api-get-positions">
Positions, activity, and holders data
</Card>
<Card title="WebSocket" icon="bolt" href="/developers/CLOB/websocket/wss-overview">
Real-time orderbook updates
</Card>
<Card title="RTDS" icon="signal-stream" href="/developers/RTDS/RTDS-overview">
Real-time data streaming service
</Card>
</CardGroup>
docs/quickstart/first-order.md
+302
View File
@@ -0,0 +1,302 @@
> ## 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.
# Placing Your First Order
> Set up authentication and submit your first trade
This guide walks you through placing an order on Polymarket using your own wallet.
***
## Installation
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client ethers@5
```
```bash Python theme={null}
pip install py-clob-client
```
```bash Rust theme={null}
cargo add polymarket-client-sdk
```
</CodeGroup>
***
## Step 1: Initialize Client with Private Key
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers"; // v5.8.0
const HOST = "https://clob.polymarket.com";
const CHAIN_ID = 137; // Polygon mainnet
const signer = new Wallet(process.env.PRIVATE_KEY);
const client = new ClobClient(HOST, CHAIN_ID, signer);
```
```python Python theme={null}
from py_clob_client.client import ClobClient
import os
host = "https://clob.polymarket.com"
chain_id = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
client = ClobClient(host, key=private_key, chain_id=chain_id)
```
</CodeGroup>
***
## Step 2: Derive User API Credentials
Your private key is used once to derive API credentials. These credentials authenticate all subsequent requests.
<CodeGroup>
```typescript TypeScript theme={null}
// Get existing API key, or create one if none exists
const userApiCreds = await client.createOrDeriveApiKey();
console.log("API Key:", userApiCreds.apiKey);
console.log("Secret:", userApiCreds.secret);
console.log("Passphrase:", userApiCreds.passphrase);
```
```python Python theme={null}
# Get existing API key, or create one if none exists
user_api_creds = client.create_or_derive_api_creds()
print("API Key:", user_api_creds["apiKey"])
print("Secret:", user_api_creds["secret"])
print("Passphrase:", user_api_creds["passphrase"])
```
</CodeGroup>
***
## Step 3: Configure Signature Type and Funder
Before reinitializing the client, determine your **signature type** and **funder address**:
| How do you want to trade? | Type | Value | Funder Address |
| ----------------------------------------------------------------------------------------- | ------------ | ----- | ------------------------- |
| I want to use an EOA wallet. It holds USDCe and position tokens, and I'll pay my own gas. | EOA | `0` | Your EOA wallet address |
| I want to trade through my Polymarket.com account (Magic Link email/Google login). | POLY\_PROXY | `1` | Your proxy wallet address |
| I want to trade through my Polymarket.com account (browser wallet connection). | GNOSIS\_SAFE | `2` | Your proxy wallet address |
<Note>
If you have a Polymarket.com account, your funds are in a proxy wallet (visible in the profile dropdown). Use type 1 or 2. Type 0 is for standalone EOA wallets only.
</Note>
***
## Step 4: Reinitialize with Full Authentication
<CodeGroup>
```typescript TypeScript theme={null}
// Choose based on your wallet type (see table above)
const SIGNATURE_TYPE = 0; // EOA example
const FUNDER_ADDRESS = signer.address; // For EOA, funder is your wallet
const client = new ClobClient(
HOST,
CHAIN_ID,
signer,
userApiCreds,
SIGNATURE_TYPE,
FUNDER_ADDRESS
);
```
```python Python theme={null}
# Choose based on your wallet type (see table above)
signature_type = 0 # EOA example
funder_address = "YOUR_WALLET_ADDRESS" # For EOA, funder is your wallet
client = ClobClient(
host,
key=private_key,
chain_id=chain_id,
creds=user_api_creds,
signature_type=signature_type,
funder=funder_address
)
```
</CodeGroup>
<Warning>
**Do not use Builder API credentials in place of User API credentials!** Builder credentials are for order attribution, not user authentication. See [Builder Order Attribution](/developers/builders/order-attribution).
</Warning>
***
## Step 5: Place an Order
Now you're ready to trade! First, get a token ID from the [Gamma API](/developers/gamma-markets-api/get-markets).
<CodeGroup>
```typescript TypeScript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
// Get market info first
const market = await client.getMarket("TOKEN_ID");
const response = await client.createAndPostOrder(
{
tokenID: "TOKEN_ID",
price: 0.50, // Price per share ($0.50)
size: 10, // Number of shares
side: Side.BUY, // BUY or SELL
},
{
tickSize: market.tickSize,
negRisk: market.negRisk, // true for multi-outcome events
},
OrderType.GTC // Good-Til-Cancelled
);
console.log("Order ID:", response.orderID);
console.log("Status:", response.status);
```
```python Python theme={null}
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
# Get market info first
market = client.get_market("TOKEN_ID")
response = client.create_and_post_order(
OrderArgs(
token_id="TOKEN_ID",
price=0.50, # Price per share ($0.50)
size=10, # Number of shares
side=BUY, # BUY or SELL
),
options={
"tick_size": market["tickSize"],
"neg_risk": market["negRisk"], # True for multi-outcome events
},
order_type=OrderType.GTC # Good-Til-Cancelled
)
print("Order ID:", response["orderID"])
print("Status:", response["status"])
```
</CodeGroup>
***
## Step 6: Check Your Orders
<CodeGroup>
```typescript TypeScript theme={null}
// View all open orders
const openOrders = await client.getOpenOrders();
console.log(`You have ${openOrders.length} open orders`);
// View your trade history
const trades = await client.getTrades();
console.log(`You've made ${trades.length} trades`);
// Cancel an order
await client.cancelOrder(response.orderID);
```
```python Python theme={null}
# View all open orders
open_orders = trading_client.get_open_orders()
print(f"You have {len(open_orders)} open orders")
# View your trade history
trades = trading_client.get_trades()
print(f"You've made {len(trades)} trades")
# Cancel an order
trading_client.cancel_order(response["orderID"])
```
</CodeGroup>
***
## Troubleshooting
<AccordionGroup>
<Accordion title="Invalid Signature / L2 Auth Not Available">
Wrong private key, signature type, or funder address for the derived User API credentials.
Double check the following values when creating User API credentials via `createOrDeriveApiKey()`:
* Do not use Builder API credentials in place of User API credentials
* Check `signatureType` matches your account type (0, 1, or 2)
* Ensure `funder` is correct for your wallet type
</Accordion>
<Accordion title="Unauthorized / Invalid API Key">
Wrong API key, secret, or passphrase.
Re-derive credentials with `createOrDeriveApiKey()` and update your config.
</Accordion>
<Accordion title="Not Enough Balance / Allowance">
Either not enough USDCe / position tokens in your funder address, or you lack approvals to spend your tokens.
* Deposit USDCe to your funder address.
* Ensure you have more USDCe than what's committed in open orders.
* Check that you've set all necessary token approvals.
</Accordion>
<Accordion title="Blocked by Cloudflare / Geoblock">
You're trying to place a trade from a restricted region.
See [Geographic Restrictions](/developers/CLOB/geoblock) for details.
</Accordion>
</AccordionGroup>
***
## Adding Builder API Credentials
If you're building an app that routes orders for your users, you can add builder credentials to get attribution on the [Builder Leaderboard](https://builders.polymarket.com/):
```typescript TypeScript theme={null}
import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";
const builderCreds: BuilderApiKeyCreds = {
key: process.env.POLY_BUILDER_API_KEY!,
secret: process.env.POLY_BUILDER_SECRET!,
passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};
const builderConfig = new BuilderConfig({ localBuilderCreds: builderCreds });
// Add builderConfig as the last parameter
const client = new ClobClient(
HOST,
CHAIN_ID,
signer,
userApiCreds,
signatureType,
funderAddress,
undefined,
false,
builderConfig
);
```
<Info>
Builder credentials are **separate** from user credentials. You use your builder
credentials to tag orders, but each user still needs their own L2 credentials to trade.
</Info>
<Card title="Full Builder Guide" icon="hammer" href="/developers/builders/order-attribution">
Complete documentation for order attribution and gasless transactions
</Card>
docs/quickstart/introduction/rate-limits.md
+109
View File
@@ -0,0 +1,109 @@
> ## 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.
# API Rate Limits
## How Rate Limiting Works
All rate limits are enforced using Cloudflare's throttling system. When you exceed the maximum configured rate for any endpoint, requests are throttled rather than immediately rejected. This means:
* **Throttling**: Requests over the limit are delayed/queued rather than dropped
* **Burst Allowances**: Some endpoints allow short bursts above the sustained rate
* **Time Windows**: Limits reset based on sliding time windows (e.g., per 10 seconds, per minute)
## General Rate Limits
| Endpoint | Limit | Notes |
| --------------------- | -------------------- | -------------------------------------------------- |
| General Rate Limiting | 15000 requests / 10s | Throttle requests over the maximum configured rate |
| "OK" Endpoint | 100 requests / 10s | Throttle requests over the maximum configured rate |
## Data API Rate Limits
| Endpoint | Limit | Notes |
| ---------------------------- | ------------------- | -------------------------------------------------- |
| Data API (General) | 1000 requests / 10s | Throttle requests over the maximum configured rate |
| Data API `/trades` | 200 requests / 10s | Throttle requests over the maximum configured rate |
| Data API `/positions` | 150 requests / 10s | Throttle requests over the maximum configured rate |
| Data API `/closed-positions` | 150 requests / 10s | Throttle requests over the maximum configured rate |
| Data API "OK" Endpoint | 100 requests / 10s | Throttle requests over the maximum configured rate |
## GAMMA API Rate Limits
| Endpoint | Limit | Notes |
| -------------------------------- | ------------------- | -------------------------------------------------- |
| GAMMA (General) | 4000 requests / 10s | Throttle requests over the maximum configured rate |
| GAMMA Get Comments | 200 requests / 10s | Throttle requests over the maximum configured rate |
| GAMMA `/events` | 500 requests / 10s | Throttle requests over the maximum configured rate |
| GAMMA `/markets` | 300 requests / 10s | Throttle requests over the maximum configured rate |
| GAMMA `/markets` /events listing | 900 requests / 10s | Throttle requests over the maximum configured rate |
| GAMMA Tags | 200 requests / 10s | Throttle requests over the maximum configured rate |
| GAMMA Search | 350 requests / 10s | Throttle requests over the maximum configured rate |
## CLOB API Rate Limits
### General CLOB Endpoints
| Endpoint | Limit | Notes |
| ----------------------------- | ------------------- | -------------------------------------------------- |
| CLOB (General) | 9000 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB GET Balance Allowance | 200 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB UPDATE Balance Allowance | 50 requests / 10s | Throttle requests over the maximum configured rate |
### CLOB Market Data
| Endpoint | Limit | Notes |
| ----------------- | ------------------- | -------------------------------------------------- |
| CLOB `/book` | 1500 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB `/books` | 500 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB `/price` | 1500 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB `/prices` | 500 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB `/midprice` | 1500 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB `/midprices` | 500 requests / 10s | Throttle requests over the maximum configured rate |
### CLOB Ledger Endpoints
| Endpoint | Limit | Notes |
| ----------------------------------------------------------- | ------------------ | -------------------------------------------------- |
| CLOB Ledger (`/trades` `/orders` `/notifications` `/order`) | 900 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB Ledger `/data/orders` | 500 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB Ledger `/data/trades` | 500 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB `/notifications` | 125 requests / 10s | Throttle requests over the maximum configured rate |
### CLOB Markets & Pricing
| Endpoint | Limit | Notes |
| --------------------- | ------------------- | -------------------------------------------------- |
| CLOB Price History | 1000 requests / 10s | Throttle requests over the maximum configured rate |
| CLOB Market Tick Size | 200 requests / 10s | Throttle requests over the maximum configured rate |
### CLOB Authentication
| Endpoint | Limit | Notes |
| ------------- | ------------------ | -------------------------------------------------- |
| CLOB API Keys | 100 requests / 10s | Throttle requests over the maximum configured rate |
### CLOB Trading Endpoints
| Endpoint | Limit | Notes |
| ----------------------------------- | ---------------------------------- | ---------------------------------------------------------- |
| CLOB POST `/order` | 3500 requests / 10s (500/s) | BURST - Throttle requests over the maximum configured rate |
| CLOB POST `/order` | 36000 requests / 10 minutes (60/s) | Throttle requests over the maximum configured rate |
| CLOB DELETE `/order` | 3000 requests / 10s (300/s) | BURST - Throttle requests over the maximum configured rate |
| CLOB DELETE `/order` | 30000 requests / 10 minutes (50/s) | Throttle requests over the maximum configured rate |
| CLOB POST `/orders` | 1000 requests / 10s (100/s) | BURST - Throttle requests over the maximum configured rate |
| CLOB POST `/orders` | 15000 requests / 10 minutes (25/s) | Throttle requests over the maximum configured rate |
| CLOB DELETE `/orders` | 1000 requests / 10s (100/s) | BURST - Throttle requests over the maximum configured rate |
| CLOB DELETE `/orders` | 15000 requests / 10 minutes (25/s) | Throttle requests over the maximum configured rate |
| CLOB DELETE `/cancel-all` | 250 requests / 10s (25/s) | BURST - Throttle requests over the maximum configured rate |
| CLOB DELETE `/cancel-all` | 6000 requests / 10 minutes (10/s) | Throttle requests over the maximum configured rate |
| CLOB DELETE `/cancel-market-orders` | 1000 requests / 10s (100/s) | BURST - Throttle requests over the maximum configured rate |
| CLOB DELETE `/cancel-market-orders` | 1500 requests / 10 minutes (25/s) | Throttle requests over the maximum configured rate |
## Other API Rate Limits
| Endpoint | Limit | Notes |
| ----------------- | ---------------------- | -------------------------------------------------- |
| RELAYER `/submit` | 25 requests / 1 minute | Throttle requests over the maximum configured rate |
| User PNL API | 200 requests / 10s | Throttle requests over the maximum configured rate |
docs/quickstart/overview.md
+122
View File
@@ -0,0 +1,122 @@
> ## 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.
# Developer Quickstart
> Get started building with Polymarket APIs
Polymarket provides a suite of APIs and SDKs for building prediction market applications. This guide will help you understand what's available and where to find it.
***
## What Can You Build?
| If you want to... | Start here |
| ----------------------------- | ------------------------------------------------------------------- |
| Fetch markets & prices | [Fetching Market Data](/quickstart/fetching-data) |
| Place orders for yourself | [Placing Your First Order](/quickstart/first-order) |
| Build a trading app for users | [Builders Program Introduction](/developers/builders/builder-intro) |
| Provide liquidity | [Market Makers](/developers/market-makers/introduction) |
***
## APIs at a Glance
### Markets & Data
<CardGroup cols={2}>
<Card title="Gamma API" icon="database" href="/developers/gamma-markets-api/overview">
**Market discovery & metadata**
Fetch events, markets, categories, and resolution data. This is where you discover what's tradeable.
`https://gamma-api.polymarket.com`
</Card>
<Card title="CLOB API" icon="book" href="/developers/CLOB/introduction">
**Prices, orderbooks & trading**
Get real-time prices, orderbook depth, and place orders. The core trading API.
`https://clob.polymarket.com`
</Card>
<Card title="Data API" icon="chart-bar" href="/developers/misc-endpoints/data-api-get-positions">
**Positions, activity & history**
Query user positions, trade history, and portfolio data.
`https://data-api.polymarket.com`
</Card>
<Card title="WebSocket" icon="bolt" href="/developers/CLOB/websocket/wss-overview">
**Real-time updates**
Subscribe to orderbook changes, price updates, and order status.
`wss://ws-subscriptions-clob.polymarket.com`
</Card>
</CardGroup>
### Additional Data Sources
<CardGroup cols={2}>
<Card title="RTDS" icon="signal-stream" href="/developers/RTDS/RTDS-overview">
**Low-latency data stream**
Real-time crypto prices and comments. Optimized for market makers.
</Card>
<Card title="Subgraph" icon="diagram-project" href="/developers/subgraph/overview">
**Onchain queries**
Query blockchain state directly via GraphQL.
</Card>
</CardGroup>
### Trading Infrastructure
<CardGroup cols={2}>
<Card title="CTF Operations" icon="arrows-split-up-and-left" href="/developers/CTF/overview">
**Token split/merge/redeem**
Convert between USDC and outcome tokens. Essential for inventory management.
</Card>
<Card title="Relayer Client" icon="gas-pump" href="/developers/builders/relayer-client">
**Gasless transactions**
Builders can offer gasfree transactions via Polymarket's relayer.
</Card>
</CardGroup>
***
## SDKs & Libraries
<Card title="CLOB Client (TypeScript)" icon="npm" href="https://github.com/Polymarket/clob-client">
`npm install @polymarket/clob-client`
</Card>
<CardGroup cols={2}>
<Card title="CLOB Client (Python)" icon="python" href="https://github.com/Polymarket/py-clob-client">
`pip install py-clob-client`
</Card>
<Card title="CLOB Client (Rust)" icon="rust" href="https://github.com/Polymarket/rs-clob-client">
`cargo add polymarket-client-sdk`
</Card>
</CardGroup>
For builders routing orders for users:
<CardGroup cols={2}>
<Card title="Relayer Client" icon="bolt" href="https://github.com/Polymarket/builder-relayer-client">
Gasless wallet operations
</Card>
<Card title="Signing SDK" icon="key" href="https://github.com/Polymarket/builder-signing-sdk">
Builder authentication headers
</Card>
</CardGroup>
docs/quickstart/reference/endpoints.md
+102
View File
@@ -0,0 +1,102 @@
> ## 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.
# Endpoints
> All Polymarket API URLs and base endpoints
All base URLs for Polymarket APIs. See individual API documentation for available routes and parameters.
***
## REST APIs
| API | Base URL | Description |
| ------------- | ---------------------------------- | ------------------------------------ |
| **CLOB API** | `https://clob.polymarket.com` | Order management, prices, orderbooks |
| **Gamma API** | `https://gamma-api.polymarket.com` | Market discovery, metadata, events |
| **Data API** | `https://data-api.polymarket.com` | User positions, activity, history |
***
## WebSocket Endpoints
| Service | URL | Description |
| ------------------ | ------------------------------------------------ | ----------------------------------- |
| **CLOB WebSocket** | `wss://ws-subscriptions-clob.polymarket.com/ws/` | Orderbook updates, order status |
| **RTDS** | `wss://ws-live-data.polymarket.com` | Low-latency crypto prices, comments |
***
## Quick Reference
### CLOB API
```
https://clob.polymarket.com
```
Common endpoints:
* `GET /price` — Get current price for a token
* `GET /book` — Get orderbook for a token
* `GET /midpoint` — Get midpoint price
* `POST /order` — Place an order (auth required)
* `DELETE /order` — Cancel an order (auth required)
[Full CLOB documentation →](/developers/CLOB/introduction)
### Gamma API
```
https://gamma-api.polymarket.com
```
Common endpoints:
* `GET /events` — List events
* `GET /markets` — List markets
* `GET /events/{id}` — Get event details
[Full Gamma documentation →](/developers/gamma-markets-api/overview)
### Data API
```
https://data-api.polymarket.com
```
Common endpoints:
* `GET /positions` — Get user positions
* `GET /activity` — Get user activity
* `GET /trades` — Get trade history
[Full Data API documentation →](/developers/misc-endpoints/data-api-get-positions)
### CLOB WebSocket
```
wss://ws-subscriptions-clob.polymarket.com/ws/
```
Channels:
* `market` — Orderbook and price updates (public)
* `user` — Order status updates (authenticated)
[Full WebSocket documentation →](/developers/CLOB/websocket/wss-overview)
### RTDS (Real-Time Data Stream)
```
wss://ws-live-data.polymarket.com
```
Channels:
* Crypto price feeds
* Comment streams
[Full RTDS documentation →](/developers/RTDS/RTDS-overview)
docs/quickstart/reference/glossary.md
+79
View File
@@ -0,0 +1,79 @@
> ## 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.
# Glossary
> Key terms and concepts for Polymarket developers
## Markets & Events
| Term | Definition |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Event** | A collection of related markets grouped under a common topic. Example: "2024 US Presidential Election" contains markets for each candidate. |
| **Market** | A single tradeable outcome within an event. Each market has a Yes and No side. Corresponds to a condition ID, question ID, and pair of token IDs. |
| **Token** | Represents a position in a specific outcome (Yes or No). Prices range from 0.00 to 1.00. Winning tokens redeem for \$1 USDCe. Also called *outcome token* or referenced by *token ID*. |
| **Token ID** | The unique identifier for a specific outcome token. Required when placing orders or querying prices. |
| **Condition ID** | Onchain identifier for a market's resolution condition. Used in CTF operations. |
| **Question ID** | Identifier linking a market to its resolution oracle (UMA). |
| **Slug** | Human-readable URL identifier for a market or event. Found in Polymarket URLs: `polymarket.com/event/[slug]` |
***
## Trading
| Term | Definition |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **CLOB** | Central Limit Order Book. Polymarket's off-chain order matching system. Orders are matched here before onchain settlement. |
| **Tick Size** | The minimum price increment for a market. Usually `0.01` (1 cent) or `0.001` (0.1 cent). |
| **Fill** | When an order is matched and executed. Orders can be partially or fully filled. |
***
## Order Types
| Term | Definition |
| ------- | ---------------------------------------------------------------------------------------------------------------- |
| **GTC** | Good-Til-Cancelled. An order that remains open until filled or manually cancelled. |
| **GTD** | Good-Til-Date. An order that expires at a specified time if not filled. |
| **FOK** | Fill-Or-Kill. An order that must be filled entirely and immediately, or it's cancelled. No partial fills. |
| **FAK** | Fill-And-Kill. An order that fills as much as possible immediately, then cancels any remaining unfilled portion. |
***
## Market Types
| Term | Definition |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Binary Market** | A market with exactly two outcomes: Yes and No. The prices always sum to approximately \$1. |
| **Negative Risk (NegRisk)** | A multi-outcome event where only one outcome can resolve Yes. Requires `negRisk: true` in order parameters. [Details](/developers/neg-risk/overview) |
***
## Wallets
| Term | Definition |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **EOA** | Externally Owned Account. A standard Ethereum wallet controlled by a private key. |
| **Funder Address** | The wallet address that holds funds and tokens for trading. |
| **Signature Type** | Identifies wallet type when trading. `0` = EOA, `1` = Magic Link proxy, `2` = Gnosis Safe proxy. |
***
## Token Operations (CTF)
| Term | Definition |
| ---------- | ------------------------------------------------------------------------------------ |
| **CTF** | Conditional Token Framework. The onchain smart contracts that manage outcome tokens. |
| **Split** | Convert USDCe into a complete set of outcome tokens (one Yes + one No). |
| **Merge** | Convert a complete set of outcome tokens back into USDCe. |
| **Redeem** | After resolution, exchange winning tokens for \$1 USDCe each. |
***
## Infrastructure
| Term | Definition |
| ----------- | ------------------------------------------------------------------------- |
| **Polygon** | The blockchain network where Polymarket operates. Chain ID: `137`. |
| **USDCe** | The stablecoin used as collateral on Polymarket. Bridged USDC on Polygon. |
docs/quickstart/websocket/WSS-Quickstart.md
+161
View File
@@ -0,0 +1,161 @@
> ## 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.
# WSS Quickstart
The following code samples and explanation will show you how to subscribe to the Marker and User channels of the Websocket.
You'll need your API keys to do this so we'll start with that.
## Getting your API Keys
<CodeGroup>
```python DeriveAPIKeys-Python [expandable] theme={null}
from py_clob_client.client import ClobClient
host: str = "https://clob.polymarket.com"
key: str = "" #This is your Private Key. If using email login export from https://reveal.magic.link/polymarket otherwise export from your Web3 Application
chain_id: int = 137 #No need to adjust this
POLYMARKET_PROXY_ADDRESS: str = '' #This is the address you deposit/send USDC to to FUND your Polymarket account.
#Select from the following 3 initialization options to matches your login method, and remove any unused lines so only one client is initialized.
### Initialization of a client using a Polymarket Proxy associated with an Email/Magic account. If you login with your email use this example.
client = ClobClient(host, key=key, chain_id=chain_id, signature_type=1, funder=POLYMARKET_PROXY_ADDRESS)
### Initialization of a client using a Polymarket Proxy associated with a Browser Wallet(Metamask, Coinbase Wallet, etc)
client = ClobClient(host, key=key, chain_id=chain_id, signature_type=2, funder=POLYMARKET_PROXY_ADDRESS)
### Initialization of a client that trades directly from an EOA.
client = ClobClient(host, key=key, chain_id=chain_id)
print( client.derive_api_key() )
```
```javascript DeriveAPIKeys-TS [expandable] theme={null}
//npm install @polymarket/clob-client
//npm install ethers
//Client initialization example and dumping API Keys
import {ClobClient, ApiKeyCreds } from "@polymarket/clob-client";
import { Wallet } from "@ethersproject/wallet";
const host = 'https://clob.polymarket.com';
const signer = new Wallet("YourPrivateKey"); //This is your Private Key. If using email login export from https://reveal.magic.link/polymarket otherwise export from your Web3 Application
// Initialize the clob client
// NOTE: the signer must be approved on the CTFExchange contract
const clobClient = new ClobClient(host, 137, signer);
(async () => {
const apiKey = await clobClient.deriveApiKey();
console.log(apiKey);
})();
```
</CodeGroup>
## Using those keys to connect to the Market or User Websocket
<CodeGroup>
```python WSS-Connection [expandable] theme={null}
from websocket import WebSocketApp
import json
import time
import threading
MARKET_CHANNEL = "market"
USER_CHANNEL = "user"
class WebSocketOrderBook:
def __init__(self, channel_type, url, data, auth, message_callback, verbose):
self.channel_type = channel_type
self.url = url
self.data = data
self.auth = auth
self.message_callback = message_callback
self.verbose = verbose
furl = url + "/ws/" + channel_type
self.ws = WebSocketApp(
furl,
on_message=self.on_message,
on_error=self.on_error,
on_close=self.on_close,
on_open=self.on_open,
)
self.orderbooks = {}
def on_message(self, ws, message):
print(message)
pass
def on_error(self, ws, error):
print("Error: ", error)
exit(1)
def on_close(self, ws, close_status_code, close_msg):
print("closing")
exit(0)
def on_open(self, ws):
if self.channel_type == MARKET_CHANNEL:
ws.send(json.dumps({"assets_ids": self.data, "type": MARKET_CHANNEL}))
elif self.channel_type == USER_CHANNEL and self.auth:
ws.send(
json.dumps(
{"markets": self.data, "type": USER_CHANNEL, "auth": self.auth}
)
)
else:
exit(1)
thr = threading.Thread(target=self.ping, args=(ws,))
thr.start()
def subscribe_to_tokens_ids(self, assets_ids):
if self.channel_type == MARKET_CHANNEL:
self.ws.send(json.dumps({"assets_ids": assets_ids, "operation": "subscribe"}))
def unsubscribe_to_tokens_ids(self, assets_ids):
if self.channel_type == MARKET_CHANNEL:
self.ws.send(json.dumps({"assets_ids": assets_ids, "operation": "unsubscribe"}))
def ping(self, ws):
while True:
ws.send("PING")
time.sleep(10)
def run(self):
self.ws.run_forever()
if __name__ == "__main__":
url = "wss://ws-subscriptions-clob.polymarket.com"
#Complete these by exporting them from your initialized client.
api_key = ""
api_secret = ""
api_passphrase = ""
asset_ids = [
"109681959945973300464568698402968596289258214226684818748321941747028805721376",
]
condition_ids = [] # no really need to filter by this one
auth = {"apiKey": api_key, "secret": api_secret, "passphrase": api_passphrase}
market_connection = WebSocketOrderBook(
MARKET_CHANNEL, url, asset_ids, auth, None, True
)
user_connection = WebSocketOrderBook(
USER_CHANNEL, url, condition_ids, auth, None, True
)
market_connection.subscribe_to_tokens_ids(["123"])
# market_connection.unsubscribe_to_tokens_ids(["123"])
market_connection.run()
# user_connection.run()
```
</CodeGroup>