polyalpha

Python SDK for Polymarket — discover prediction markets, stream live prices, trade paper or real, run bots with composable strategy conditions, analyse with 19 TA indicators and AI signals, track P&L with full reporting, and manage wallets.

git clone https://github.com/Genius740Code/polyalpha.git
cd polyalpha
pip install -e .

Quick start

import polyalpha

client = polyalpha.Client()
market = client.markets.latest("BTC", "5m")

stream = client.stream(market)
@stream.on("price")
def on_price(up, down):
    print(f"UP={up:.4f}  DOWN={down:.4f}")
stream.start(background=True)

client.paper.buy(market, side="UP", amount=10.0)
client.paper.summary()

Market discovery

Find any Up/Down market by asset + timeframe, slug, keyword, or browse all active.

client.markets.latest("BTC", "5m")
client.markets.latest("ETH", "15m")
client.markets.latest("SOL", "1h")
client.markets.get("btc-updown-5m-1751234700")
client.markets.search("ETH 15m")
client.markets.available("5m")      # all active 5m markets

Assets: BTC, ETH, SOL, XRP, DOGE, HYPE, BNB
Timeframes: 5m, 15m, 1h, 4h, 24h

Price streaming

WebSocket stream with auto-reconnect, PING keepalive, and five event hooks.

stream = client.stream(market)

@stream.on("price")   def on_price(up, down): ...
@stream.on("book")    def on_book(data): ...
@stream.on("trade")   def on_trade(data): ...
@stream.on("close")   def on_close(): ...
@stream.on("error")   def on_error(exc): ...

stream.start()                    # blocking
stream.start(background=True)     # daemon thread
stream.stop()

# Latest prices without a handler
stream.up
stream.down

See examples/stream.py.

Paper trading

Simulate orders with configurable fees, slippage, execution delay, and risk limits. Attach a stream for live P&L.

client = polyalpha.Client(balance=500.0)

client.paper.buy(market, side="UP", amount=10.0)
client.paper.sell_position(market, side="UP", amount=5.0)
client.paper.limit(market, side="UP", price=0.92, amount=25.0)
client.paper.cancel(order.id)

client.paper.positions()       # open positions
client.paper.all_positions()   # all, incl. resolved
client.paper.balance
client.paper.summary()         # P&L table

# Advanced order types (stop_loss_pct / take_profit_pct as decimals)
client.paper.buy(market, side="UP", amount=10.0,
    stop_loss_pct=0.05,         # 5% stop-loss
    take_profit_pct=0.50)       # 50% take-profit
client.paper.buy_with_tp_sl(market, side="UP", amount=10.0,
    stop_loss=0.45,             # absolute stop-loss price
    take_profit=0.65)           # absolute take-profit price
client.paper.oco_order(market, side="UP", amount=10.0,
    stop_loss=0.40, take_profit=0.70)  # one-cancels-other

# Attach a stream for auto-fill + live P&L
client.paper.attach_stream(stream, market)

# Resolve after settlement
client.paper.resolve(market, outcome="UP")

See examples/paper.py and examples/advanced_orders.py.

Calculations library

Unified calculation functions for market data analysis across all data sources (Chainlink, Binance, Coinbase).

from polyalpha.calculations import MarketCalculations, VolumeCalculations

# Universal price calculations (all data sources)
MarketCalculations.change_pct(data, period=1)     # % change over N periods
MarketCalculations.change_abs(data, period=1)     # absolute price change
MarketCalculations.rate_of_change(data, period=1) # speed of change per second
MarketCalculations.trend(data, period=1)          # UP/DOWN/NEUTRAL
MarketCalculations.direction(data, period=1)       # "up"/"down"/"flat"
MarketCalculations.volatility(data, period=10)     # price volatility
MarketCalculations.high(data, period=10)          # highest price
MarketCalculations.low(data, period=10)           # lowest price
MarketCalculations.range(data, period=10)         # price range

