> ## Documentation Index
> Fetch the complete documentation index at: https://docs.probalytics.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Client

> Query markets, fills, and orderbook snapshots from Python with typed models and dataframes

The [`probalytics`](https://github.com/Probalytics/probalytics-python) Python client is a convenience layer over the ClickHouse database. It handles the connection, builds queries for you, and returns results as [Polars](https://pola.rs) or [pandas](https://pandas.pydata.org) dataframes — or as typed Python models.

<Note>
  The client connects to ClickHouse using the same credentials as the [SQL Guide](/docs/sql-guide/overview). Create ClickHouse credentials in [app.probalytics.io](https://app.probalytics.io) → ClickHouse Credentials.
</Note>

## Installation

```bash theme={null}
pip install probalytics
```

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

```bash theme={null}
pip install "probalytics[pandas]"
```

## Connecting

<Tabs>
  <Tab title="From credentials">
    ```python theme={null}
    from probalytics import ProbalyticsClient

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

    Advanced options:

    ```python theme={null}
    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"
    )
    ```
  </Tab>

  <Tab title="From environment">
    Set these environment variables:

    ```bash theme={null}
    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:

    ```python theme={null}
    from probalytics import ProbalyticsClient

    client = ProbalyticsClient.from_env()
    ```
  </Tab>

  <Tab title="Context manager">
    The client can be used as a context manager to close the connection automatically:

    ```python theme={null}
    from probalytics import ProbalyticsClient

    with ProbalyticsClient.from_env() as client:
        markets = client.markets(platform="POLYMARKET", status="ACTIVE")
    ```
  </Tab>
</Tabs>

## Markets

Query market metadata as typed models or as a dataframe.

```python theme={null}
# 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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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`:

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
# 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:

```python theme={null}
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"},
)
```

<Warning>
  Always pass values via `parameters` rather than string-formatting them into the query. See the [SQL Guide](/docs/sql-guide/overview) for table schemas and query examples.
</Warning>

## 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`, `limit`                                        |

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

## Resources

<CardGroup cols={2}>
  <Card title="Source & README" icon="github" href="https://github.com/Probalytics/probalytics-python">
    GitHub repository (Apache-2.0)
  </Card>

  <Card title="SQL Guide" icon="database" href="/docs/sql-guide/overview">
    Table schemas and query examples
  </Card>
</CardGroup>