> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Market Data

> Discover Perps markets and monitor public market activity

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

**TypeScript**

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

```ts theme={null}
import { createPublicClient } from "@polymarket/client";

const client = createPublicClient();
```

**Python**

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

```python theme={null}
from polymarket import AsyncPublicClient

client = AsyncPublicClient()
```

**API**

Use the Perps REST API production URL.

```text theme={null}
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**

Fetch instruments with `client.fetchPerpsInstruments()`.

```ts theme={null}
const instruments = await client.fetchPerpsInstruments();
// instruments: PerpsInstrument[]
```

where `PerpsInstrument` is:

```ts PerpsInstrument Type theme={null}
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;
};
```

```json PerpsInstrument Example theme={null}
{
  "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.

```ts theme={null}
const retired = await client.fetchPerpsInstruments({ instrumentId: 1 });
```

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

> **Output: PerpsInstrumentSettlement**
>
> ```json PerpsInstrumentSettlement Example theme={null}
> {
>   "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. |

**Python**

Fetch instruments with `client.fetch_perps_instruments()`.

```python theme={null}
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.

```python theme={null}
instruments = await client.fetch_perps_instruments(instrument_id=1)
```

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

```json PerpsInstrument Example theme={null}
{
  "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**
>
> ```json PerpsInstrumentSettlement Example theme={null}
> {
>   "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. |

**API**

Fetch the available instruments.

```bash theme={null}
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.

```bash theme={null}
curl -G "https://api.perpetuals.polymarket.com/v1/info/instruments" \
  --data-urlencode "instrument_id=1"
```

The response is an array of instruments.

```json theme={null}
[
  {
    "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**
>
> ```json InstrumentSettlement Example theme={null}
> {
>   "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. |

> [!NOTE]
>
> 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**

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

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

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

```ts theme={null}
const tickers = await client.fetchPerpsTickers();
// tickers: PerpsTicker[]
```

where `PerpsTicker` is:

```ts PerpsTicker Type theme={null}
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;
};
```

```json PerpsTicker Example theme={null}
{
  "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
}
```

**Python**

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

```python theme={null}
ticker = await client.fetch_perps_ticker(instrument_id=instrument.id)
# ticker: PerpsTicker
```

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

```python theme={null}
tickers = await client.fetch_perps_tickers()
# tickers: tuple[PerpsTicker, ...]
```

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

```json Example theme={null}
{
  "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
}
```

**API**

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

```bash theme={null}
curl "https://api.perpetuals.polymarket.com/v1/info/tickers"
```

Filter by instrument ID when you only need one ticker.

```bash theme={null}
curl -G "https://api.perpetuals.polymarket.com/v1/info/tickers" \
  --data-urlencode "instrument_id=1"
```

The response is an array of ticker snapshots.

```json theme={null}
[
  {
    "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**

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

```ts theme={null}
// 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.

```ts theme={null}
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:

```ts PerpsBook Type theme={null}
type PerpsBook = {
  instrumentId: PerpsInstrumentId;
  bids: PerpsBookLevel[];
  asks: PerpsBookLevel[];
  timestamp: EpochMilliseconds;
  sequence: number;
};

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

```json PerpsBook Example theme={null}
{
  "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
}
```

**Python**

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

```python theme={null}
depth = 100
```

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

```python theme={null}
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.

```json Example theme={null}
{
  "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
}
```

**API**

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

```bash theme={null}
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.

```json theme={null}
{
  "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**

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

```ts theme={null}
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:

```ts PerpsCandle Type theme={null}
type PerpsCandle = {
  timestamp: EpochMilliseconds;
  open: DecimalString;
  high: DecimalString;
  low: DecimalString;
  close: DecimalString;
  volume: DecimalString;
  trades: number;
};
```

```json PerpsCandle Example theme={null}
{
  "timestamp": 1766120400000,
  "open": "65000.00",
  "high": "65025.00",
  "low": "64980.00",
  "close": "65010.00",
  "volume": "42.5",
  "trades": 18
}
```

**Python**

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

```python theme={null}
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.

```json Example theme={null}
{
  "timestamp": 1766120400000,
  "open": "65000.00",
  "high": "65025.00",
  "low": "64980.00",
  "close": "65010.00",
  "volume": "42.5",
  "trades": 18
}
```

**API**

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

```bash theme={null}
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.

```json theme={null}
{
  "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.

**API**

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.

```bash theme={null}
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.

```json theme={null}
{
  "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**

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

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

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

where `PerpsPublicTrade` is:

```ts PerpsPublicTrade Type theme={null}
type PerpsPublicTrade = {
  tradeId: PerpsTradeId;
  instrumentId: PerpsInstrumentId;
  side: PerpsSide;
  settlement: boolean;
  price: DecimalString;
  quantity: DecimalString;
  timestamp: EpochMilliseconds;
  hash?: TxHash;
};
```

```json PerpsPublicTrade Example theme={null}
{
  "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.

**Python**

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

```python theme={null}
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.

```json PerpsTrade Example theme={null}
{
  "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.

**API**

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

```bash theme={null}
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.

```json theme={null}
{
  "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**

The SDK paginates funding-rate history.

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

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

where `PerpsFundingRate` is:

```ts PerpsFundingRate Type theme={null}
type PerpsFundingRate = {
  fundingRate: DecimalString;
  timestamp: EpochMilliseconds;
};
```

```json PerpsFundingRate Example theme={null}
{
  "fundingRate": "0.0001",
  "timestamp": 1766120400000
}
```

**Python**

The SDK paginates funding-rate history.

```python theme={null}
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.

```json Example theme={null}
{
  "funding_rate": "0.0001",
  "timestamp": 1766120400000
}
```

**API**

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.

```bash theme={null}
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.

```json theme={null}
{
  "data": [
    {
      "funding_rate": "0.0001",
      "timestamp": 1766120400000
    }
  ],
  "more": false
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.