# Volume calculations (Binance/Coinbase only)
VolumeCalculations.vol_ratio(data, period=10)      # current / avg volume
VolumeCalculations.volume_trend(data, period=5)    # INCREASING/DECREASING/STABLE
VolumeCalculations.volume_surge(data, multiplier=2.0) # detect volume spikes
VolumeCalculations.avg_volume(data, period=10)    # average volume
VolumeCalculations.volume_momentum(data, period=5) # volume % change
VolumeCalculations.relative_volume(data, percentile=0.75) # percentile-based

Data source accessors

Source-specific accessors that integrate calculations with live data:

from polyalpha.calculations import ChainlinkAccessor
from polyalpha.windows import TimeWindow

# Chainlink accessor (price calculations only)
window = TimeWindow(max_age=120)
cl_accessor = ChainlinkAccessor(window)
cl_accessor.update(67850.0)  # Update with Chainlink price
cl_accessor.change_pct(30)    # % change over 30 seconds
cl_accessor.trend(60)         # trend direction
cl_accessor.is_rising(30)     # convenience method
cl_accessor.is_falling(30)    # convenience method

Source availability:

Chainlink: Price calculations only (no volume data)
Binance: Price + volume calculations
Coinbase: Price + volume calculations (future)

See src/polyalpha/calculations/ for implementation details.

Paper config & presets

Tune realism: fee model, slippage, fill probability, execution delay, risk limits.

from polyalpha.trading.paper_config import get_paper_config_from_preset, list_presets

print(list_presets())
config = get_paper_config_from_preset("REALISTIC")    # 2s delay, polymarket fees, 85% fill prob
config = get_paper_config_from_preset("AGGRESSIVE")   # no delay, high fill prob
config = get_paper_config_from_preset("CONSERVATIVE") # polymarket fees, 1% slippage, 95% fill prob
config = get_paper_config_from_preset("TEST")         # zero fees, instant, 100% fill

client = polyalpha.Client(balance=500.0, paper_config=config)
# or load from .env:
client = polyalpha.Client(paper_config_from_env=True)

Built-in presets

Preset	Slippage	Delay	Fill prob	Risk
`CONSERVATIVE`	1%	500ms	95%	Low
`REALISTIC`	3%	2000ms	85%	Medium
`AGGRESSIVE`	5%	100ms	70%	High
`ZERO_FEE`	0%	0ms	100%	Medium
`HIGH_LATENCY`	8%	5000ms	60%	Medium
`LIQUIDITY_PROVIDER`	2%	1000ms	90%	Low
`SCALPER`	2%	50ms	98%	Low
`TEST`	0%	0ms	100%	None

Bots

Bot handles the full lifecycle: discover → stream → tick → resolve → rollover → repeat.

bot = polyalpha.Bot("BTC", "5m", balance=500, mode="simple")

@bot.on_tick
def strategy(ctx):
    if ctx.price.up > 0.9 and ctx.rsi > 50:
        ctx.buy("UP", 20)

bot.run()  # blocking, auto-rollover

Modes

Three execution templates via the mode parameter:

Mode	Fees	Delay	Slippage	Fill prob
`"simple"` (default)	Zero	Instant	0%	100%
`"realistic"`	Polymarket fees	2000ms	3%	85%
`"custom"`	Your `PaperConfig`	Your config	Your config	Your config

# Simple — zero fees, instant, 100% fill (default)
bot = polyalpha.Bot("BTC", "5m", balance=500)

# Realistic — polymarket fees, slippage, delay
bot = polyalpha.Bot("BTC", "5m", balance=500, mode="realistic")

# Custom — your own PaperConfig
from polyalpha.trading.paper_config import PaperConfig, get_paper_config_from_preset

bot = polyalpha.Bot("BTC", "5m", balance=500, mode="custom",
    paper_config=PaperConfig(fee_mode="custom", custom_fee_rate=0.015))

TickContext

