Python Client

The probalytics Python client is a convenience layer over the ClickHouse database. It handles the connection, builds queries for you, and returns results as Polars or pandas dataframes — or as typed Python models.

The client connects to ClickHouse using the same credentials as the SQL Guide. Create ClickHouse credentials in app.probalytics.io → ClickHouse Credentials.

Installation

pip install probalytics

Requires Python 3.11+. Polars is included by default. For pandas support:

pip install "probalytics[pandas]"

Connecting

From credentials
From environment
Context manager

from probalytics import ProbalyticsClient

client = ProbalyticsClient.from_clickhouse(
    host="clickhouse.probalytics.io",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)

Advanced options:

client = ProbalyticsClient.from_clickhouse(
    host="clickhouse.probalytics.io",
    port=9440,
    database="probalytics",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
    secure=True,
    frame="polars",  # default dataframe backend: "polars" or "pandas"
)

Set these environment variables:

export PROBALYTICS_CLICKHOUSE_HOST="clickhouse.probalytics.io"
export PROBALYTICS_CLICKHOUSE_USERNAME="YOUR_USERNAME"
export PROBALYTICS_CLICKHOUSE_PASSWORD="YOUR_PASSWORD"
export PROBALYTICS_FRAME="polars"  # optional

Then:

from probalytics import ProbalyticsClient

client = ProbalyticsClient.from_env()

The client can be used as a context manager to close the connection automatically:

from probalytics import ProbalyticsClient

with ProbalyticsClient.from_env() as client:
    markets = client.markets(platform="POLYMARKET", status="ACTIVE")

Markets

Query market metadata as typed models or as a dataframe.

# Typed models
markets = client.markets(
    market_platform_id="0xmarket",
    platform="POLYMARKET",
    status="ACTIVE",
    limit=100,
)

market = markets[0]
print(market.title, market.platform, market.platform_id)

# As a dataframe
markets_df = client.markets_frame(
    platform="KALSHI",
    status="ACTIVE",
    frame="polars",
)

Any filter accepts a single value or a list:

markets = client.markets(
    market_platform_id=["0xmarket", "KXBTC-26JUN-T50000"],
    platform=["POLYMARKET", "KALSHI"],
    status=["ACTIVE", "PAUSED"],
)

Fills

Fetch trade fills. Scope them to a market object, a market ID, or a platform-native ID:

fills = client.fills(
    market=market,
    start_time="2026-03-15T00:00:00Z",
    end_time="2026-03-16T00:00:00Z",
)

# Equivalent ways to scope:
fills = market.fills()
fills = client.fills(market_id=market.id)
fills = client.fills(market_platform_id=market.platform_id, platform=market.platform)

Filter by participant, side, and platform:

fills = client.fills(
    platform=["POLYMARKET", "KALSHI"],
    taker_side=["BUY", "SELL"],
    trader_id="0x1234...",
    start_time="2026-03-15T00:00:00Z",
)

Return typed models instead of a dataframe with fills_models:

fill_models = client.fills_models(market=market, start_time="2026-03-15T00:00:00Z")
fill_models = market.fills_models(start_time="2026-03-15T00:00:00Z")

Interpret financial fields using the linked market’s market_type. normalized_price is not a probability for perpetual products, cash-flow fields are not currently signed by trade direction, and fee = 0 can mean fee data was unavailable.

Orderbook snapshots

Full bid/ask depth per outcome, captured when the book changes. Requires an Orderbook or Custom ClickHouse tier.

book = client.orderbook_snapshots(
    market=market,
    start_time="2026-03-15T00:00:00Z",
    end_time="2026-03-15T00:01:00Z",
    state="VERIFIED",
)

# Or from the market object:
book = market.orderbook_snapshots(
    start_time="2026-03-15T00:00:00Z",
    end_time="2026-03-15T00:01:00Z",
    state="VERIFIED",
)

Each row is a complete replacement book for one outcome, not a level delta. Snapshot rows also expose indexed_at, hash, state, continuity, and path_index.

Order rows within one outcome by timestamp, path_index, then indexed_at.
Keep INTERMEDIATE rows to see every retained book state; filter to VERIFIED for orderbooks reconstructed without gaps.
A RESET row is a fresh starting point. Do not calculate changes from the preceding row or forward-fill across it.
Do not deduplicate different states by timestamp alone.

See Orderbook Snapshots for field semantics and venue-specific reconstruction details.

Choosing Polars or pandas

Methods return Polars by default. Set the backend globally when connecting, or override per call:

# Global: every call returns pandas
client = ProbalyticsClient.from_clickhouse(..., frame="pandas")

# Per call
fills_pd = client.fills(market=market, frame="pandas")

Valid values are "polars" and "pandas".

Custom SQL

Run arbitrary parameterized queries and get a dataframe back:

df = client.query(
    """
    SELECT platform, count() AS fills
    FROM fills
    WHERE timestamp >= %(start_time)s
    GROUP BY platform
    ORDER BY fills DESC
    """,
    parameters={"start_time": "2026-03-15T00:00:00Z"},
)

Always pass values via parameters rather than string-formatting them into the query. See the SQL Guide for table schemas and query examples.

Supported filters

Method	Filters
`markets` / `markets_frame`	`start_time`, `end_time`, `status`, `platform`, `market_id`, `market_platform_id`, `limit`, `max_rows`
`fills` / `fills_models`	`start_time`, `end_time`, `platform`, `market`, `market_id`, `market_platform_id`, `taker_side`, `trader_id`, `limit`, `max_rows`
`orderbook_snapshots`	`start_time`, `end_time`, `platform`, `market`, `market_id`, `market_platform_id`, `state`, `continuity`, `limit`

Every filter accepts a single value or a list of values.

Resources

Source & README

Package source and usage guide (Apache-2.0)

SQL Guide

Table schemas and query examples

Getting Started

Datasets

Access Methods

REST API

Reference

Support

Installation

Connecting

Markets

Fills

Orderbook snapshots

Choosing Polars or pandas

Custom SQL

Supported filters

Resources

Source & README

SQL Guide

​Installation

​Connecting

​Markets

​Fills

​Orderbook snapshots

​Choosing Polars or pandas

​Custom SQL

​Supported filters

​Resources

Source & README

SQL Guide

Installation

Connecting

Markets

Fills

Orderbook snapshots

Choosing Polars or pandas

Custom SQL

Supported filters

Resources