Market Data

Use market data to understand what can be traded, where the market is trading now, and how activity has changed over time.

TypeScript
Python
API

The TypeScript examples on this page use a PublicClient. The same market-data methods are also available on SecureClient instances.

import { createPublicClient } from "@polymarket/client";

const client = createPublicClient();

The Python examples on this page use an AsyncPublicClient. The same market-data methods are also available on AsyncSecureClient instances.

from polymarket import AsyncPublicClient

client = AsyncPublicClient()

Use the Perps REST API production URL.

https://api.perpetuals.polymarket.com

Fetch Instruments

Fetch instruments before your integration lets users choose or submit orders for a Perps market. Instrument data gives you the constraints needed to validate that workflow.

TypeScript
Python
API

Fetch the available instruments.

const instruments = await client.fetchPerpsInstruments();
// instruments: PerpsInstrument[]

where PerpsInstrument is:

type PerpsInstrument = {
  id: PerpsInstrumentId;
  category: PerpsInstrumentCategory;
  symbol: string;
  baseAsset: string;
  quoteAsset: string;
  fundingInterval: PerpsFundingInterval;
  quantityDecimals: number;
  priceDecimals: number;
  priceBounds: DecimalString;
  liquidationFee: DecimalString;
  maxOrderCount: number;
  minNotional: DecimalString;
  maxMarketNotional: DecimalString;
  maxLimitNotional: DecimalString;
  maxLeverage: number;
  isolatedOnly: boolean;
  riskTiers: PerpsRiskTier[];
};

type PerpsRiskTier = {
  lowerBound: DecimalString;
  maxLeverage: number;
};

{
  "id": 1,
  "category": "crypto",
  "symbol": "BTC-PERP",
  "baseAsset": "BTC",
  "quoteAsset": "USD",
  "fundingInterval": "1h",
  "quantityDecimals": 4,
  "priceDecimals": 2,
  "priceBounds": "0.1",
  "liquidationFee": "0.01",
  "maxOrderCount": 200,
  "minNotional": "1",
  "maxMarketNotional": "100000",
  "maxLimitNotional": "1000000",
  "maxLeverage": 10,
  "isolatedOnly": false,
  "riskTiers": [{ "lowerBound": "0", "maxLeverage": 10 }]
}

PerpsInstrument includes the market metadata and trading constraints your app needs before submitting orders.

Field	Description
`id`	Instrument identifier.
`category`	Market category, such as crypto, index, equity, or commodity.
`symbol`	Human-readable market symbol.
`baseAsset`	Base asset for the instrument.
`quoteAsset`	Quote asset used for prices.
`fundingInterval`	Funding interval for the instrument, such as `1h`.
`quantityDecimals`	Decimal precision for quantities.
`priceDecimals`	Decimal precision for prices.
`priceBounds`	Price-bound value for the instrument.
`liquidationFee`	Liquidation fee value for the instrument.
`maxOrderCount`	Maximum order count for the instrument.
`minNotional`	Minimum notional value for orders.
`maxMarketNotional`	Maximum notional value for market orders.
`maxLimitNotional`	Maximum notional value for limit orders.
`maxLeverage`	Maximum leverage allowed for the instrument.
`isolatedOnly`	Whether the instrument supports only isolated margin. When `false`, both cross and isolated margin modes are supported.
`riskTiers`	Risk tiers for larger position sizes.

Fetch the available instruments.

instruments = await client.fetch_perps_instruments()
# instruments: tuple[PerpsInstrument, ...]

Filter by instrument ID when you already know the market you need.

instruments = await client.fetch_perps_instruments(instrument_id=1)

PerpsInstrument includes the market metadata and trading constraints your app needs before submitting orders.

Example

{
  "id": 1,
  "category": "crypto",
  "symbol": "BTC-PERP",
  "base_asset": "BTC",
  "quote_asset": "USD",
  "funding_interval": "1h",
  "quantity_decimals": 4,
  "price_decimals": 2,
  "price_bounds": "0.1",
  "liquidation_fee": "0.01",
  "max_order_count": 200,
  "min_notional": "1",
  "max_market_notional": "100000",
  "max_limit_notional": "1000000",
  "max_leverage": 10,
  "isolated_only": false,
  "risk_tiers": [{ "lower_bound": "0", "max_leverage": 10 }]
}

