Skip to main content
Polymarket markets represent prediction markets where users trade on the outcome of real-world events. Each market consists of conditional tokens that represent different possible outcomes, and the CLOB facilitates trading these tokens.

​
Market Structure

Every Polymarket market is built on conditional tokens following the CTF (Conditional Token Framework) standard:

Condition ID

Unique identifier for the market (66-character hex string starting with 0x)

Token IDs

Each outcome has a unique token ID (large integer representing the conditional token)

Binary Outcomes

Most markets have YES/NO outcomes, though multi-outcome markets are supported

USDC Settlement

All markets settle in USDC collateral on Polygon

​
Conditional Tokens

Conditional tokens represent a claim on collateral contingent on a specific outcome occurring.

​
Token ID Format

Token IDs are large integers derived from the condition ID and outcome index: 
// Example token IDs from a binary market
const YES_TOKEN = "71321045679252212594626385532706912750332728571942532289631379312455583992563";
const NO_TOKEN = "52114319501245915516055106046884209969926127482827954674443846427813813222426";

// These represent the same market but different outcomes

​
Token Properties

interface Token {
    token_id: string;   // Unique token identifier
    outcome: string;    // "Yes" or "No" (or other outcome names)
    price: number;      // Current market price (0.0 to 1.0)
}
Token prices always sum to 1.0 in binary markets. If YES is trading at 0.65, NO will be at 0.35.

​
Retrieving Markets

​
Get All Markets

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

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

// Get paginated markets
let cursor = "MA=="; // Initial cursor
while (cursor !== "END") {
  const response = await client.getMarkets(cursor);
  
  console.log(`Found ${response.count} markets`);
  for (const market of response.data) {
    console.log(market);
  }
  
  cursor = response.next_cursor;
}

// Or simplified markets (less data)
const simplified = await client.getSimplifiedMarkets();

​
Get Specific Market

// Get market by condition ID
const conditionId = "0x1234567890abcdef...";
const market = await client.getMarket(conditionId);

console.log(market);
// {
//   condition_id: "0x1234...",
//   question: "Will X happen by Y date?",
//   tokens: [
//     { token_id: "123...", outcome: "Yes", price: 0.65 },
//     { token_id: "456...", outcome: "No", price: 0.35 }
//   ],
//   ...
// }

​
Sampling Markets

// Get random sample of active markets
const samplingMarkets = await client.getSamplingMarkets();

// Get random sample of simplified markets
const simplifiedSampling = await client.getSamplingSimplifiedMarkets();

​
Order Books

Each token has its own order book with bids and asks: 
interface OrderBookSummary {
    market: string;          // Condition ID
    asset_id: string;        // Token ID
    timestamp: string;       // Last update time
    bids: OrderSummary[];    // Buy orders
    asks: OrderSummary[];    // Sell orders
    min_order_size: string;  // Minimum order size
    tick_size: string;       // Price increment ("0.01", "0.001", etc.)
    neg_risk: boolean;       // Whether market uses neg-risk
    last_trade_price: string; // Last executed trade price
    hash: string;            // Orderbook hash for verification
}

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

​
Getting Order Book Data

// Get single order book
const tokenId = "71321045679252212594626385532706912750332728571942532289631379312455583992563";
const book = await client.getOrderBook(tokenId);

console.log("Bids:", book.bids);
// [{ price: "0.64", size: "100" }, { price: "0.63", size: "250" }, ...]

console.log("Asks:", book.asks);
// [{ price: "0.66", size: "150" }, { price: "0.67", size: "200" }, ...]

console.log("Tick size:", book.tick_size);
// "0.01"

// Verify orderbook integrity
const hash = await client.getOrderBookHash(book);
console.log("Hash matches:", hash === book.hash);

​
Batch Order Book Queries

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

// Get multiple order books at once
const books = await client.getOrderBooks([
  { token_id: "123...", side: Side.BUY },
  { token_id: "456...", side: Side.SELL },
]);

​
Market Data

​
Current Prices

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

const tokenId = "71321045679252212594626385532706912750332728571942532289631379312455583992563";

// Get midpoint price
const midpoint = await client.getMidpoint(tokenId);
console.log(midpoint); // { mid: "0.65" }

// Get best bid or ask
const bestBid = await client.getPrice(tokenId, Side.BUY);
const bestAsk = await client.getPrice(tokenId, Side.SELL);

// Get spread
const spread = await client.getSpread(tokenId);
console.log(spread); // { spread: "0.02" }

// Get last trade price
const lastPrice = await client.getLastTradePrice(tokenId);
console.log(lastPrice); // { price: "0.65" }

​
Batch Price Queries

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

// Get multiple midpoints
const midpoints = await client.getMidpoints([
  { token_id: "123...", side: Side.BUY },
  { token_id: "456...", side: Side.BUY },
]);

// Get multiple best prices
const prices = await client.getPrices([
  { token_id: "123...", side: Side.BUY },
  { token_id: "456...", side: Side.SELL },
]);

// Get multiple spreads
const spreads = await client.getSpreads([
  { token_id: "123...", side: Side.BUY },
  { token_id: "456...", side: Side.BUY },
]);

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

​
Price History

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

// Get historical prices
const history = await client.getPricesHistory({
  market: "0x1234...",  // condition ID
  interval: PriceHistoryInterval.ONE_HOUR,
  fidelity: 100,  // number of data points
});