ctx.price.up / ctx.price.down   # current prices
ctx.balance                     # paper balance
ctx.positions                   # open positions
ctx.pnl                         # realised P&L
ctx.rsi / ctx.sma_20 / ctx.ema_12   # indicators (requires pandas)
ctx.tick_count / ctx.trade_count
ctx.chainlink.last_price        # BTC spot from Chainlink oracle
ctx.cl.value                    # latest Chainlink price
ctx.cl.change_pct(30)           # % change over 30 seconds
ctx.cl.change_pct(60)           # % change over 60 seconds
ctx.cl.age_s                    # seconds since last CL update
ctx.cl.trend(60)               # trend direction (UP/DOWN/NEUTRAL)
ctx.cl.direction(30)           # simple direction ("up"/"down"/"flat")
ctx.cl.volatility(120)         # price volatility
ctx.binance.macd(12, 26, 9)     # MACD from Binance data
ctx.binance.price_change(3)     # BTC price change over 3 candles
ctx.binance.change_pct(3)       # % price change over 3 candles
ctx.binance.vol_ratio(10)       # current volume / avg of last 10 candles
ctx.binance.volume_trend(5)     # volume trend (increasing/decreasing/stable)
ctx.binance.volume_surge(2.0)    # detect volume spikes
ctx.buy("UP", 20)               # market buy
ctx.limit("UP", 0.92, 25)       # limit order
ctx.close_position("UP")        # close position

Composable conditions

Use declarative conditions with and_, or_, not_ (or &, |, ~).

from polyalpha.conditions import rsi_above, price_above, and_

bot.when(and_(rsi_above(50), price_above("up", 0.9))).buy("UP", 20)
bot.when(rsi_below(30) & price_below("down", 0.15)).buy("DOWN", 20)
bot.run()

Built-in conditions: rsi_above, rsi_below, price_above, price_below, price_change_pct_above, sma_above, sma_below, trending_up, trending_down, volatility_above, volume_above, min_tick_count, max_spend, stopped, macd_bullish_crossover, macd_bearish_crossover, macd_above_zero, macd_below_zero, price_change_above, price_change_below, price_up, price_down

Mixing data sources: Conditions like macd_bullish_crossover() read from Binance BTC data via ctx.binance, while price_above() reads Polymarket UP/DOWN prices. Both work together in the same declarative rule:

from polyalpha.conditions import and_, price_above, macd_bullish_crossover

bot.when(
    and_(price_above("UP", 0.90), macd_bullish_crossover())
).buy("UP", 20)
bot.run()

Chainlink BTC spot is also available at ctx.chainlink.last_price in on_tick strategies or via ctx.chainlink in BotHub strategies.

See examples/bot_simple.py.

BotHub — Multi-Strategy Hub

Run multiple strategies from a single data connection. One market discovery, one WebSocket stream — N isolated paper engines. Eliminates redundant rate-limited connections.

hub = polyalpha.BotHub("BTC", "5m", default_balance=500)

@hub.strategy("momentum")
def momentum(ctx):
    if ctx.price.up > 0.9 and ctx.rsi > 50:
        ctx.buy("UP", 20)

@hub.strategy("value", balance=1000)
def value(ctx):
    if ctx.price.down < 0.10:
        ctx.buy("DOWN", 10)

hub.run()

Each strategy gets its own balance, positions, and P&L. Error isolation — one crash doesn't stop the others.

Event hooks & timers: hub.on("tick"), hub.on("candle_open"), hub.every(30) for lifecycle callbacks.

Variants: Register strategies with params metadata and compare side-by-side via hub.compare_variants() (Rich table sorted by P&L, win rate, Sharpe, max drawdown).

Order book: ctx.orderbook.up.bids, ctx.orderbook.down.asks, ctx.orderbook.refresh() — auto-attached to the shared stream.

Scenario	Use
One strategy	`Bot`
20+ strategies, same asset/timeframe	`BotHub`
Different assets per strategy	`Bot.run_async()`

See examples/bot_hub.py and docs/bot.md.

Real trading

Trade live on Polymarket via CLOB with EIP-712 signing.

client = polyalpha.Client(
    private_key="0x...",
    rpc_url="https://polygon-rpc.com",
    polymarket_api_key="...",
)

client.real.buy(market, side="UP", amount=10.0)
client.real.cancel(order.id)
client.real.positions()
client.real.balance

