# predxt

Read-only Python SDK for prediction-market websocket ingestion and REST
market-data snapshots.

## Use predxt for

- live market-data recorders
- orderbook dashboards
- monitoring agents
- research tools
- read-only scanners

## Do not use predxt for

- placing orders
- account management
- trading advice
- credential generation
- bypassing venue restrictions

## Install

```bash
pip install "predxt>=0.3.0"
```

## Core APIs

```python
from predxt import OrderBookState, VenueMessage, typed_event_from_message
from predxt.polymarket import PolymarketRestClient, PolymarketWsClient
from predxt.kalshi import KalshiRestClient, KalshiWsClient
from predxt.opinion import OpinionRestClient, OpinionWsClient
```

`VenueMessage` fields: `venue`, `raw_data`, `timestamp_ms`, `event_type`,
`market_id`, `asset_id`, `received_at_ms`.

Typed event classes: `OrderBookSnapshot`, `OrderBookDelta`, `TradeEvent`,
`PriceChangeEvent`.

REST model classes: `MarketSummary`, `MarketDetail`, `OrderBookLevel`,
`VenueCredentialStatus`, `VenueApiError`.

REST clients expose `search_markets`, `get_market`, `get_orderbook`, and
`healthcheck`/`test_credentials`.

## CLI

First-run commands require predxt 0.3.0 or later:

```bash
predxt demo
predxt explore polymarket --query "bitcoin"
```

`demo` uses built-in synthetic data and no network. `explore` selects an open
market and outcome, reads one REST snapshot, and prints a WebSocket command.
Use `--market-id ID --outcome-index N --json` without an interactive terminal.
Each request has a deadline (`--timeout`, default 10 seconds). API failures never
silently fall back to synthetic output. See `docs/first-run.md`.

Polymarket `search_markets(query, limit=20, active_only=False)` uses Gamma
public-search for non-empty queries and lists markets for empty queries. It
returns up to limit unique market rows from the first page, retaining raw_data.

Existing commands (the fixture path requires a checkout):

```bash
predxt parse-fixture --venue polymarket --jsonl tests/fixtures/polymarket_order_books.json
predxt stream polymarket --asset-id 1234567890 --limit 10 --jsonl
```

## Agent guidance

- Preserve raw payload access.
- Keep generated apps read-only.
- Use env vars or secret managers for Kalshi and Opinion credentials.
- Use connection managers' public `start()` and `stop()` lifecycle; never
  inspect or cancel their private message tasks.
- Prefer `OrderBookState` for simple dashboards; do not claim execution-grade semantics.

More context: `llms-full.txt`, `docs/`, `skills/predxt/SKILL.md`.

## Websocket recovery

All three websocket clients recover from graceful stream endings with
backoff, updated connection health, and restored subscriptions. Opinion stops
its heartbeat during reconnect. Explicit `close()` interrupts retry waits;
cancelling or closing the message iterator releases the connection without
reconnecting. Call `connect()` explicitly to restart a closed client.