PerpsInstrument exposes these attributes:

Attribute	Description
`id`	Instrument identifier.
`category`	Market category, such as crypto, index, equity, or commodity.
`symbol`	Human-readable market symbol.
`base_asset`	Base asset for the instrument.
`quote_asset`	Quote asset used for prices.
`funding_interval`	Funding interval for the instrument, such as `1h`.
`quantity_decimals`	Decimal precision for quantities.
`price_decimals`	Decimal precision for prices.
`price_bounds`	Price-bound value for the instrument.
`liquidation_fee`	Liquidation fee value for the instrument.
`max_order_count`	Maximum order count for the instrument.
`min_notional`	Minimum notional value for orders.
`max_market_notional`	Maximum notional value for market orders.
`max_limit_notional`	Maximum notional value for limit orders.
`max_leverage`	Maximum leverage allowed for the instrument.
`isolated_only`	Whether the instrument supports only isolated margin. When `False`, both cross and isolated margin modes are supported.
`risk_tiers`	Risk tiers for larger position sizes.
`risk_tiers[].lower_bound`	Lower notional bound for the risk tier.
`risk_tiers[].max_leverage`	Maximum leverage allowed for the risk tier.

Fetch the available instruments.

curl "https://api.perpetuals.polymarket.com/v1/info/instruments"

Filter by instrument ID when you already know the market you need.

curl -G "https://api.perpetuals.polymarket.com/v1/info/instruments" \
  --data-urlencode "instrument_id=1"

The response is an array of instruments.

[
  {
    "instrument_id": 1,
    "instrument_type": "perpetual",
    "category": "crypto",
    "symbol": "BTC-PERP",
    "base_asset": "BTC",
    "quote_asset": "USD",
    "funding_interval": "1h",
    "quantity_decimals": 4,
    "price_decimals": 2,
    "price_bounds": "0.1",
    "liquidation_fee": "0.01",
    "max_order_count": 200,
    "min_notional": "1",
    "max_market_notional": "100000",
    "max_limit_notional": "1000000",
    "max_leverage": 10,
    "isolated_only": false,
    "risk_tiers": [{ "lower_bound": "0", "max_leverage": 10 }],
    "ui_live_time": null
  }
]

Each instrument object includes the market metadata and trading constraints your app needs before submitting orders.

Field	Description
`instrument_id`	Instrument identifier.
`instrument_type`	Instrument type. Perps instruments use `perpetual`.
`category`	Market category, such as `crypto`, `index`, `equity`, or `commodity`.
`symbol`	Human-readable market symbol.
`base_asset`	Base asset for the instrument.
`quote_asset`	Quote asset used for prices.
`funding_interval`	Funding interval for the instrument, such as `1h`.
`quantity_decimals`	Decimal precision for quantities.
`price_decimals`	Decimal precision for prices.
`price_bounds`	Price-bound value for the instrument.
`liquidation_fee`	Liquidation fee value for the instrument.
`max_order_count`	Maximum order count for the instrument.
`min_notional`	Minimum notional value for orders.
`max_market_notional`	Maximum notional value for market orders.
`max_limit_notional`	Maximum notional value for limit orders.
`max_leverage`	Maximum leverage allowed for the instrument.
`isolated_only`	Whether the instrument supports only isolated margin. When `false`, both cross and isolated margin modes are supported.
`risk_tiers`	Risk tiers for larger position sizes.
`risk_tiers[].lower_bound`	Lower notional bound for the risk tier.
`risk_tiers[].max_leverage`	Maximum leverage allowed for the risk tier.
`ui_live_time`	Advisory display time in Unix milliseconds, or `null` when hidden from first-party interfaces.

Most trading and market-data integrations can ignore ui_live_time. It is advisory metadata for interface display timing and does not control whether the API returns an instrument or whether that instrument can be traded. A non-null value indicates when first-party interfaces may display it.

Fetch Tickers

Use tickers when you need a lightweight view of where one or more markets are trading now.

TypeScript
Python
API

Fetch one ticker when you already know which instrument your integration is tracking.

const ticker = await client.fetchPerpsTicker({
  instrumentId: instrument.id,
});
// ticker: PerpsTicker

Fetch all tickers to build a market list or refresh a dashboard.

