Perpetual Tickers

Use the perpetual ticker method when you need the market state a venue publishes together, such as mark and index prices, open interest, premium, and the current or predicted funding rate. Each event is a partial update for one source and market pair.

Methods

SDK	Method	Returns
Python	`perpetual_tickers(...)`	Single-pass iterator of typed perpetual ticker dictionaries
Rust	`perpetual_tickers(HistoricalQuery)`	`HistoricalStream<PerpetualTickerEvent>`
TypeScript	`perpetualTickers(options)`	`Promise<PerpetualTickerEvent[]>`

The Rust blocking client exposes the same perpetual_tickers(HistoricalQuery) method and returns a HistoricalIterator<PerpetualTickerEvent>.

Python signature

perpetual_tickers(source, market, from_=None, to=None, allow_gaps=False)

Parameters

Parameter	Type	Required	Notes
`source`	string	Yes	Non-empty perpetual data source ID
`market`	string	Yes	Non-empty market ID returned by Catalog
`from_` / `from`	string, datetime, date, or integer	No	Inclusive start time
`to`	string, datetime, date, or integer	No	Exclusive end time
`allow_gaps`	boolean	No	Python and Rust only; return covered rows and warn instead of failing on coverage gaps

Query perpetual tickers

from itertools import islice

from polaris_data import PolarisClient

with PolarisClient() as client:
    tickers = client.perpetual_tickers(
        source="hyperliquid",
        market="BTC",
    )
    print(list(islice(tickers, 2)))

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;
    let mut tickers = client
        .perpetual_tickers(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: None,
            to: None,
            allow_gaps: false,
            materialize_orderbooks: false,
        })
        .await?;

    while let Some(ticker) = tickers.next().await {
        let ticker = ticker?;
        println!("{} {:?}", ticker.timestamp(), ticker.data());
    }
    Ok(())
}

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

const tickers = await client.perpetualTickers({
  source: "hyperliquid",
  market: "BTC",
});

console.log(tickers[0]?.data.mark_price);

Event shapes

The exported PerpetualTickerEvent type is a legacy/v2 union in every SDK. Python and TypeScript also export the legacy and v2 event types directly. Rust exports LegacyPerpetualTickerEvent, PerpetualTickerEventV2, and the PerpetualTickerEvent enum.

Schema v2

{
  "collector_timestamp": 1704067200100,
  "collector_sequence": 1,
  "exchange_timestamp": 1704067199000,
  "exchange_sequence": null,
  "source": "hyperliquid",
  "market": "BTC",
  "type": "perpetual_ticker",
  "data": {
    "last_price": "98751.2",
    "mark_price": "98750.3",
    "index_price": "98749.9",
    "oracle_price": "98749.8",
    "mid_price": "98750.25",
    "open_interest": "1234.567890123456789",
    "funding_rate": "0.0000125",
    "funding_timestamp": 1704069000000,
    "predicted_funding_rate": "0.000013",
    "premium": "0.00001"
  }
}

Legacy

{
  "timestamp": 1704067200200,
  "source": "hyperliquid",
  "market": "BTC",
  "type": "perpetual_ticker",
  "data": {
    "funding_rate": "-0.000025"
  }
}

Use collector_timestamp as SDK time for v2 events and timestamp for legacy events. Rust provides timestamp(), source(), market(), and data() accessors across both versions. See Event envelope for the version-specific envelope fields.

Payload fields

Every payload field is optional because venues publish different subsets of state:

Field	Type	Meaning
`last_price`	decimal string	Most recent venue-published trade price
`mark_price`	decimal string	Price used by the venue for margin and liquidation calculations
`index_price`	decimal string	Venue-published underlying index price
`oracle_price`	decimal string	Venue-published oracle reference price
`mid_price`	decimal string	Venue-published midpoint
`open_interest`	decimal string	Open position or contract quantity in the venue’s units
`funding_rate`	decimal string	Current venue-published funding rate
`funding_timestamp`	integer	Funding timestamp in Unix milliseconds
`predicted_funding_rate`	decimal string	Venue-published estimate of a future funding rate
`premium`	decimal string	Venue-published premium or basis measure

Decimal values remain strings so standardization does not lose venue precision. Parse them with a decimal type for calculations instead of converting them to binary floating-point numbers.

Partial updates

Each event contains only the fields published in that venue message. The SDK does not carry omitted fields forward from earlier events. If you need a current state object, update only the keys present in each payload:

from polaris_data import PolarisClient

state = {}
with PolarisClient() as client:
    for event in client.perpetual_tickers(source="hyperliquid", market="BTC"):
        state.update(event["data"])

Do not interpret an omitted field as zero or null.

Validation and compatibility

Perpetual ticker events require non-empty source and market identities. The payload must contain at least one recognized field, decimal fields must be strings, and funding_timestamp must be an integer. Invalid rows fail decoding. Legacy and v2 envelopes remain supported. Generic events, replay, and realtime stream methods accept perpetual_ticker rows automatically; use the typed method when you only need perpetual ticker updates. The Rust blocking client can filter an already prepared historical replay with PreparedHistoricalReplay::perpetual_tickers(), which reuses the resolved local files without another catalog, coverage, or download request.

Choose between ticker and point-series methods

Use perpetual_tickers when you need the partial bundle of state published by a venue or want to reconstruct that state in event order. Use funding_rates or mark_prices when you only need one normalized point series, including Python Arrow or DataFrame output.

Perpetuals for end-to-end perpetual-market workflows
Funding rates for the focused funding point series
Mark prices for the focused mark-price point series
Events for mixed normalized event streams
Snapshots for snapshot-first historical reads

Foundation

Trade & Price Data

Orderbook & Liquidity

Derivatives Data

Perpetual Tickers

Methods

Python signature

Parameters

Query perpetual tickers

Event shapes

Schema v2

Legacy

Payload fields

Partial updates

Validation and compatibility

Choose between ticker and point-series methods

​Methods

​Python signature

​Parameters

​Query perpetual tickers

​Event shapes

​Schema v2

​Legacy

​Payload fields

​Partial updates

​Validation and compatibility

​Choose between ticker and point-series methods

​Related documentation

Methods

Python signature

Parameters

Query perpetual tickers

Event shapes

Schema v2

Legacy

Payload fields

Partial updates

Validation and compatibility

Choose between ticker and point-series methods

Related documentation