> ## Documentation Index > Fetch the complete documentation index at: https://docs.polaris.supply/llms.txt > Use this file to discover all available pages before exploring further. # Perpetual Tickers > Query partial venue-published prices, open interest, premium, and funding state for perpetual markets. 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` | | TypeScript | `perpetualTickers(options)` | `Promise` | The Rust blocking client exposes the same `perpetual_tickers(HistoricalQuery)` method and returns a `HistoricalIterator`. ### Python signature ```python theme={null} 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 ```python Python theme={null} 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))) ``` ```rust Rust theme={null} use futures_util::StreamExt; use polaris_data::{HistoricalQuery, PolarisClient}; #[tokio::main] async fn main() -> Result<(), Box> { 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(()) } ``` ```typescript TypeScript theme={null} 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 ```json theme={null} { "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 ```json theme={null} { "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](/concepts/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: ```python theme={null} 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. ## Related documentation * [Perpetuals](/guides/perpetuals) for end-to-end perpetual-market workflows * [Funding rates](/schemas/funding-rates) for the focused funding point series * [Mark prices](/schemas/mark-prices) for the focused mark-price point series * [Events](/schemas/events) for mixed normalized event streams * [Snapshots](/reference/snapshots) for snapshot-first historical reads