const tickers = await client.fetchPerpsTickers();
// tickers: PerpsTicker[]

where PerpsTicker is:

type PerpsTicker = {
  instrumentId: PerpsInstrumentId;
  symbol: string;
  indexPrice: DecimalString;
  markPrice: DecimalString;
  lastPrice: DecimalString;
  midPrice: DecimalString;
  openInterest: DecimalString;
  fundingRate: DecimalString;
  nextFunding: EpochMilliseconds;
  volume24h?: DecimalString;
  openPrice?: DecimalString;
  timestamp?: EpochMilliseconds;
};

{
  "instrumentId": 1,
  "symbol": "BTC-PERP",
  "indexPrice": "65000.00",
  "markPrice": "65012.50",
  "lastPrice": "65010.00",
  "midPrice": "65011.25",
  "openInterest": "125.4",
  "fundingRate": "0.0001",
  "nextFunding": 1766124000000,
  "volume24h": "2450000",
  "openPrice": "64250.00",
  "timestamp": 1766120400000
}

Fetch one ticker when you already know which instrument your integration is tracking.

ticker = await client.fetch_perps_ticker(instrument_id=instrument.id)
# ticker: PerpsTicker

Fetch all tickers to build a market list or refresh a dashboard.

tickers = await client.fetch_perps_tickers()
# tickers: tuple[PerpsTicker, ...]

Use the returned ticker for current price, open interest, and funding state.

Example

{
  "instrument_id": 1,
  "symbol": "BTC-PERP",
  "index_price": "65000.00",
  "mark_price": "65012.50",
  "last_price": "65010.00",
  "mid_price": "65011.25",
  "open_interest": "125.4",
  "funding_rate": "0.0001",
  "next_funding": 1766124000000,
  "volume_24h": "2450000",
  "open_price": "64250.00",
  "timestamp": 1766120400000
}

Fetch all tickers to build a market list or refresh a dashboard.

curl "https://api.perpetuals.polymarket.com/v1/info/tickers"

Filter by instrument ID when you only need one ticker.

curl -G "https://api.perpetuals.polymarket.com/v1/info/tickers" \
  --data-urlencode "instrument_id=1"

The response is an array of ticker snapshots.

[
  {
    "instrument_id": 1,
    "symbol": "BTC-PERP",
    "index_price": "65000.00",
    "mark_price": "65012.50",
    "last_price": "65010.00",
    "mid_price": "65011.25",
    "open_interest": "125.4",
    "funding_rate": "0.0001",
    "next_funding": 1766124000000,
    "timestamp": 1766120400000
  }
]

Ticker snapshots are refreshed in the background and may be up to ten seconds old. When the gateway cannot guarantee that bound — for example while its data store is unavailable — the endpoint returns 503 Service Unavailable rather than stale prices. Treat a 503 as transient and retry with backoff.

Fetch the Order Book

Use the order book before choosing an order price or size. It shows available liquidity at the requested depth.

TypeScript
Python
API

Choose how many price levels to request. Supported depths are 10, 100, 500, and 1000. When omitted, the SDK requests 100 levels.

// depth: PerpsBookDepth
const depth = 100;

Fetch the book for the selected instrument. Bids and asks are returned as price levels with decimal string prices and quantities.

const book = await client.fetchPerpsBook({
  instrumentId: instrument.id,
  depth,
});

const bestBid = book.bids[0];
const bestAsk = book.asks[0];

// book: PerpsBook
// bestBid: PerpsBookLevel | undefined
// bestAsk: PerpsBookLevel | undefined

where PerpsBook and PerpsBookLevel are:

type PerpsBook = {
  instrumentId: PerpsInstrumentId;
  bids: PerpsBookLevel[];
  asks: PerpsBookLevel[];
  timestamp: EpochMilliseconds;
  sequence: number;
};

type PerpsBookLevel = {
  price: DecimalString;
  quantity: DecimalString;
};

{
  "instrumentId": 1,
  "bids": [
    { "price": "65010.00", "quantity": "0.75" },
    { "price": "65009.50", "quantity": "1.2" }
  ],
  "asks": [
    { "price": "65012.50", "quantity": "0.6" },
    { "price": "65013.00", "quantity": "1.1" }
  ],
  "timestamp": 1766120400000,
  "sequence": 123456
}