console.log(history);
// [
//   { t: 1640000000, p: 0.60 },  // timestamp, price
//   { t: 1640003600, p: 0.62 },
//   ...
// ]

// Available intervals
enum PriceHistoryInterval {
    MAX = "max",
    ONE_WEEK = "1w",
    ONE_DAY = "1d",
    SIX_HOURS = "6h",
    ONE_HOUR = "1h",
}

​
Market Configuration

​
Tick Size

Tick size determines the minimum price increment for a market: 
type TickSize = "0.1" | "0.01" | "0.001" | "0.0001";

// Get tick size for a token
const tickSize = await client.getTickSize(tokenId);
console.log(tickSize); // "0.01"

// Valid prices for "0.01": 0.01, 0.02, 0.03, ..., 0.99
// Valid prices for "0.001": 0.001, 0.002, 0.003, ..., 0.999

// Clear tick size cache to force refresh
client.clearTickSizeCache(tokenId);
Tick sizes are cached for 5 minutes by default. Order books also contain tick size information and update the cache automatically.

​
Neg-Risk Markets

Neg-risk (negative risk) markets use a special mechanism for capital efficiency: 
// Check if market uses neg-risk
const isNegRisk = await client.getNegRisk(tokenId);
console.log(isNegRisk); // true or false

// Use neg-risk when creating orders
const order = await client.createOrder(
  {
    tokenID: tokenId,
    price: 0.65,
    size: 100,
    side: Side.BUY,
  },
  {
    tickSize: "0.01",
    negRisk: isNegRisk,  // Important for correct order creation
  }
);
Neg-risk allows traders to use their outcome tokens as collateral for opposite-side trades, reducing capital requirements.

​
Fee Rates

Fee rates vary by market and are specified in basis points: 
// Get fee rate for a market (in basis points)
const feeRateBps = await client.getFeeRateBps(tokenId);
console.log(feeRateBps); // e.g., 100 = 1.00%

// Fee is automatically applied when creating orders
const order = await client.createOrder({
  tokenID: tokenId,
  price: 0.65,
  size: 100,
  side: Side.BUY,
  // feeRateBps is auto-populated from market configuration
});

​
Market Events

Track real-time trading activity on markets: 
// Get recent trade events for a market
const conditionId = "0x1234...";
const events = await client.getMarketTradesEvents(conditionId);

for (const event of events) {
  console.log(event);
  // {
  //   event_type: "trade",
  //   market: { condition_id: "0x1234...", question: "...", ... },
  //   user: { address: "0xabc...", username: "trader123", ... },
  //   side: "BUY",
  //   size: "100",
  //   price: "0.65",
  //   outcome: "Yes",
  //   outcome_index: 0,
  //   transaction_hash: "0xdef...",
  //   timestamp: "2024-01-01T12:00:00Z"
  // }
}

​
Asset Types

The CLOB distinguishes between two asset types: 
enum AssetType {
    COLLATERAL = "COLLATERAL",    // USDC
    CONDITIONAL = "CONDITIONAL",  // Outcome tokens
}

// Get USDC balance
const usdcBalance = await client.getBalanceAllowance({
  asset_type: AssetType.COLLATERAL,
});

console.log(`USDC: ${usdcBalance.balance}`);

// Get token balance
const tokenBalance = await client.getBalanceAllowance({
  asset_type: AssetType.CONDITIONAL,
  token_id: "71321045679252212594626385532706912750332728571942532289631379312455583992563",
});

console.log(`Token: ${tokenBalance.balance}`);

​
Example: Complete Market Analysis

import { ClobClient, Side } from "@polymarket/clob-client";

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

// 1. Find a market
const conditionId = "0x1234567890abcdef...";
const market = await client.getMarket(conditionId);

console.log(`Market: ${market.question}`);
console.log(`Tokens:`, market.tokens);

const yesToken = market.tokens[0].token_id;
const noToken = market.tokens[1].token_id;

// 2. Get market configuration
const tickSize = await client.getTickSize(yesToken);
const negRisk = await client.getNegRisk(yesToken);
const feeRate = await client.getFeeRateBps(yesToken);

console.log(`Tick size: ${tickSize}`);
console.log(`Neg-risk: ${negRisk}`);
console.log(`Fee rate: ${feeRate} bps`);

// 3. Analyze order book
const book = await client.getOrderBook(yesToken);
const midpoint = await client.getMidpoint(yesToken);
const spread = await client.getSpread(yesToken);

console.log(`Best bid: ${book.bids[0]?.price}`);
console.log(`Best ask: ${book.asks[0]?.price}`);
console.log(`Midpoint: ${midpoint.mid}`);
console.log(`Spread: ${spread.spread}`);

// 4. Get price history
const history = await client.getPricesHistory({
  market: conditionId,
  interval: "1d",
  fidelity: 24,
});

console.log(`24h price range: ${Math.min(...history.map(h => h.p))} - ${Math.max(...history.map(h => h.p))}`);

// 5. Recent activity
const events = await client.getMarketTradesEvents(conditionId);
console.log(`Recent trades: ${events.length}`);

Orders

Learn how to create orders for markets

Trading

Understand the complete trading workflow

Market Data API

Complete API reference for market data

Gamma Markets API

Explore markets using the Gamma API

Build docs developers (and LLMs) love

Get started for freeTalk to us