Client¶

PythPandas — core HTTP client dataclass with DataFrame preprocessing.

The client targets the Pyth Pro Router (Pyth Lazer) REST API. Endpoint methods live in mixins; this class provides transport, authentication, DataFrame preprocessing, and shared infrastructure.

class pyth_pandas.client.PythPandas(base_url='https://pyth-lazer.dourolabs.app/v1/', timeout=30, api_key=None, use_tqdm=True, tqdm_description='', numeric_columns=('price', 'bestBidPrice', 'bestAskPrice', 'confidence', 'emaPrice', 'emaConfidence', 'fundingRate', 'exponent', 'publisherCount', 'fundingRateInterval', 'priceFeedId'), str_datetime_columns=(), int_datetime_columns=(), ms_int_datetime_columns=(), us_int_datetime_columns=('timestampUs', 'feedUpdateTimestamp', 'fundingTimestamp'), bool_columns=(), drop_columns=(), json_columns=())[source]¶

Bases: PricesMixin, GovernanceMixin

HTTP client for the Pyth Pro Router that returns pandas DataFrames.

Endpoint methods live in the mixins. This class provides the HTTP transport, bearer-token authentication, DataFrame preprocessing, and error-mapping infrastructure. Use as a context manager so the underlying connection pool is closed deterministically.

Parameters:

base_url (str) – Pyth Pro Router base URL. Pyth runs multiple endpoints (numbered 0/1/2) for redundancy; supply whichever you have been onboarded onto.
timeout (int) – Per-request timeout in seconds.
api_key (str | None) – Bearer access token. Falls back to PYTH_API_KEY from the environment (after any load_dotenv() call).
use_tqdm (bool) – Whether progress bars are enabled for any future paginated helpers.
tqdm_description (str)
numeric_columns (tuple)
str_datetime_columns (tuple)
int_datetime_columns (tuple)
ms_int_datetime_columns (tuple)
us_int_datetime_columns (tuple)
bool_columns (tuple)
drop_columns (tuple)
json_columns (tuple)

Example

>>> from pyth_pandas import PythPandas
>>> with PythPandas() as client:
...     df = client.fetch_latest_prices(
...         symbols=["Crypto.BTC/USD"],
...         properties=["price", "confidence", "exponent"],
...     )

API_VERSION: ClassVar[str] = '1.0.0'¶: Upstream API version this client targets (from the OpenAPI spec).

SUPPORTED_API_VERSIONS: ClassVar[tuple[str, ...]] = ('1.0.0',)¶: Upstream API versions this client is known to be compatible with.

api_key: str | None = None¶

base_url: str = 'https://pyth-lazer.dourolabs.app/v1/'¶

bool_columns: tuple = ()¶

close()[source]¶

Close the underlying HTTP connection pool.

Return type:: None

drop_columns: tuple = ()¶

int_datetime_columns: tuple = ()¶

json_columns: tuple = ()¶

ms_int_datetime_columns: tuple = ()¶

numeric_columns: tuple = ('price', 'bestBidPrice', 'bestAskPrice', 'confidence', 'emaPrice', 'emaConfidence', 'fundingRate', 'exponent', 'publisherCount', 'fundingRateInterval', 'priceFeedId')¶

preprocess_dataframe(df)[source]¶

Apply the client’s column-coercion config to df.

Parameters:: df (DataFrame)
Return type:: DataFrame

preprocess_dict(data)[source]¶

Apply the client’s column-coercion config to a single dict.

Parameters:: data (dict)
Return type:: dict

str_datetime_columns: tuple = ()¶

timeout: int = 30¶

tqdm_description: str = ''¶

us_int_datetime_columns: tuple = ('timestampUs', 'feedUpdateTimestamp', 'fundingTimestamp')¶

use_tqdm: bool = True¶

Price-fetching endpoints (/latest_price, /price, /reduce_price).

class pyth_pandas.mixins._prices.PricesMixin[source]¶

Bases: object

Price fetch endpoints that return one row per requested feed.

Each fetch_* method returns a DataFrame of parsed feeds. The accompanying on-chain payloads (EVM, Solana, …) and the update timestamp are attached as df.attrs. For the raw JsonUpdate response, use the matching *_raw variant.

fetch_latest_prices(*, properties, formats=None, channel='real_time', price_feed_ids=None, symbols=None, json_binary_encoding='hex')[source]¶

Fetch the latest update and return it as a parsed-feed DataFrame.