Real trading presets: CONSERVATIVE, REALISTIC, AGGRESSIVE, MINIMAL, HIGH_FREQUENCY, POSITION_TRADER, HEDGING_ENABLED, TEST.

Real trading is available via client.real — see docs/trading.md for the full API.

Auto-redeem

Schedule automatic redemption of winning positions.

from polyalpha import AutoRedeemConfig

config = AutoRedeemConfig(time_interval="1d", min_value_usd=100.0)
client.paper.set_auto_redeem_config(config)
client.paper.auto_redeem.start_scheduler()

# Manual
client.paper.auto_redeem.redeem()
client.paper.auto_redeem.get_redeem_history()

Triggers: time interval, market count, value threshold. Safety: dry-run, min age, max value caps.

Auto-redeem is available via client.paper.auto_redeem — see docs/trading.md for usage.

Order book

REST snapshots + optional WebSocket deltas, in-memory O(1) manager, analytics, and backtestable strategies.

# REST
feed = client.orderbook(market)
feed.refresh()
feed.bids[:3]
feed.asks[:3]

# Attach stream for live updates
feed.attach_stream(client.stream(market))

# Analytics
from polyalpha.orderbook import estimate_fill, book_summary, cumulative_depth
estimate_fill(snapshot, side="UP", amount=100.0)

# Strategies + backtesting
from polyalpha.orderbook import MomentumStrategy, SpreadStrategy, BacktestEngine

Strategies: MomentumStrategy, SpreadStrategy (market making), ImbalanceStrategy.

See docs/orderbook.md for the full order book API.

Technical analysis

Multi-source data feed and 19 TA indicators.

from polyalpha.analysis import DataFeed, IndicatorCalculator, SignalGenerator

feed = DataFeed(DataFeedConfig(source="binance", timeframe="5m"))
data = feed.fetch("BTC")

ind = IndicatorCalculator(data)
ind.rsi(14)
ind.bollinger_bands(20, 2.0)
ind.macd(12, 26, 9)
ind.adx(14)
ind.atr(14)
ind.stochastic(14, 3, 3)
ind.obv()

sig = SignalGenerator(ind)
sig.rsi_above(50)
sig.price_above_sma(20)
sig.price_above_bb_upper()
sig.macd_bullish_crossover()
sig.summary()  # all signals at once

Data sources: scraping (default), binance, chainlink, custom, websocket.

Live Binance feeds (polyalpha.analysis): CVDTracker streams spot aggTrades for cumulative volume delta (cvd, z, velocity, …), and LiquidationTracker streams futures forceOrder events for one-sided liquidation clusters (cluster()). Both run their own connection and reconnect forever.

from polyalpha.analysis import CVDTracker, LiquidationTracker

cvd = CVDTracker(); cvd.start()
liq = LiquidationTracker(); liq.start()

cvd.z()                       # CVD z-score, or None
liq.cluster()                 # {"direction", "notional", "count"} or None

Shared Globals (polyalpha.Globals): one instance of every continuously-running feed, shared by all strategies so adding one costs zero extra connections. default_globals("BTC", cvd=True, liq=True) builds the feeds; .start() / .stop() manage them all. Per-market scope is MarketCtx / watch_market().

See examples/analysis.py and examples/price_change_signals.py.

AI-powered signals

Analyse markets and generate trading signals via OpenRouter.

client = polyalpha.Client(openrouter_api_key="sk-or-...")

analysis = client.ai.analyze_market(market_data)
analysis.sentiment    # "bullish" | "bearish" | "neutral"
analysis.confidence   # 0.0 – 1.0
analysis.reasoning    # markdown explanation

signal = client.ai.generate_trading_signal(market_data)
signal.action         # "BUY" | "SELL" | "HOLD"
signal.side           # "UP" | "DOWN" | None
signal.confidence     # 0.0 – 1.0

AI analysis is available via client.ai — see docs/ai.md for usage.

Reporting

Generate terminal summaries, interactive HTML dashboards, and PNG snapshots of paper-trading performance.

