Skip to main content
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 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"
)

​
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")

​
Orderbook snapshots

Full bid/ask depth per outcome, captured when the book changes. Requires an Early Access tier. 
book = client.orderbook_snapshots(
    market=market,
    start_time="2026-03-15T00:00:00Z",
    end_time="2026-03-15T00:01:00Z",
)

# Or from the market object:
book = market.orderbook_snapshots(
    start_time="2026-03-15T00:00:00Z",
    end_time="2026-03-15T00:01:00Z",
)
Each snapshot includes the market identifiers, outcome, bids, asks, and timestamp.

​
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

MethodFilters
markets / markets_framestart_time, end_time, status, platform, market_id, market_platform_id, limit, max_rows
fills / fills_modelsstart_time, end_time, platform, market, market_id, market_platform_id, taker_side, trader_id, limit, max_rows
orderbook_snapshotsstart_time, end_time, platform, market, market_id, market_platform_id, limit
Every filter accepts a single value or a list of values.

​
Resources

Source & README

GitHub repository (Apache-2.0)

SQL Guide

Table schemas and query examples