Same arguments as fetch_latest_prices_raw(). The returned DataFrame has one row per feed; the on-chain payloads and timestampUs are attached on df.attrs.

Parameters:

properties (list[str]) – Feed properties to include.
formats (list[str] | None) – On-chain payload formats. Defaults to [] (parsed only).
channel (str) – Update channel.
price_feed_ids (list[int] | None) – Numeric feed IDs (mutually exclusive with symbols).
symbols (list[str] | None) – Feed symbols (e.g. ["Crypto.BTC/USD"]).
json_binary_encoding (str | None) – "hex" or "base64".

Returns:

DataFrame conforming to ParsedFeedSchema.

Return type:

DataFrame[ParsedFeedSchema]

fetch_latest_prices_raw(*, properties, formats, channel='real_time', price_feed_ids=None, symbols=None, parsed=True, json_binary_encoding='hex')[source]¶

Fetch the latest available update for the requested feeds.

Parameters:

properties (list[str]) – Feed properties to include (price, confidence, exponent, …).
formats (list[str]) – On-chain payload formats to include (evm, solana, leEcdsa, leUnsigned).
channel (str) – Update channel — real_time or fixed_rate@*.
price_feed_ids (list[int] | None) – Numeric feed IDs. Mutually exclusive with symbols.
symbols (list[str] | None) – Feed symbols (e.g. ["Crypto.BTC/USD"]).
parsed (bool) – Include the parsed block in the response.
json_binary_encoding (str | None) – "hex" or "base64" for binary payloads.

Returns:

The raw JsonUpdate dict.

Raises:

PythAPIError – For any non-2xx response from the upstream API.

Return type:

JsonUpdate

fetch_prices(*, timestamp, properties, formats=None, channel='real_time', price_feed_ids=None, symbols=None, json_binary_encoding='hex')[source]¶

DataFrame variant of fetch_prices_raw().

Returns:

DataFrame conforming to ParsedFeedSchema.

Parameters:

timestamp (int | float | str | Timestamp)
properties (list[str])
formats (list[str] | None)
channel (str)
price_feed_ids (list[int] | None)
symbols (list[str] | None)
json_binary_encoding (str | None)

Return type:

DataFrame[ParsedFeedSchema]

fetch_prices_raw(*, timestamp, properties, formats, channel='real_time', price_feed_ids=None, symbols=None, parsed=True, json_binary_encoding='hex')[source]¶

Fetch updates issued at a specific point in time.

Parameters:

timestamp (int | float | str | Timestamp) – Microsecond-resolution Unix timestamp. Accepts an int (interpreted as µs if >= 10**14, else seconds), a pd.Timestamp, or an ISO-8601 string.
properties (list[str]) – Feed properties to include.
formats (list[str]) – On-chain payload formats.
channel (str) – Update channel.
price_feed_ids (list[int] | None) – Numeric feed IDs.
symbols (list[str] | None) – Feed symbols.
parsed (bool) – Include parsed block.
json_binary_encoding (str | None) – Binary payload encoding.

Returns:

The raw JsonUpdate dict.

Return type:

JsonUpdate

reduce_price(*, payload, price_feed_ids)[source]¶

DataFrame variant of reduce_price_raw().

Parameters:

payload (JsonUpdate)
price_feed_ids (list[int])

Return type:

DataFrame[ParsedFeedSchema]

reduce_price_raw(*, payload, price_feed_ids)[source]¶

Reduce an existing on-chain payload to only the listed feeds.

Parameters:

payload (JsonUpdate) – A JsonUpdate previously received from fetch_latest_prices_raw, fetch_prices_raw, or the WebSocket stream.
price_feed_ids (list[int]) – Subset of feed IDs to retain.

Returns:

A new JsonUpdate containing only the requested feeds.

Return type:

JsonUpdate

Governance endpoints (/guardian_set_upgrade).

class pyth_pandas.mixins._governance.GovernanceMixin[source]¶

Bases: object

Wormhole-related governance endpoints exposed by the Pyth Pro Router.

get_guardian_set_upgrade()[source]¶

Get the signed Wormhole guardian set upgrade VAA body, if any.

Active when both the current and next guardian sets are present in router state, indicating that a guardian set upgrade is in progress. Returns None when no upgrade is in progress.

Returns:: The signed upgrade dict, or None if not in progress.
Return type:: SignedGuardianSetUpgrade | None