client.paper.report.show()                    # terminal (rich tables)
client.paper.report.html(open_browser=True)   # interactive HTML
client.paper.report.save_png("report.png")    # requires kaleido

30+ metrics: Sharpe, Sortino, Calmar, Omega, Kelly criterion, VaR, CVaR, profit factor, win rate, average win/loss, max drawdown, recovery factor.

12 charts: equity curve, underwater drawdown, P&L per trade, win/loss distribution, monthly returns, rolling Sharpe, correlation matrix, P&L hourly heatmap.

See docs/reporting.md for the full reporting API.

Database

SQLite-backed trade persistence with optional encryption.

client = polyalpha.Client(db_path="./trades.db")

db = client.paper.database
db.get_statistics()                                   # aggregate stats (no args)
db.load_trades(filters={"asset": "btc"})              # filtered trades
db.load_trades_by_market("btc-updown-5m-1751234700")  # trades for one market
db.export_json("trades.json")
db.export_csv("trades.csv")

See docs/database.md for the full database API.

Sniper bot

Time-window execution bot with configurable thresholds and auto-rollover. Supports advanced time windows: multiple disjoint periods, burst patterns, absolute time windows, conditional windows (indicator-based), and day/hour filtering.

from polyalpha import Sniper, SniperConfig, TimeWindow, ConditionalWindow, TimeFilter

# Simple time window (backward compatible)
Sniper(SniperConfig(
    asset="BTC", timeframe="5m",
    balance=500.0, window_seconds=30,
    side="UP", order_size=25.0,
    auto_rollover=True,
)).run()

# Advanced: Multiple time windows with conditions
Sniper(SniperConfig(
    asset="BTC", timeframe="5m",
    side="UP", entry_price=0.92, exit_price=0.88,
    time_windows=[
        TimeWindow(start_time="01:00", end_time="02:00"),
        TimeWindow(start_time="02:30", end_time="03:00"),
    ],
    conditional_windows=[
        ConditionalWindow(indicator="btc_change", operator="lt", threshold=2.0, periods=5),
    ],
    time_filter=TimeFilter(days=[0, 1, 2, 3, 4], hours=[9, 10, 11, 12, 13, 14, 15, 16, 17]),
    amount=20.0,
)).run()

timeframe is required (one of 5m, 15m, 1h, 4h, 24h — no silent 5m default). By default each bot buys only once per market (buy_once_per_market=True); set it to False on the config to allow multiple entries within the same market.

See examples/sniper.py, examples/sniper_minimal.py, examples/sniper_ta.py, and docs/bots.md.

Tracker

Real-time P&L tracking with JSON/CSV export.

from polyalpha import Tracker

tracker = Tracker(client.paper)
tracker.sync()
tracker.summary()
tracker.export_json("trades.json")
tracker.export_csv("trades.csv")

See docs/bot.md for Tracker usage.

Wallet management

Multi-wallet paper trading and secure wallet storage (AES-256, multi-sig, audit logging).

from polyalpha.trading.wallet import WalletManager, PaperWallet

manager = WalletManager()
manager.add_wallet(PaperWallet("trader-1", balance=1000.0))
client.paper.enable_multi_wallet(manager)

See examples/multi_wallet_paper.py.

Errors

Typed exceptions for every failure mode:

from polyalpha import (
    PolyalphaError,          # base
    MarketNotFound,          # slug not found
    MarketClosed,            # window closed
    StreamDisconnected,      # WS retry exhausted
    InsufficientBalance,     # balance too low
    OrderNotFound,           # unknown order
    OrderRejected,           # CLOB rejection
    OrderTimeout,            # not filled
    RiskLimitExceeded,       # risk check failed
    NetworkError,            # HTTP/WS failure
)

Logging

Variable	Default	Description
`POLYALPHA_LOG_LEVEL`	`WARNING`	DEBUG / INFO / WARNING / ERROR
`POLYALPHA_LOG_FILE`	—	File path (10 MB rotate)
`POLYALPHA_LOG_FORMAT`	`text`	`text` or `json`

