predxt

Read-only market-data ingestion for prediction market builders.

predxt streams websocket data and reads REST market-data snapshots from Polymarket, Kalshi, and Opinion. It is built for dashboards, recorders, research tools, monitoring agents, market scanners, and orderbook visualizations. It is not a trading, execution, account, or financial-advice library.

Install

pip install "predxt>=0.3.0"

For local development:

uv sync --group dev
uv run pytest -q -s

Your first orderbook

This walkthrough requires Python 3.12 or later and predxt 0.3.0 or later.

Start with a built-in synthetic example. It works from any directory, with no credentials, files to download, or network connection:

predxt demo

SYNTHETIC DEMO — no network requests
Market: Example market
Outcome: Yes
 BID PRICE         SIZE |  ASK PRICE         SIZE
    0.4200          100 |     0.4400           80
    0.4100           50 |     0.4500          120
Spread: 0.0200

Then find a real Polymarket market by name and choose its outcome:

predxt explore polymarket --query "bitcoin"

Choose a market number and an outcome number at the prompts. The CLI reads a REST snapshot, displays the top five levels on each side, and prints a ready-to-run WebSocket command for that outcome. Public Polymarket market data needs no API key. Each API request has a 10-second deadline; empty results and unavailable markets produce a clear message. The snapshot's fetch time is local receipt time.

See the first-run guide for scriptable selection, JSON output, and troubleshooting. Kalshi and Opinion remain available through the existing REST and WebSocket clients.

Venue matrix

API contract

Core imports:

from predxt import (
    OrderBookState,
    VenueMessage,
    typed_event_from_message,
)

Venue imports:

from predxt.polymarket import (
    PolymarketRestClient,
    PolymarketSubscriptionConfig,
    PolymarketWsClient,
)
from predxt.kalshi import (
    KalshiRestClient,
    KalshiWsClient,
    build_kalshi_auth_headers,
)
from predxt.opinion import (
    OpinionRestClient,
    OpinionSubscriptionConfig,
    OpinionWsClient,
)

Every client emits VenueMessage objects with:

• venue
• event_type
• market_id
• asset_id
• timestamp_ms
• received_at_ms
• raw_data

Use typed_event_from_message(message) when you want dataclass events such as OrderBookSnapshot, OrderBookDelta, TradeEvent, or PriceChangeEvent. Use OrderBookState when you need a small in-memory orderbook helper.

REST clients expose read-only market-data methods:

from predxt.polymarket import PolymarketRestClient

client = PolymarketRestClient()
markets = await client.search_markets("weather", limit=5)
book = await client.get_orderbook("CLOB_TOKEN_ID")
await client.close()

Connection managers own their background websocket reader. Use their public start() and stop() methods for lifecycle management; stop() also handles idle streams and is safe to call before start() or more than once. Consumers do not need to access private task attributes.

CLI

Built-in demo:

predxt demo --json

Parse a fixture from a repository checkout:

predxt parse-fixture --venue polymarket --jsonl tests/fixtures/polymarket_order_books.json

Live streams:

predxt stream polymarket --asset-id 1234567890 --limit 10 --jsonl
KALSHI_KEY_ID=... KALSHI_PRIVATE_KEY_PATH=... predxt stream kalshi --market MARKET-TICKER
OPINION_API_KEY=... predxt stream opinion --market-id 2764

Examples

This repository keeps minimal examples in examples/. Public showcase starters:

• hzprotocol/predxt-orderbook-tui
  • terminal orderbook monitor
• hzprotocol/predxt-web-dashboard
  • FastAPI + React dashboard
• hzprotocol/predxt-agent-market-monitor
  • read-only agent/MCP starter

What this is not

predxt does not place orders, derive trading credentials, manage positions, execute strategies, bypass venue restrictions, or provide financial advice. It is a read-only market-data SDK. Keep credentials in environment variables or a secret manager; never hard-code them in examples or agent prompts.

Documentation

• Docs site: https://hzprotocol.github.io/predxt
• AI context: llms.txt, llms-full.txt
• Codex skill: skills/predxt/SKILL.md

Development

uv sync --group dev
uv run ruff check .
uv run mypy
uv run pytest -q -s
uv build
uv run twine check dist/*

Release

Releases use SemVer and tags in the vX.Y.Z format. See docs/releasing.md.