Skip to main content
This guide covers how to retrieve market data including order books, prices, trades, and market metadata. Most market data endpoints are public and don’t require authentication.

​
Order Books

​
Get Single Order Book

Retrieve the full order book for a token: 
import { ClobClient } from "@polymarket/clob-client";

const host = "https://clob.polymarket.com";
const chainId = 137;
const clobClient = new ClobClient(host, chainId);

const tokenID = "71321045679252212594626385532706912750332728571942532289631379312455583992563";
const orderbook = await clobClient.getOrderBook(tokenID);

console.log("Market:", orderbook.market);
console.log("Asset ID:", orderbook.asset_id);
console.log("Bids:", orderbook.bids);  // Array of {price, size}
console.log("Asks:", orderbook.asks);  // Array of {price, size}
console.log("Tick Size:", orderbook.tick_size);
console.log("Min Order Size:", orderbook.min_order_size);
console.log("Last Trade Price:", orderbook.last_trade_price);
Response structure: 
interface OrderBookSummary {
  market: string;              // Condition ID
  asset_id: string;           // Token ID
  timestamp: string;
  bids: OrderSummary[];       // Buy orders
  asks: OrderSummary[];       // Sell orders
  min_order_size: string;
  tick_size: string;          // "0.01", "0.001", etc.
  neg_risk: boolean;
  last_trade_price: string;
  hash: string;               // Order book hash
}

interface OrderSummary {
  price: string;              // Price level
  size: string;               // Total size at this price
}

​
Get Multiple Order Books

Fetch multiple order books in a single request: 
import { BookParams, Side } from "@polymarket/clob-client";

const params: BookParams[] = [
  { token_id: "71321045...", side: Side.BUY },
  { token_id: "52114319...", side: Side.SELL },
];

const orderbooks = await clobClient.getOrderBooks(params);

for (const book of orderbooks) {
  console.log(`${book.asset_id}: ${book.bids.length} bids, ${book.asks.length} asks`);
}

​
Order Book Hash

Calculate a hash of the order book for change detection: 
const orderbook = await clobClient.getOrderBook(tokenID);
const hash = await clobClient.getOrderBookHash(orderbook);

console.log("Order book hash:", hash);
// Use this hash to detect if the order book has changed

​
Prices

​
Midpoint Price

Get the midpoint between best bid and best ask: 
const midpoint = await clobClient.getMidpoint(tokenID);
console.log("Midpoint price:", midpoint);

// Get multiple midpoints at once
const params: BookParams[] = [
  { token_id: "71321045...", side: Side.BUY },
  { token_id: "52114319...", side: Side.BUY },
];
const midpoints = await clobClient.getMidpoints(params);

​
Best Price

Get the best available price for a specific side: 
// Best ask (lowest sell price)
const bestAsk = await clobClient.getPrice(tokenID, Side.SELL);
console.log("Best ask:", bestAsk);

// Best bid (highest buy price)
const bestBid = await clobClient.getPrice(tokenID, Side.BUY);
console.log("Best bid:", bestBid);

// Get multiple prices at once
const prices = await clobClient.getPrices([
  { token_id: "71321045...", side: Side.BUY },
  { token_id: "71321045...", side: Side.SELL },
]);

​
Spread

Get the bid-ask spread: 
const spread = await clobClient.getSpread(tokenID);
console.log("Spread:", spread);

// Get multiple spreads
const spreads = await clobClient.getSpreads([
  { token_id: "71321045...", side: Side.BUY },
  { token_id: "52114319...", side: Side.BUY },
]);

​
Last Trade Price

Get the price of the most recent trade: 
const lastPrice = await clobClient.getLastTradePrice(tokenID);
console.log("Last trade price:", lastPrice);

// Get multiple last trade prices
const lastPrices = await clobClient.getLastTradesPrices([
  { token_id: "71321045...", side: Side.BUY },
  { token_id: "52114319...", side: Side.BUY },
]);

​
Price History

Get historical price data: 
import { PriceHistoryInterval } from "@polymarket/clob-client";

const priceHistory = await clobClient.getPricesHistory({
  market: "0x5f65177b394277fd294cd75650044e32ba009a95022d88a0c1d565897d72f8f1",
  interval: PriceHistoryInterval.ONE_HOUR,
  startTs: Math.floor(Date.now() / 1000) - 86400,  // 24 hours ago
  endTs: Math.floor(Date.now() / 1000),
  fidelity: 60,  // One data point per minute
});

for (const price of priceHistory) {
  console.log(`${new Date(price.t * 1000).toISOString()}: $${price.p}`);
}
Available intervals:
  • PriceHistoryInterval.MAX - Maximum available data
  • PriceHistoryInterval.ONE_WEEK - Past week
  • PriceHistoryInterval.ONE_DAY - Past 24 hours
  • PriceHistoryInterval.SIX_HOURS - Past 6 hours
  • PriceHistoryInterval.ONE_HOUR - Past hour

​
Trades

View historical trade data (requires L2 authentication):

​
Get Your Trades

// Get all your trades
const trades = await clobClient.getTrades();

for (const trade of trades) {
  console.log(`${trade.side} ${trade.size} @ ${trade.price}`);
  console.log(`  Order ID: ${trade.taker_order_id}`);
  console.log(`  Time: ${trade.match_time}`);
  console.log(`  Status: ${trade.status}`);
}

