agent-skills/market-data.md

Market Data

Four sources for market data: Gamma API (events, markets, search), Data API (trades, positions, user data), CLOB (orderbook, prices), and Subgraph (onchain queries).

Gamma API

Base URL: https://gamma-api.polymarket.com — no auth required.

Events Endpoint

# All active events
GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=100

# By slug (from polymarket.com/event/{slug})
GET https://gamma-api.polymarket.com/events?slug=fed-decision-in-october

# By tag
GET https://gamma-api.polymarket.com/events?tag_id=100381&limit=10&active=true&closed=false

# By series (sports)
GET https://gamma-api.polymarket.com/events?series_id=10345&active=true&closed=false

# Sorted by volume
GET https://gamma-api.polymarket.com/events?active=true&closed=false&order=volume_24hr&ascending=false&limit=100

Markets Endpoint

# By slug
GET https://gamma-api.polymarket.com/markets?slug=fed-decision-in-october

Sort Parameters

Parameter	Values
order	volume_24hr, volume, liquidity, start_date, end_date, competitive, closed_time
ascending	true / false (default: false)
active	true / false
closed	true / false
limit	1–500 (default: 20)
offset	Pagination offset

Pagination

# Page 1
GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=50&offset=0

# Page 2
GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=50&offset=50

Response includes has_more: true/false. Increment offset by limit until has_more is false.

Tags & Sports

# Discover tags
GET https://gamma-api.polymarket.com/tags

# Sports metadata
GET https://gamma-api.polymarket.com/sports

Data API

Base URL: https://data-api.polymarket.com — no auth required. Used for trades, positions, and user-specific data.

CLOB Orderbook

Base URL: https://clob.polymarket.com — no auth for read endpoints.

Get Orderbook

// TypeScript
const client = new ClobClient("https://clob.polymarket.com", 137);
const book = await client.getOrderBook("TOKEN_ID");
// { bids: [{price, size}...], asks: [{price, size}...], tick_size, min_order_size, neg_risk }

# Python
client = ClobClient("https://clob.polymarket.com", chain_id=137)
book = client.get_order_book("TOKEN_ID")

# REST
curl "https://clob.polymarket.com/book?token_id=TOKEN_ID"

Prices

const buyPrice = await client.getPrice("TOKEN_ID", "BUY");   // best ask
const sellPrice = await client.getPrice("TOKEN_ID", "SELL");  // best bid

curl "https://clob.polymarket.com/price?token_id=TOKEN_ID&side=BUY"

Midpoint

const mid = await client.getMidpoint("TOKEN_ID");  // { mid: "0.50" }

If bid-ask spread > $0.10, Polymarket UI shows last traded price instead of midpoint.

Spread

const spread = await client.getSpread("TOKEN_ID");  // { spread: "0.04" }

Last Trade Price

const last = await client.getLastTradePrice("TOKEN_ID");  // { price, side }

Price History

const history = await client.getPricesHistory({
  market: "TOKEN_ID",
  interval: PriceHistoryInterval.ONE_DAY,
  fidelity: 60,  // data points every 60 minutes
});
// Each entry: { t: timestamp, p: price }

Interval	Description
1h	Last hour
6h	Last 6 hours
1d	Last day
1w	Last week
1m	Last month
max	All available

Use startTs/endTs for absolute ranges (mutually exclusive with interval).

Estimate Fill Price

Walk the orderbook to estimate slippage for a given order size:

const price = await client.calculateMarketPrice(
  "TOKEN_ID", Side.BUY, 500, OrderType.FOK
);

Batch Requests

All orderbook queries have batch variants (up to 500 tokens):

Single	Batch	REST
getOrderBook()	getOrderBooks()	POST /books
getPrice()	getPrices()	POST /prices
getMidpoint()	getMidpoints()	POST /midpoints
getSpread()	getSpreads()	POST /spreads
getLastTradePrice()	getLastTradesPrices()	—

const prices = await client.getPrices([
  { token_id: "TOKEN_A", side: Side.BUY },
  { token_id: "TOKEN_B", side: Side.BUY },
]);

Key Market Fields

Field	Description
tokenID / asset_id	ERC1155 token ID for an outcome
conditionID / market	Condition ID — identifies the market
questionID	Hash of UMA ancillary data
neg_risk	true for multi-outcome events
minimum_tick_size	Minimum price increment
enableOrderBook	Whether orderbook is active
slug	URL-friendly identifier
tokens	Array of { token_id, outcome } for both outcomes

Subgraph (Onchain Data)

GraphQL queries via Goldsky-hosted subgraphs:

Subgraph	Description
Positions	User token balances
Orders	Order book and trade events
Activity	Splits, merges, redemptions
Open Interest	Market and global OI
PNL	User position P&L

curl -X POST \
  https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/orderbook-subgraph/0.0.1/gn \
  -H "Content-Type: application/json" \
  -d '{"query": "query { orderbooks { id tradesQuantity } }"}'

Fetching Strategy

1. Specific market: fetch by slug — GET https://gamma-api.polymarket.com/events?slug=...
2. Category browsing: filter by tag — GET https://gamma-api.polymarket.com/events?tag_id=...
3. All active markets: paginate events — GET https://gamma-api.polymarket.com/events?active=true&closed=false
4. Always include active=true&closed=false unless you need historical data
5. Events > Markets: events contain their markets, reducing API calls