Skip to main content
Use market data to understand what can be traded, where the market is trading now, and how activity has changed over time.
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();

​
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.
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;
  riskTiers: PerpsRiskTier[];
};

type PerpsRiskTier = {
  lowerBound: DecimalString;
  maxLeverage: number;
};
PerpsInstrument includes the market metadata and trading constraints your app needs before submitting orders.
FieldDescription
idInstrument identifier.
categoryMarket category, such as crypto, index, equity, or commodity.
symbolHuman-readable market symbol.
baseAssetBase asset for the instrument.
quoteAssetQuote asset used for prices.
fundingIntervalFunding interval for the instrument, such as 1h.
quantityDecimalsDecimal precision for quantities.
priceDecimalsDecimal precision for prices.
priceBoundsPrice-bound value for the instrument.
liquidationFeeLiquidation fee value for the instrument.
maxOrderCountMaximum order count for the instrument.
minNotionalMinimum notional value for orders.
maxMarketNotionalMaximum notional value for market orders.
maxLimitNotionalMaximum notional value for limit orders.
maxLeverageMaximum leverage allowed for the instrument.
riskTiersRisk tiers for larger position sizes.

​
Fetch Tickers

Use tickers when you need a lightweight view of where one or more markets are trading now.
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;
};

​
Fetch the Order Book

Use the order book before choosing an order price or size. It shows available liquidity at the requested depth.
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;
};

​
List Candles

Use candles when your workflow needs time-bucketed price history for charts, backtests, or trading signals.
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;
};

​
List Trades

Use public trades when recent executions matter more than aggregated candles. This is useful for trade tape views and execution analysis.
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;
};

​
List Funding History

Use funding-rate history when estimating carry costs or explaining why Perps prices differ from the index over time.
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;
};