PolyTrader

A Python trading client for Polymarket — the world's largest prediction market.

Documentation

Features

• Order Management — Limit (GTC/GTD), market (FOK/FAK), and post-only orders with full cancel support
• Real-time WebSocket — Market data (order book, price changes, trades, BBO) and authenticated user events (order updates, trade confirmations)
• Binance Integration — aggTrade, kline, and depth streams for cross-market signals
• Typed Models — All data parsed into msgspec.Struct with Decimal prices and StrEnum statuses
• Position & Balance Tracking — Query positions, USDC balance, and conditional token balances
• On-chain Operations — Token and collateral approvals with optional builder/relayer support

Installation

pip install polytrader

Quick Start

from decimal import Decimal
from polytrader import PolyTrader, OrderSide, Coin, Timeframe

trader = PolyTrader(
    private_key="0x...",
    funder="0x...",
    signature_type=0,
)

# Get current Up/Down market
market = await trader.get_current_updown_market(Coin.BTC, Timeframe.M5)

# Place a limit order
result = trader.create_order(
    token_id=market.up_token_id,
    side=OrderSide.BUY,
    price=Decimal("0.50"),
    size=Decimal("10"),
)

# Cancel all orders
trader.cancel_all_orders()

# Real-time market data
await trader.market_ws.connect()
await trader.market_ws.subscribe([market.up_token_id], callback)
await trader.market_ws.run()

See the Getting Started guide for setup details and configuration options.

Documentation

Full documentation is available at omidroshani.github.io/polytrader.

• Getting Started — Installation, setup, and configuration
• Trading Client — Orders, positions, and balances
• WebSockets — Real-time market and user data
• Binance Integration — Binance streams
• API Reference — Full API documentation

Contributing

Contributions are welcome! To get started:

git clone https://github.com/omidroshani/polytrader.git
cd polytrader
uv sync --group dev --group docs

Run checks before submitting a PR:

make check    # mypy + ruff lint + ruff format
make test     # pytest
make security # bandit

License

This project is licensed under the MIT License.