Sensitive data (keys, addresses, tokens) is auto-redacted in both formats.

Configuration

client = polyalpha.Client(
    balance         = 100.0,        # paper USDC balance
    timeout         = 10,           # HTTP timeout (s)
    retries         = 3,            # HTTP retries
    log_level       = "WARNING",
    rate_limit      = None,         # requests/s
    paper_config    = None,         # PaperConfig instance
    paper_config_from_env = False,
    db_path         = None,         # SQLite path
    openrouter_api_key = None,      # AI features
    private_key     = None,         # real trading key
    rpc_url         = None,         # Polygon RPC
    polymarket_api_key = None,      # CLOB API key
    real_config     = None,         # RealTradingConfig
)

Examples index

| File | What it shows | |---|---|---| | examples/stream.py | Price streaming with all event hooks | | examples/paper.py | Paper trading — buy, sell, limit, summary | | examples/advanced_orders.py | Trailing stop, OCO, take-profit | | examples/conditions.py | Composable trading conditions | | examples/bot_simple.py | Bot with on_tick strategy | | examples/bot_hub.py | BotHub — multi-strategy from one connection | | examples/sniper.py | Sniper time-window bot | | examples/sniper_minimal.py | Minimal Sniper bot (~10 lines) | | examples/sniper_ta.py | Sniper + technical analysis | | examples/analysis.py | TA data feed, indicators, signals | | examples/multi_wallet_paper.py | Multi-wallet paper trading | | examples/risk_management.py | Risk limits and controls | | examples/pairsum_arb.py | Arbitrage example | | examples/price_change_signals.py | Price change detection signals | | examples/chainlink_btc_scraper.py | Chainlink BTC data scraper | | examples/multi_arb_bot.py | Multi-arbitrage bot | | examples/telegram_notifications.py | Telegram notification integration |

Project layout

src/polyalpha/
├── __init__.py          Public API surface
├── client.py            Client — single entry point
├── markets.py           MarketClient — discovery
├── stream.py            Stream — WebSocket price feed
├── bot.py               Bot — lifecycle runner
├── bot_hub.py           BotHub — multi-strategy hub
├── conditions.py        Composable strategy conditions
│
├── core/                Constants, errors, market models, env
├── trading/             PaperEngine, RealTradingEngine, auto-redeem, retry
├── orderbook/           REST + WS book, manager, strategies, backtest
├── analysis/            DataFeed, 19 indicators, 30+ signals
├── ai/                  OpenRouterClient, MarketAnalysis, TradingSignal
├── report/              ReportEngine, metrics (30+), charts (12), HTML
├── bots/                Sniper, Tracker
├── database/            SQLite, encryption, auth
├── wallet/              WalletSecurity, MultiSig, TransactionSigner, AuditLogger
└── utils/               Sensitive-data logging

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
examples		examples
polyalpha-0.2.28/src/polyalpha/orderbook		polyalpha-0.2.28/src/polyalpha/orderbook
src/polyalpha		src/polyalpha
tests		tests
.env.example		.env.example
.gitignore		.gitignore
License.md		License.md
README.md		README.md
TOD		TOD
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
strats.md		strats.md

Navigation Menu

Repository files navigation

polyalpha

Quick start

Market discovery

Price streaming

Paper trading

Calculations library

Data source accessors

Paper config & presets

Built-in presets

Bots

Modes

TickContext

Composable conditions

BotHub — Multi-Strategy Hub

Real trading

Auto-redeem

Order book

Technical analysis

AI-powered signals

Reporting

Database

Sniper bot

Tracker

Wallet management

Errors

Logging

Configuration

Examples index

Project layout

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

polyalpha

Quick start

Market discovery

Price streaming

Paper trading

Calculations library

Data source accessors

Paper config & presets

Built-in presets

Bots

Modes

TickContext

Composable conditions

BotHub — Multi-Strategy Hub

Real trading

Auto-redeem

Order book

Technical analysis

AI-powered signals

Reporting

Database

Sniper bot

Tracker

Wallet management

Errors

Logging

Configuration

Examples index

Project layout

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages