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

docs: populate 96 empty documentation files (2026-04-26)

Browse Source
This commit is contained in:
Etherdrake
2026-04-26 18:12:39 +02:00
parent 454358fdc1
commit 8169113321
96 changed files with 20121 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/quickstart/fetching-data.md
+156
View File
@@ -0,0 +1,156 @@
> ## 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. Default: `false` |
| `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`** when fetching live markets. The `closed` parameter now defaults to `false`, so closed markets are excluded automatically — pass `closed=true` only if you 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>
</CardGroup>
docs/quickstart/first-order.md
+285
View File
@@ -0,0 +1,285 @@
> ## 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
> Place your first order on Polymarket
This guide walks you through placing an order on Polymarket end-to-end.
<Steps>
<Step title="Install the SDK">
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client-v2 ethers@5
```
```bash Python theme={null}
pip install py-clob-client-v2
```
```bash Rust theme={null}
cargo add polymarket-client-sdk --features clob
```
</CodeGroup>
</Step>
<Step title="Set Up Your Client">
Derive your API credentials and initialize the trading client. This example uses an EOA wallet (type `0`) — your wallet pays its own gas and acts as the funder:
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client-v2";
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);
// Derive API credentials
const tempClient = new ClobClient({ host: HOST, chain: CHAIN_ID, signer });
const apiCreds = await tempClient.createOrDeriveApiKey();
// Initialize trading client
const client = new ClobClient({
host: HOST,
chain: CHAIN_ID,
signer,
creds: apiCreds,
signatureType: 0, // EOA
funderAddress: signer.address,
});
```
```python Python theme={null}
from py_clob_client.client import ClobClient
import os
host = "https://clob.polymarket.com"
chain = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
# Derive API credentials
temp_client = ClobClient(host, key=private_key, chain=chain)
api_creds = temp_client.create_or_derive_api_creds()
# Initialize trading client
client = ClobClient(
host,
key=private_key,
chain=chain,
creds=api_creds,
signature_type=0, # EOA
funder="YOUR_WALLET_ADDRESS"
)
```
```rust Rust theme={null}
use std::str::FromStr;
use polymarket_client_sdk::POLYGON;
use polymarket_client_sdk::auth::{LocalSigner, Signer};
use polymarket_client_sdk::clob::{Client, Config};
let private_key = std::env::var("POLYMARKET_PRIVATE_KEY")?;
let signer = LocalSigner::from_str(&private_key)?
.with_chain_id(Some(POLYGON));
// Derive API credentials and initialize client (EOA by default)
let client = Client::new("https://clob.polymarket.com", Config::default())?
.authentication_builder(&signer)
.authenticate()
.await?;
```
</CodeGroup>
<Note>
If you have a Polymarket.com account, your funds are in a proxy wallet — use
signature type `1` or `2` instead. See [Signature
Types](/trading/overview#signature-types) for details.
</Note>
<Warning>
Before trading, your funder address needs **pUSD** (for buying outcome
tokens) and **POL** (for gas, if using EOA type `0`). Proxy wallet users
(types `1` and `2`) can use Polymarket's gasless relayer instead.
</Warning>
</Step>
<Step title="Place an Order">
Get a token ID from the [Markets API](/market-data/fetching-markets), then create and submit your order:
<CodeGroup>
```typescript TypeScript theme={null}
import { Side, OrderType } from "@polymarket/clob-client-v2";
const response = await client.createAndPostOrder(
{
tokenID: "YOUR_TOKEN_ID",
price: 0.5,
size: 10,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false, // Set to true for multi-outcome markets
},
OrderType.GTC,
);
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
response = client.create_and_post_order(
OrderArgs(
token_id="YOUR_TOKEN_ID",
price=0.50,
size=10,
side=BUY,
),
options={
"tick_size": "0.01",
"neg_risk": False, # Set to True for multi-outcome markets
},
order_type=OrderType.GTC
)
print("Order ID:", response["orderID"])
print("Status:", response["status"])
```
```rust Rust theme={null}
use polymarket_client_sdk::clob::types::Side;
use polymarket_client_sdk::types::dec;
let token_id = "YOUR_TOKEN_ID".parse()?;
// Tick size and neg risk are auto-fetched by the order builder
let order = client
.limit_order()
.token_id(token_id)
.price(dec!(0.50))
.size(dec!(10))
.side(Side::Buy)
.build()
.await?;
let signed_order = client.sign(&signer, order).await?;
let response = client.post_order(signed_order).await?;
println!("Order ID: {}", response.order_id);
println!("Status: {:?}", response.status);
```
</CodeGroup>
<Tip>
Look up a market's `tickSize` and `negRisk` values using the SDK's
`getTickSize()` and `getNegRisk()` methods, or from the market object returned
by the API.
</Tip>
</Step>
<Step title="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 = client.get_orders()
print(f"You have {len(open_orders)} open orders")
# View your trade history
trades = client.get_trades()
print(f"You've made {len(trades)} trades")
# Cancel an order
client.cancel(order_id=response["orderID"])
```
```rust Rust theme={null}
use polymarket_client_sdk::clob::types::request::{OrdersRequest, TradesRequest};
// View all open orders
let open_orders = client.orders(&OrdersRequest::default(), None).await?;
println!("You have {} open orders", open_orders.data.len());
// View your trade history
let trades = client.trades(&TradesRequest::default(), None).await?;
println!("You've made {} trades", trades.data.len());
// Cancel an order
client.cancel_order(&response.order_id).await?;
```
</CodeGroup>
</Step>
</Steps>
***
## Troubleshooting
<AccordionGroup>
<Accordion title="L2 AUTH NOT AVAILABLE - Invalid Signature">
Wrong private key, signature type, or funder address for the derived API credentials.
* Check that `signatureType` matches your account type (`0`, `1`, `2`, or `3`)
* Ensure `funder` is correct for your wallet type
* Re-derive credentials with `createOrDeriveApiKey()` if unsure
</Accordion>
<Accordion title="Order rejected - insufficient balance">
Your funder address doesn't have enough tokens:
* **BUY orders**: need pUSD in your funder address
* **SELL orders**: need outcome tokens in your funder address
* Ensure you have more pUSD than what's committed in open orders
</Accordion>
<Accordion title="Order rejected - insufficient allowance">
You need to approve the Exchange contract to spend your tokens. This is
typically done through the Polymarket UI on your first trade, or using the CTF
contract's `setApprovalForAll()` method.
</Accordion>
<Accordion title="What is my funder address">
Your funder address is the wallet where your funds are held:
* **EOA (type 0)**: Your wallet address directly
* **Proxy wallet (type 1 or 2)**: Go to [polymarket.com/settings](https://polymarket.com/settings) and look for the wallet address in the profile dropdown
If the proxy wallet doesn't exist, log into Polymarket.com first (it's deployed on first login).
</Accordion>
<Accordion title="Blocked by Cloudflare or Geoblock">
You're trying to place a trade from a restricted region. See [Geographic Restrictions](/api-reference/geoblock) for details.
</Accordion>
</AccordionGroup>
***
## Next Steps
<CardGroup cols={2}>
<Card title="Create Orders" icon="plus" href="/trading/orders/create">
Order types, tick sizes, and error handling
</Card>
<Card title="Order Attribution" icon="tag" href="/trading/orders/attribution">
Attribute orders to your builder account for volume credit
</Card>
</CardGroup>
docs/quickstart/introduction/rate-limits.md
+126
View File
@@ -0,0 +1,126 @@
> ## 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.
# Rate Limits
> API rate limits for all Polymarket endpoints
All API rate limits are enforced using Cloudflare's throttling system. When you exceed the limit for any endpoint, requests are throttled (delayed/queued) rather than immediately rejected. Limits reset on sliding time windows.
***
## General
| Endpoint | Limit |
| --------------------- | ---------------- |
| General rate limiting | 15,000 req / 10s |
| Health check (`/ok`) | 100 req / 10s |
***
## Gamma API
Base URL: `https://gamma-api.polymarket.com`
| Endpoint | Limit |
| ------------------------------ | --------------- |
| General | 4,000 req / 10s |
| `/events` | 500 req / 10s |
| `/markets` | 300 req / 10s |
| `/markets` + `/events` listing | 900 req / 10s |
| `/comments` | 200 req / 10s |
| `/tags` | 200 req / 10s |
| `/public-search` | 350 req / 10s |
***
## Data API
Base URL: `https://data-api.polymarket.com`
| Endpoint | Limit |
| -------------------- | --------------- |
| General | 1,000 req / 10s |
| `/trades` | 200 req / 10s |
| `/positions` | 150 req / 10s |
| `/closed-positions` | 150 req / 10s |
| Health check (`/ok`) | 100 req / 10s |
***
## CLOB API
Base URL: `https://clob.polymarket.com`
### General
| Endpoint | Limit |
| -------------------------- | --------------- |
| General | 9,000 req / 10s |
| `GET` balance allowance | 200 req / 10s |
| `UPDATE` balance allowance | 50 req / 10s |
### Market Data
| Endpoint | Limit |
| ----------------- | --------------- |
| `/book` | 1,500 req / 10s |
| `/books` | 500 req / 10s |
| `/price` | 1,500 req / 10s |
| `/prices` | 500 req / 10s |
| `/midpoint` | 1,500 req / 10s |
| `/midpoints` | 500 req / 10s |
| `/prices-history` | 1,000 req / 10s |
| Market tick size | 200 req / 10s |
### Ledger
| Endpoint | Limit |
| ------------------------------------------------ | ------------- |
| `/trades`, `/orders`, `/notifications`, `/order` | 900 req / 10s |
| `/data/orders` | 500 req / 10s |
| `/data/trades` | 500 req / 10s |
| `/notifications` | 125 req / 10s |
### Authentication
| Endpoint | Limit |
| ----------------- | ------------- |
| API key endpoints | 100 req / 10s |
### Trading
Trading endpoints have both **burst** limits (short spikes allowed) and **sustained** limits (longer-term average).
| Endpoint | Burst Limit | Sustained Limit |
| ------------------------------ | --------------- | ------------------- |
| `POST /order` | 3,500 req / 10s | 36,000 req / 10 min |
| `DELETE /order` | 3,000 req / 10s | 30,000 req / 10 min |
| `POST /orders` | 1,000 req / 10s | 15,000 req / 10 min |
| `DELETE /orders` | 1,000 req / 10s | 15,000 req / 10 min |
| `DELETE /cancel-all` | 250 req / 10s | 6,000 req / 10 min |
| `DELETE /cancel-market-orders` | 1,000 req / 10s | 1,500 req / 10 min |
***
## Other
| Endpoint | Limit |
| ----------------- | -------------- |
| Relayer `/submit` | 25 req / 1 min |
| User PNL API | 200 req / 10s |
***
## Next Steps
<CardGroup cols={2}>
<Card title="Authentication" icon="key" href="/api-reference/authentication">
Learn how to authenticate trading requests.
</Card>
<Card title="Clients & SDKs" icon="cube" href="/api-reference/clients-sdks">
Official TypeScript, Python, and Rust libraries.
</Card>
</CardGroup>
docs/quickstart/overview.md
+291
View File
@@ -0,0 +1,291 @@
> ## 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
> Fetch a market and place your first order
Get up and running with the Polymarket API in minutes — fetch market data and place your first order.
<Steps>
<Step title="Fetch a Market">
All data endpoints are public — no API key or authentication needed. Use the markets endpoint to find a market and get its token IDs:
<Tabs>
<Tab title="cURL">
```bash theme={null}
curl "https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=1"
```
</Tab>
<Tab title="TypeScript">
```typescript theme={null}
const response = await fetch(
"https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=1"
);
const markets = await response.json();
const market = markets[0];
console.log(market.question);
console.log(market.clobTokenIds);
// ["123456...", "789012..."] — [Yes token ID, No token ID]
```
</Tab>
<Tab title="Python">
```python theme={null}
import requests
response = requests.get(
"https://gamma-api.polymarket.com/markets",
params={"active": "true", "closed": "false", "limit": 1}
)
markets = response.json()
market = markets[0]
print(market["question"])
print(market["clobTokenIds"])
# ["123456...", "789012..."] — [Yes token ID, No token ID]
```
</Tab>
<Tab title="Rust">
```rust theme={null}
use polymarket_client_sdk::gamma::Client;
use polymarket_client_sdk::gamma::types::request::MarketsRequest;
let client = Client::default();
let request = MarketsRequest::builder()
.closed(false)
.limit(1)
.build();
let markets = client.markets(&request).await?;
let market = &markets[0];
println!("{:?}", market.question);
println!("{:?}", market.clob_token_ids);
// Some(["123456...", "789012..."]) — [Yes token ID, No token ID]
```
</Tab>
</Tabs>
Save a token ID from `clobTokenIds` — you'll need it to place an order. The first ID is the Yes token, the second is the No token. See [Fetching Markets](/market-data/fetching-markets) for more strategies like fetching by slug, tag, or event.
</Step>
<Step title="Install the SDK">
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client-v2 ethers@5
```
```bash Python theme={null}
pip install py-clob-client-v2
```
```bash Rust theme={null}
cargo add polymarket-client-sdk
```
</CodeGroup>
</Step>
<Step title="Set Up Your Client">
Derive API credentials and initialize the trading client:
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { ClobClient } from "@polymarket/clob-client-v2";
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);
// Derive API credentials (L1 → L2 auth)
const tempClient = new ClobClient({ host: HOST, chain: CHAIN_ID, signer });
const apiCreds = await tempClient.createOrDeriveApiKey();
// Initialize trading client
const client = new ClobClient({
host: HOST,
chain: CHAIN_ID,
signer,
creds: apiCreds,
signatureType: 0, // Signature type: 0 = EOA
funderAddress: signer.address, // Funder address
});
```
</Tab>
<Tab title="Python">
```python theme={null}
from py_clob_client.client import ClobClient
import os
host = "https://clob.polymarket.com"
chain = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
# Derive API credentials (L1 → L2 auth)
temp_client = ClobClient(host, key=private_key, chain=chain)
api_creds = temp_client.create_or_derive_api_creds()
# Initialize trading client
client = ClobClient(
host,
key=private_key,
chain=chain,
creds=api_creds,
signature_type=0, # Signature type: 0 = EOA
funder="YOUR_WALLET_ADDRESS", # Funder address
)
```
</Tab>
<Tab title="Rust">
```rust theme={null}
use std::str::FromStr;
use polymarket_client_sdk::POLYGON;
use polymarket_client_sdk::auth::{LocalSigner, Signer};
use polymarket_client_sdk::clob::{Client, Config};
let private_key = std::env::var("POLYMARKET_PRIVATE_KEY")?;
let signer = LocalSigner::from_str(&private_key)?
.with_chain_id(Some(POLYGON));
// Derive API credentials and initialize trading client (L1 → L2 auth)
// Signature type defaults to EOA (0)
let client = Client::new("https://clob.polymarket.com", Config::default())?
.authentication_builder(&signer)
.authenticate()
.await?;
```
</Tab>
</Tabs>
<Note>
This example uses an EOA wallet (signature type `0`) — your wallet pays its
own gas. Proxy wallet users (types `1` and `2`) can use Polymarket's gasless
relayer instead. See [Authentication](/api-reference/authentication) for
details on signature types.
</Note>
<Warning>
Before trading, your funder address needs **pUSD** (for buying outcome
tokens) and **POL** (for gas, if using EOA type `0`).
</Warning>
</Step>
<Step title="Place an Order">
Use the `token_id` from Step 1 to place a limit order:
<Tabs>
<Tab title="TypeScript">
```typescript theme={null}
import { Side, OrderType } from "@polymarket/clob-client-v2";
// Fetch market details to get tick size and neg risk
const market = await client.getMarket("YOUR_CONDITION_ID");
const tickSize = String(market.minimum_tick_size); // e.g., "0.01"
const negRisk = market.neg_risk; // e.g., false
const response = await client.createAndPostOrder(
{
tokenID: "YOUR_TOKEN_ID", // From Step 1
price: 0.50,
size: 10,
side: Side.BUY,
orderType: OrderType.GTC,
},
{
tickSize,
negRisk,
},
);
console.log("Order ID:", response.orderID);
console.log("Status:", response.status);
```
</Tab>
<Tab title="Python">
```python theme={null}
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
# Fetch market details to get tick size and neg risk
market = client.get_market("YOUR_CONDITION_ID")
tick_size = str(market["minimum_tick_size"]) # e.g., "0.01"
neg_risk = market["neg_risk"] # e.g., False
response = client.create_and_post_order(
OrderArgs(
token_id="YOUR_TOKEN_ID", # From Step 1
price=0.50,
size=10,
side=BUY,
order_type=OrderType.GTC,
),
options={
"tick_size": tick_size,
"neg_risk": neg_risk,
},
)
print("Order ID:", response["orderID"])
print("Status:", response["status"])
```
</Tab>
<Tab title="Rust">
```rust theme={null}
use polymarket_client_sdk::clob::types::Side;
use polymarket_client_sdk::types::dec;
// token_id is a U256 — parse from the string returned in Step 1
let token_id = "YOUR_TOKEN_ID".parse()?;
// The Rust SDK auto-fetches tick size, neg risk, and fee rate
// No need to manually look them up — the order builder handles it
let order = client
.limit_order()
.token_id(token_id)
.price(dec!(0.50))
.size(dec!(10))
.side(Side::Buy)
.build()
.await?;
let signed_order = client.sign(&signer, order).await?;
let response = client.post_order(signed_order).await?;
println!("Order ID: {}", response.order_id);
println!("Status: {:?}", response.status);
```
</Tab>
</Tabs>
</Step>
</Steps>
***
## Next Steps
<CardGroup cols={2}>
<Card title="Authentication" icon="lock" href="/api-reference/authentication">
Understand L1/L2 auth, signature types, and API credentials.
</Card>
<Card title="Trading Quickstart" icon="bolt" href="/trading/quickstart">
Detailed trading guide with order management and troubleshooting.
</Card>
<Card title="Fetching Markets" icon="magnifying-glass" href="/market-data/fetching-markets">
Strategies for discovering markets by slug, tag, or category.
</Card>
<Card title="Core Concepts" icon="book" href="/concepts/markets-events">
Understand markets, events, prices, and positions.
</Card>
</CardGroup>
docs/quickstart/reference/endpoints.md
+59
View File
@@ -0,0 +1,59 @@
> ## 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.
# Introduction
> Overview of the Polymarket APIs
The Polymarket API provides programmatic access to the world's largest prediction market. The platform is served by three separate APIs, each handling a different domain.
***
## APIs
<CardGroup cols={1}>
<Card title="Gamma API" icon="database">
**`https://gamma-api.polymarket.com`**
Markets, events, tags, series, comments, sports, search, and public profiles. This is the primary API for discovering and browsing market data.
</Card>
<Card title="Data API" icon="chart-line">
**`https://data-api.polymarket.com`**
User positions, trades, activity, holder data, open interest, leaderboards, and builder analytics.
</Card>
<Card title="CLOB API" icon="arrows-rotate">
**`https://clob.polymarket.com`**
Orderbook data, pricing, midpoints, spreads, and price history. Also handles order placement, cancellation, and other trading operations. Trading endpoints require [authentication](/api-reference/authentication).
</Card>
</CardGroup>
<Info>
A separate **Bridge API** (`https://bridge.polymarket.com`) handles deposits and withdrawals. Bridges are not handled by Polymarket, it is a proxy of fun.xyz service.
</Info>
***
## Authentication
The Gamma API and Data API are fully public — no authentication required.
The CLOB API has both public endpoints (orderbook, prices) and authenticated endpoints (order management). See [Authentication](/api-reference/authentication) for details.
***
## Next Steps
<CardGroup cols={2}>
<Card title="Authentication" icon="key" href="/api-reference/authentication">
Learn how to authenticate requests for trading endpoints.
</Card>
<Card title="Clients & SDKs" icon="cube" href="/api-reference/clients-sdks">
Official TypeScript, Python, and Rust libraries.
</Card>
</CardGroup>
docs/quickstart/websocket/WSS-Quickstart.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 and 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 about 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>