Metadata-Version: 2.4
Name: polyalpha
Version: 2.3.0
Summary: Python SDK for Polymarket — market discovery, real-time price streaming, and paper trading
Author: Genius740Code
License: # MIT License
        
        Copyright (c) 2026 polyalpha contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/Genius740Code/polyalpha
Project-URL: Documentation, https://github.com/Genius740Code/polyalpha#readme
Project-URL: Repository, https://github.com/Genius740Code/polyalpha
Project-URL: Issues, https://github.com/Genius740Code/polyalpha/issues
Keywords: polymarket,prediction markets,trading,api,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: h2>=4.0.0
Requires-Dist: websocket-client>=1.0.0
Requires-Dist: websockets>=12.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: web3>=6.0.0
Requires-Dist: eth-account>=0.9.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: analysis
Requires-Dist: pandas>=1.5.0; extra == "analysis"
Requires-Dist: numpy>=1.23.0; extra == "analysis"
Requires-Dist: requests>=2.28.0; extra == "analysis"
Requires-Dist: pandas-ta>=0.3.14b0; extra == "analysis"
Provides-Extra: report
Requires-Dist: plotly>=5.18.0; extra == "report"
Requires-Dist: rich>=13.0.0; extra == "report"
Requires-Dist: kaleido>=0.2.1; extra == "report"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=20.0; extra == "telegram"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: polyalpha[analysis,dev,report,telegram]; extra == "all"

# polyalpha

Python SDK for [Polymarket](https://polymarket.com) — discover prediction markets, stream live prices, trade paper or real, run bots with composable strategy conditions, analyse with 20+ TA indicators and AI signals, track P&L with full reporting, and manage wallets.

```bash
git clone https://github.com/your-org/polyalpha.git
cd polyalpha
pip install -e .
```

---

## Quick start

```python
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.

```python
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.

```python
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`](./examples/stream.py).

---

## Paper trading

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

```python
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`](./examples/paper.py) and [`examples/advanced_orders.py`](./examples/advanced_orders.py).

### Paper config & presets

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

```python
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.

```python
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 |

```python
# 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

```python
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.binance.macd(12, 26, 9)     # MACD from Binance data
ctx.binance.price_change(3)     # BTC price change over 3 candles
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 `&`, `|`, `~`).

```python
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:

```python
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`](./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.

```python
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`](./examples/bot_hub.py) and [`docs/bot.md`](./docs/bot.md#bothub--multi-strategy-hub).

---

## Real trading

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

```python
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.

```python
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.

```python
# 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 20+ TA indicators.

```python
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:** `binance` (default), `chainlink`, `coingecko`, `custom`.

See [`examples/analysis.py`](./examples/analysis.py) and [`examples/price_change_signals.py`](./examples/price_change_signals.py).

---

## AI-powered signals

Analyse markets and generate trading signals via OpenRouter.

```python
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.

```python
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.

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

db = client.paper.database
db.get_statistics(start_date="2026-01-01", end_date="2026-07-22")
db.get_trades(market_slug="btc-updown-*")
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.

```python
from polyalpha import Sniper, SniperConfig

Sniper(SniperConfig(
    asset="BTC", timeframe="5m",
    balance=500.0, window_seconds=30,
    side="UP", order_size=25.0,
    auto_rollover=True,
)).run()
```

See [`examples/sniper.py`](./examples/sniper.py), [`examples/sniper_minimal.py`](./examples/sniper_minimal.py), and [`examples/sniper_ta.py`](./examples/sniper_ta.py).

---

## Tracker

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

```python
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).

```python
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`](./examples/multi_wallet_paper.py).

---

## Errors

Typed exceptions for every failure mode:

```python
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

```python
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`](./examples/stream.py) | Price streaming with all event hooks |
| [`examples/paper.py`](./examples/paper.py) | Paper trading — buy, sell, limit, summary |
| [`examples/advanced_orders.py`](./examples/advanced_orders.py) | Trailing stop, OCO, take-profit |
| [`examples/conditions.py`](./examples/conditions.py) | Composable trading conditions |
| [`examples/bot_simple.py`](./examples/bot_simple.py) | Bot with on_tick strategy |
| [`examples/bot_hub.py`](./examples/bot_hub.py) | BotHub — multi-strategy from one connection |
| [`examples/sniper.py`](./examples/sniper.py) | Sniper time-window bot |
| [`examples/sniper_minimal.py`](./examples/sniper_minimal.py) | Minimal Sniper bot (~10 lines) |
| [`examples/sniper_ta.py`](./examples/sniper_ta.py) | Sniper + technical analysis |
| [`examples/analysis.py`](./examples/analysis.py) | TA data feed, indicators, signals |
| [`examples/multi_wallet_paper.py`](./examples/multi_wallet_paper.py) | Multi-wallet paper trading |
| [`examples/risk_management.py`](./examples/risk_management.py) | Risk limits and controls |
| [`examples/pairsum_arb.py`](./examples/pairsum_arb.py) | Arbitrage example |
| [`examples/price_change_signals.py`](./examples/price_change_signals.py) | Price change detection signals |
| [`examples/chainlink_btc_scraper.py`](./examples/chainlink_btc_scraper.py) | Chainlink BTC data scraper |
| [`examples/m42_flb.py`](./examples/m42_flb.py) | M42 FLB strategy |
| [`examples/multi_arb_bot.py`](./examples/multi_arb_bot.py) | Multi-arbitrage bot |
| [`examples/telegram_notifications.py`](./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, 20+ 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
