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 instruments with client.fetchPerpsInstruments().

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

where PerpsInstrument is:

type PerpsInstrument = {
  id: PerpsInstrumentId;
  category: PerpsInstrumentCategory;
  symbol: string;
  displaySymbol: string | undefined;
  closeOnly: boolean;
  settlement: PerpsInstrumentSettlement | undefined;
  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 PerpsInstrumentSettlement = {
  sequence: number;
  timestamp: EpochMilliseconds;
  price: DecimalString;
  insuranceDebit: DecimalString;
};

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

{
  "id": 1,
  "category": "crypto",
  "symbol": "BTC-PERP",
  "closeOnly": false,
  "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 }]
}

Use displaySymbol ?? symbol for a label and keep id for trading and storage. displaySymbol is optional and does not change the canonical symbol. closeOnly: true requires reduce-only orders. closeOnly defaults to false when absent from an older response.To inspect a retired instrument, filter by its known ID; retired instruments are omitted from the unfiltered collection.

const retired = await client.fetchPerpsInstruments({ instrumentId: 1 });

A retired instrument has a settlement record. This is an illustrative record:

Output: PerpsInstrumentSettlement

PerpsInstrumentSettlement Example

{
  "sequence": 1234567890,
  "timestamp": 1767225600000,
  "price": "65000.00",
  "insuranceDebit": "0"
}

settlement.timestamp is Unix milliseconds. sequence is the accepted engine sequence and must be a safe integer, at most Number.MAX_SAFE_INTEGER; the SDK rejects larger values. price and insuranceDebit remain exact decimal strings. insuranceDebit is the total quote amount debited from the insurance fund. An instrument without a record has settlement: undefined.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.
`displaySymbol`	Optional presentation label; falls back to `symbol`.
`closeOnly`	Whether new orders must be reduce-only.
`settlement`	Permanent retirement record, when present.
`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 instruments with client.fetch_perps_instruments().

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

Filter by a known instrument ID to also retrieve a retired instrument; retired instruments are omitted from the unfiltered collection.

instruments = await client.fetch_perps_instruments(instrument_id=1)

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

PerpsInstrument Example

{
  "id": 1,
  "category": "crypto",
  "symbol": "BTC-PERP",
  "display_symbol": null,
  "close_only": false,
  "settlement": null,
  "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 }]
}

Use display_symbol when it is not None, otherwise use symbol for the label. Keep id for trading and storage; the canonical symbol does not change. close_only=True requires reduce-only orders and defaults to False on older responses.A retired instrument has a PerpsInstrumentSettlement in settlement; otherwise it is None. This illustrative JSON serialization shows the record:

Output: PerpsInstrumentSettlement

PerpsInstrumentSettlement Example

{
  "sequence": 1234567890,
  "timestamp": "2026-01-01T00:00:00Z",
  "price": "65000.00",
  "insurance_debit": "0"
}

In Python, sequence is an exact int, timestamp is a UTC datetime, and price and insurance_debit are Decimal values. insurance_debit is the total quote amount debited from the insurance fund.PerpsInstrument exposes these attributes:

Attribute	Description
`id`	Instrument identifier.
`category`	Market category, such as crypto, index, equity, or commodity.
`symbol`	Human-readable market symbol.
`display_symbol`	Optional presentation label; falls back to `symbol`.
`close_only`	Whether new orders must be reduce-only.
`settlement`	Permanent retirement record, when present.
`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 a known instrument_id to also retrieve a retired instrument; retired instruments are omitted from the unfiltered collection.

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",
    "close_only": false,
    "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
  }
]

Use display_symbol when present and fall back to symbol for a label. Keep instrument_id for trading and storage; the canonical symbol does not change. close_only: true requires reduce-only orders.A retired instrument includes settlement. This is an illustrative record:

Output: InstrumentSettlement

InstrumentSettlement Example

{
  "sequence": 1234567890,
  "timestamp": 1767225600000,
  "price": "65000.00",
  "insurance_debit": "0"
}

sequence is the accepted engine sequence and timestamp is Unix milliseconds. price and insurance_debit are decimal strings; insurance_debit is the total quote amount debited from the insurance fund. Both settlement and display_symbol are omitted when unavailable.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.
`display_symbol`	Optional presentation label; falls back to `symbol`.
`close_only`	Whether new orders must be reduce-only.
`settlement`	Permanent retirement record, when present.
`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.

During close-only operation, pricing, funding, and risk management continue. A settlement record means the instrument has permanently retired: remaining positions close at the final settlement price, and trading cannot resume. The recorded cutoff permanently waives funding that had not already applied; already applied funding remains effective.

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;
  settlement: boolean;
  price: DecimalString;
  quantity: DecimalString;
  timestamp: EpochMilliseconds;
  hash?: TxHash;
};

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

settlement is true for an instrument-settlement close and defaults to false on older responses.

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.

PerpsTrade Example

{
  "trade_id": 987654,
  "instrument_id": 1,
  "side": "long",
  "settlement": false,
  "price": "65010.00",
  "quantity": "0.25",
  "timestamp": "2025-12-19T05:00:00Z",
  "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
}

settlement is True for an instrument-settlement close and defaults to False on older responses. timestamp is a UTC datetime; the JSON above shows its serialization.

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",
      "settlement": false,
      "price": "65010.00",
      "quantity": "0.25",
      "timestamp": 1766120400000,
      "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
    }
  ],
  "more": false
}

settlement is true for an instrument-settlement close.

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

Programs

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