Choose how many price levels to request. Supported depths are 10, 100, 500, and 1000. When omitted, the SDK requests 100 levels.

depth = 100

Fetch the book for the selected instrument. Bids and asks are returned as price levels with decimal string prices and quantities.

book = await client.fetch_perps_book(
    instrument_id=instrument.id,
    depth=depth,
)

best_bid = book.bids[0] if book.bids else None
best_ask = book.asks[0] if book.asks else None

# book: PerpsBook
# best_bid: PerpsBookLevel | None
# best_ask: PerpsBookLevel | None

Use book.bids and book.asks for bid and ask price levels.

Example

{
  "instrument_id": 1,
  "bids": [
    { "price": "65010.00", "quantity": "0.75" },
    { "price": "65009.50", "quantity": "1.2" }
  ],
  "asks": [
    { "price": "65012.50", "quantity": "0.6" },
    { "price": "65013.00", "quantity": "1.1" }
  ],
  "timestamp": 1766120400000,
  "sequence": 123456
}

Fetch the order book for an instrument. Supported depths are 10, 100, 500, and 1000; when omitted, the API uses 100.

curl -G "https://api.perpetuals.polymarket.com/v1/info/book" \
  --data-urlencode "instrument_id=1" \
  --data-urlencode "depth=100"

The response returns bids and asks as [price, quantity] levels.

{
  "instrument_id": 1,
  "bids": [
    ["65010.00", "0.75"],
    ["65009.50", "1.2"]
  ],
  "asks": [
    ["65012.50", "0.6"],
    ["65013.00", "1.1"]
  ],
  "timestamp": 1766120400000,
  "sequence": 123456
}

Each bids and asks level is [price, quantity].

List Candles

Use candles when your workflow needs time-bucketed price history for charts, backtests, or trading signals.

TypeScript
Python
API

The SDK paginates candle history. When start is omitted, it starts from the past 24 hours.

import { PerpsKlineInterval } from "@polymarket/client";

const pages = client.listPerpsCandles({
  instrumentId: instrument.id,
  interval: PerpsKlineInterval.OneMinute,
});

for await (const page of pages) {
  for (const candle of page.items) {
    // candle: PerpsCandle
  }
}

where PerpsCandle is:

type PerpsCandle = {
  timestamp: EpochMilliseconds;
  open: DecimalString;
  high: DecimalString;
  low: DecimalString;
  close: DecimalString;
  volume: DecimalString;
  trades: number;
};

{
  "timestamp": 1766120400000,
  "open": "65000.00",
  "high": "65025.00",
  "low": "64980.00",
  "close": "65010.00",
  "volume": "42.5",
  "trades": 18
}

The SDK paginates candle history. When start is omitted, it starts from the past 24 hours.

pages = client.list_perps_candles(
    instrument_id=instrument.id,
    interval="1m",
)

async for page in pages:
    for candle in page.items:
        # candle: PerpsCandle
        pass

Each candle contains one OHLCV bucket.

Example

{
  "timestamp": 1766120400000,
  "open": "65000.00",
  "high": "65025.00",
  "low": "64980.00",
  "close": "65010.00",
  "volume": "42.5",
  "trades": 18
}

Fetch candles for an instrument and interval. start_timestamp is required; end_timestamp is optional. The API returns at most 1000 candles per request.

curl -G "https://api.perpetuals.polymarket.com/v1/info/klines" \
  --data-urlencode "instrument_id=1" \
  --data-urlencode "interval=1m" \
  --data-urlencode "start_timestamp=1766120400000"

The response returns candles in data and a more flag for continuation.

{
  "data": [
    [1766120400000, "65000.00", "65025.00", "64980.00", "65010.00", "42.5", 18]
  ],
  "more": false
}

Each candle is [timestamp, open, high, low, close, volume, trades].

Fetch Mark Price History

Mark price history shows how an instrument’s mark price changed over time. Each data point contains the last mark price recorded for an interval, independent of whether trades occurred during that interval.

Fetch bucketed mark prices for an instrument and interval. start_timestamp is required; end_timestamp is optional. The API returns at most 1000 points per request.