​
Filter Trades

import { TradeParams } from "@polymarket/clob-client";

// Filter by token
const tokenTrades = await clobClient.getTrades({
  asset_id: "71321045679252212594626385532706912750332728571942532289631379312455583992563",
});

// Filter by market
const marketTrades = await clobClient.getTrades({
  market: "0x5f65177b394277fd294cd75650044e32ba009a95022d88a0c1d565897d72f8f1",
});

// Filter by time range
const recentTrades = await clobClient.getTrades({
  after: "2024-01-01T00:00:00Z",
  before: "2024-01-31T23:59:59Z",
});

// Filter by wallet address
const walletTrades = await clobClient.getTrades({
  maker_address: "0x123...",
});

​
Paginated Trades

For large result sets, use pagination: 
let cursor = "MA==";  // Initial cursor

while (cursor) {
  const result = await clobClient.getTradesPaginated({
    asset_id: "71321045...",
  }, cursor);
  
  console.log(`Got ${result.trades.length} trades`);
  
  for (const trade of result.trades) {
    console.log(`${trade.side} ${trade.size} @ ${trade.price}`);
  }
  
  cursor = result.next_cursor;
  if (cursor === "LTE=") break;  // End of results
}

​
Get First Page Only

const trades = await clobClient.getTrades(
  { market: "0x5f65177b..." },
  true  // only_first_page
);

​
Markets

​
Get Markets List

Retrieve all available markets: 
// Get first page of markets
const marketsPage = await clobClient.getMarkets();
console.log("Markets:", marketsPage.data);
console.log("Next cursor:", marketsPage.next_cursor);

// Get all markets (paginate automatically)
let allMarkets = [];
let cursor = "MA==";

while (cursor !== "LTE=") {
  const page = await clobClient.getMarkets(cursor);
  allMarkets = [...allMarkets, ...page.data];
  cursor = page.next_cursor;
}

console.log(`Total markets: ${allMarkets.length}`);

​
Get Market Details

const conditionID = "0x5f65177b394277fd294cd75650044e32ba009a95022d88a0c1d565897d72f8f1";
const market = await clobClient.getMarket(conditionID);

console.log("Question:", market.question);
console.log("Outcomes:", market.outcomes);
console.log("End date:", market.end_date);

​
Simplified Markets

Get simplified market data (lighter payload): 
// Get simplified markets
const simplified = await clobClient.getSimplifiedMarkets();

// Get sampling markets (subset for performance)
const sampling = await clobClient.getSamplingMarkets();
const samplingSimplified = await clobClient.getSamplingSimplifiedMarkets();

​
Market Events

Get real-time market trade events: 
const conditionID = "0x5f65177b394277fd294cd75650044e32ba009a95022d88a0c1d565897d72f8f1";
const events = await clobClient.getMarketTradesEvents(conditionID);

for (const event of events) {
  console.log(`${event.user.username} ${event.side} ${event.size} @ ${event.price}`);
  console.log(`  Outcome: ${event.outcome}`);
  console.log(`  Time: ${event.timestamp}`);
  console.log(`  TX: ${event.transaction_hash}`);
}

​
Market Configuration

​
Tick Size

Get the minimum price increment for a market: 
const tickSize = await clobClient.getTickSize(tokenID);
console.log("Tick size:", tickSize);  // "0.01", "0.001", etc.

// Clear cached tick size to fetch fresh
clobClient.clearTickSizeCache(tokenID);

// Clear all cached tick sizes
clobClient.clearTickSizeCache();

​
Fee Rate

Get the fee rate for a market: 
const feeRateBps = await clobClient.getFeeRateBps(tokenID);
console.log(`Fee rate: ${feeRateBps} basis points (${feeRateBps / 100}%)`);

​
Negative Risk

Check if a market uses negative risk tokens: 
const isNegRisk = await clobClient.getNegRisk(tokenID);
console.log("Negative risk:", isNegRisk);

​
Server Time

Get the server’s current timestamp: 
const serverTime = await clobClient.getServerTime();
console.log("Server time:", serverTime);
console.log("Server date:", new Date(serverTime * 1000));

​
Real-Time Updates

For real-time order book and trade updates, use WebSockets: 
import WebSocket from "ws";

const ws = new WebSocket("wss://ws-subscriptions-clob.polymarket.com/ws/market");

ws.on("open", () => {
  // Subscribe to order book updates
  ws.send(JSON.stringify({
    type: "subscribe",
    channel: "orderbook",
    market: tokenID,
  }));
  
  // Subscribe to trade updates
  ws.send(JSON.stringify({
    type: "subscribe",
    channel: "trades",
    market: tokenID,
  }));
});

ws.on("message", (data) => {
  const message = JSON.parse(data.toString());
  
  if (message.channel === "orderbook") {
    console.log("Order book update:", message.data);
  } else if (message.channel === "trades") {
    console.log("New trade:", message.data);
  }
});

​
Performance Tips

Batch Requests

Use batch methods like getOrderBooks(), getMidpoints(), and getPrices() to fetch multiple items in one request.

Cache Tick Sizes

The client automatically caches tick sizes for 5 minutes. Use this to avoid redundant requests.

Use Pagination

For large datasets, use getTradesPaginated() instead of getTrades() to control memory usage.

WebSockets for Updates

Use WebSocket subscriptions for real-time updates instead of polling REST endpoints.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us