> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# Python SDK

> The official synchronous Python client and CLI for the normalized Predictefy API.

The `predictefy` package is the official Python 3.10+ client. It uses one runtime
dependency (`httpx`) and exposes the same normalized data, history, cross-venue, and
Trader Intelligence method family as the hosted API. Catalog and order-book reads cover
all 17 venues, including PredictStreet; Trader Intelligence is served on a narrower native-venue
set. `pascal`, `xo`, and `pred` are **not** data-only venues — each has an execution lane, in its
own state — and each one **does** carry Trader Intelligence: all three serve wallet-attributed
trades and appear in the scored-trade/smart-money feed, while holders, leaderboards, and wallet
profiles stay unsupported. Actual verbs remain capability-qualified by venue.


:::note[Beta release]
Published on PyPI as **`1.0.0b1`**. Pin an exact version while the beta line moves.
:::

## Quickstart

```bash
pip install predictefy
```

```python
from predictefy import Predictefy

client = Predictefy(api_key="pk_...")

markets = client.polymarket.fetch_markets({"limit": 5, "query": "fed"})
clusters = client.fetch_clusters({"limit": 20})
smart_money = client.fetch_smart_money({"venue": "hyperliquid", "limit": 20})
```

Change the venue client without changing the normalized method shape:

```python
client.kalshi.fetch_order_book("KXFED-26MAR-T4.00")
client.exchange("hyperliquid").fetch_trades("BTC-100K")
client.router.fetch_markets({"query": "election", "status": "active"})
client.polymarket.fetch_ohlcv(
    {"outcomeId": "123", "resolution": "1h", "limit": 500}
)
```

List methods return a `PageList`: an ordinary list with `.page`, `.meta`, and
`.next_cursor`. `iterate_markets` follows snapshot-safe cursors for you.

## Trader Intelligence

Trader support is capability-qualified by venue:

```python
trades = client.polymarket.fetch_trader_trades("market-id", {"limit": 50})
holders = client.polymarket.fetch_holders("market-id", {"limit": 50})
leaders = client.hyperliquid.fetch_leaderboard({"by": "score", "limit": 50})
profile = client.hyperliquid.fetch_wallet_profile("0x...")
```

An unsupported upstream capability returns `NOT_SUPPORTED`; the client does not
fabricate trader identity or venue data.

## CLI

The PyPI package installs a `predictefy` console script:

```bash
export PREDICTEFY_API_KEY=pk_...

predictefy markets polymarket --limit 10 --q fed
predictefy discrepancies --limit 20 --live
predictefy clusters --limit 20
```

Add `--json` for raw JSON. The full verb list is `markets <venue>`, `market <venue> <id>`,
`discrepancies`, `clusters`, and `account <resource> <venue> [account-id]`.

:::caution[The name `predictefy` is shared with the Node CLI]
The npm package `@predictefy/cli` installs a binary with the **same name** and a
**different command shape** — `predictefy markets search <query>`, not
`predictefy markets <venue>`. If both are installed, whichever comes first on `PATH`
wins. Run the Python one unambiguously as `python -m predictefy.cli …`.
:::

Public execution and client-side signing support is capability-qualified separately; do not
infer execution support from data coverage.