curl -G "https://api.perpetuals.polymarket.com/v1/info/mark-history" \
  --data-urlencode "instrument_id=1" \
  --data-urlencode "interval=1s" \
  --data-urlencode "start_timestamp=1766120400000"

The response returns mark price points in data and a more flag for continuation. Only buckets that contain at least one mark update are included.

{
  "data": [
    [1766120400000, "160.00"],
    [1766120401000, "160.05"]
  ],
  "more": false
}

Each point is [bucket_open_time_ms, last_mark_price_in_bucket].

List Trades

Use public trades when recent executions matter more than aggregated candles. This is useful for trade tape views and execution analysis.

TypeScript
Python
API

The SDK paginates trade history, including cursor handling and boundary deduplication.

const pages = client.listPerpsTrades({
  instrumentId: instrument.id,
});

for await (const page of pages) {
  for (const trade of page.items) {
    // trade: PerpsPublicTrade
  }
}

where PerpsPublicTrade is:

type PerpsPublicTrade = {
  tradeId: PerpsTradeId;
  instrumentId: PerpsInstrumentId;
  side: PerpsSide;
  price: DecimalString;
  quantity: DecimalString;
  timestamp: EpochMilliseconds;
  hash?: TxHash;
};

{
  "tradeId": 987654,
  "instrumentId": 1,
  "side": "long",
  "price": "65010.00",
  "quantity": "0.25",
  "timestamp": 1766120400000,
  "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
}

The SDK paginates trade history, including cursor handling and boundary deduplication.

pages = client.list_perps_trades(instrument_id=instrument.id)

async for page in pages:
    for trade in page.items:
        # trade: PerpsTrade
        pass

Each trade contains one public execution.

Example

{
  "trade_id": 987654,
  "instrument_id": 1,
  "side": "long",
  "price": "65010.00",
  "quantity": "0.25",
  "timestamp": 1766120400000,
  "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
}

Fetch recent public trades for an instrument. start_timestamp and end_timestamp are optional. The API returns at most 100 trades per request.

curl -G "https://api.perpetuals.polymarket.com/v1/info/trades" \
  --data-urlencode "instrument_id=1"

The response returns trades in data and a more flag for continuation.

{
  "data": [
    {
      "trade_id": 987654,
      "instrument_id": 1,
      "side": "long",
      "price": "65010.00",
      "quantity": "0.25",
      "timestamp": 1766120400000,
      "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
    }
  ],
  "more": false
}

List Funding History

Use funding-rate history when estimating carry costs or explaining why Perps prices differ from the index over time.

TypeScript
Python
API

The SDK paginates funding-rate history.

const pages = client.listPerpsFundingHistory({
  instrumentId: instrument.id,
});

for await (const page of pages) {
  for (const fundingRate of page.items) {
    // fundingRate: PerpsFundingRate
  }
}

where PerpsFundingRate is:

type PerpsFundingRate = {
  fundingRate: DecimalString;
  timestamp: EpochMilliseconds;
};

{
  "fundingRate": "0.0001",
  "timestamp": 1766120400000
}

The SDK paginates funding-rate history.

pages = client.list_perps_funding_history(instrument_id=instrument.id)

async for page in pages:
    for funding_rate in page.items:
        # funding_rate: PerpsFundingRate
        pass

Each funding-rate entry contains one historical observation.

Example

{
  "funding_rate": "0.0001",
  "timestamp": 1766120400000
}

Fetch historical funding rates for an instrument. start_timestamp and end_timestamp are optional. The API returns at most 100 funding-rate entries per request.

curl -G "https://api.perpetuals.polymarket.com/v1/info/funding" \
  --data-urlencode "instrument_id=1"

The response returns funding rates in data and a more flag for continuation.

{
  "data": [
    {
      "funding_rate": "0.0001",
      "timestamp": 1766120400000
    }
  ],
  "more": false
}

Getting Started

Build With Perps

Learn About Trading

Resources

Fetch Instruments

Fetch Tickers

Fetch the Order Book

List Candles

Fetch Mark Price History

List Trades

List Funding History

​Fetch Instruments

​Fetch Tickers

​Fetch the Order Book

​List Candles

​Fetch Mark Price History

​List Trades

​List Funding History

Fetch Instruments

Fetch Tickers

Fetch the Order Book

List Candles

Fetch Mark Price History

List Trades

List Funding History