polyterm 0.6.2
A terminal-based monitoring app for PolyMarket shifts
Requires Python: >=3.8

# PolyTerm

A powerful, terminal-based monitoring and analytics tool for PolyMarket prediction markets. Track market shifts, whale activity, insider patterns, arbitrage opportunities, and signal-based predictions—all from your command line.

*a [nytemode](https://nytemode.com) project*

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/polyterm.svg)](https://pypi.org/project/polyterm/)

---

## Quick Start

### Option 1: Install from PyPI (Recommended)
```bash
pipx install polyterm
```

### Option 2: One-Command Install
```bash
curl -sSL https://raw.githubusercontent.com/NYTEMODEONLY/polyterm/main/install.sh | bash
```

### Option 3: Manual Install
```bash
git clone https://github.com/NYTEMODEONLY/polyterm.git
cd polyterm
pip install -e .
```

**Launch PolyTerm:**
```bash
polyterm
```

---

## Features Overview

### Core Features
| Feature | Command | Description |
|---------|---------|-------------|
| Market Monitoring | `polyterm monitor` | Real-time market tracking with live updates |
| Live Monitor | `polyterm live-monitor` | Dedicated terminal window for focused monitoring |
| Whale Activity | `polyterm whales` | Volume-based whale detection |
| Watch Markets | `polyterm watch` | Track specific markets with alerts |
| Export Data | `polyterm export` | Export to JSON/CSV |
| Historical Replay | `polyterm replay` | Replay market history |

### Premium Features
| Feature | Command | Description |
|---------|---------|-------------|
| Arbitrage Scanner | `polyterm arbitrage` | Find cross-market profit opportunities |
| Signal-based Predictions | `polyterm predict` | Multi-factor market predictions using live data |
| Order Book Analysis | `polyterm orderbook` | Depth charts, slippage, icebergs |
| Wallet Tracking | `polyterm wallets` | Smart money & whale wallet analysis |
| Alert Management | `polyterm alerts` | Multi-channel notification system |
| Risk Assessment | `polyterm risk` | Market risk scoring (A-F grades) |
| Copy Trading | `polyterm follow` | Follow successful wallets |

### Tools & Calculators
| Feature | Command | Description |
|---------|---------|-------------|
| Dashboard | `polyterm dashboard` | Quick overview of activity |
| Simulate P&L | `polyterm simulate -i` | Interactive P&L calculator |
| Parlay Calculator | `polyterm parlay -i` | Combine multiple bets |
| Position Size | `polyterm size -i` | Kelly Criterion bet sizing |
| Fee Calculator | `polyterm fees -i` | Calculate fees and slippage |
| Price Alerts | `polyterm pricealert -i` | Set target price notifications |

### Research & Analysis
| Feature | Command | Description |
|---------|---------|-------------|
| Market Search | `polyterm search` | Advanced filtering and search |
| Market Stats | `polyterm stats -m "market"` | Volatility, RSI, trends |
| Price Charts | `polyterm chart -m "market"` | ASCII price history |
| Compare Markets | `polyterm compare -i` | Side-by-side comparison |
| Calendar | `polyterm calendar` | Upcoming resolutions |
| Bookmarks | `polyterm bookmarks` | Save favorite markets |
| Recent Markets | `polyterm recent` | Recently viewed markets |

### Learning
| Feature | Command | Description |
|---------|---------|-------------|
| Tutorial | `polyterm tutorial` | Interactive beginner guide |
| Glossary | `polyterm glossary` | Prediction market terminology |

---

## CLI Commands

### Market Monitoring
```bash
# Monitor top markets
polyterm monitor --limit 20

# Monitor with JSON output (for scripting)
polyterm monitor --format json --limit 10 --once

# Sort by different criteria
polyterm monitor --sort volume
polyterm monitor --sort probability
polyterm monitor --sort recent
```

### Whale Activity
```bash
# Find high-volume markets
polyterm whales --hours 24 --min-amount 50000

# JSON output
polyterm whales --format json
```

### Arbitrage Scanner
```bash
# Scan for arbitrage opportunities
polyterm arbitrage --min-spread 0.025 --limit 10

# Include Kalshi cross-platform arbitrage
polyterm arbitrage --include-kalshi

# JSON output for automation
polyterm arbitrage --format json
```

**What it detects:**
- **Intra-market**: YES + NO prices < $1.00 (guaranteed profit)
- **Correlated markets**: Similar events with price discrepancies
- **Cross-platform**: Polymarket vs Kalshi price differences

### Signal-based Predictions
```bash
# Generate predictions for top markets
polyterm predict --limit 10 --horizon 24

# Predict specific market
polyterm predict --market <market_id>

# High-confidence predictions only
polyterm predict --min-confidence 0.7

# JSON output
polyterm predict --format json
```

**Prediction signals include:**
- Price momentum (trend analysis)
- Volume acceleration
- Whale behavior patterns
- Smart money positioning
- Technical indicators (RSI)
- Time to resolution

### Order Book Analysis
```bash
# Analyze order book
polyterm orderbook <market_token_id>

# Show ASCII depth chart
polyterm orderbook <market_token_id> --chart

# Calculate slippage for large order
polyterm orderbook <market_token_id> --slippage 10000 --side buy

# Full analysis with depth
polyterm orderbook <market_token_id> --depth 50 --chart
```

**What you get:**
- Best bid/ask and spread
- Bid/ask depth visualization
- Support/resistance levels
- Large order detection (icebergs)
- Slippage calculations
- Liquidity imbalance warnings

### Wallet Tracking
```bash
# View whale wallets (by volume)
polyterm wallets --type whales

# View smart money (>70% win rate)
polyterm wallets --type smart

# View suspicious wallets (high risk score)
polyterm wallets --type suspicious

# Analyze specific wallet
polyterm wallets --analyze <wallet_address>

# Track a wallet for alerts
polyterm wallets --track <wallet_address>

# JSON output
polyterm wallets --format json
```

### Alert Management
```bash
# View recent alerts
polyterm alerts --limit 20

# View only unread alerts
polyterm alerts --unread

# Filter by type
polyterm alerts --type whale
polyterm alerts --type insider
polyterm alerts --type arbitrage
polyterm alerts --type smart_money

# Acknowledge an alert
polyterm alerts --ack <alert_id>

# Test notification channels
polyterm alerts --test-telegram
polyterm alerts --test-discord
```

### Watch Specific Markets
```bash
# Watch with price threshold alerts
polyterm watch <market_id> --threshold 5

# Watch with custom interval
polyterm watch <market_id> --threshold 3 --interval 30
```

### Export Data
```bash
# Export to JSON
polyterm export --market <market_id> --format json --output data.json

# Export to CSV
polyterm export --market <market_id> --format csv --output data.csv
```

### Configuration
```bash
# List all settings
polyterm config --list

# Get specific setting
polyterm config --get alerts.probability_threshold

# Set a value
polyterm config --set alerts.probability_threshold 10.0
```

---

## Interactive TUI

Launch the interactive terminal interface:
```bash
polyterm
```

**First-time users** will be guided through an interactive tutorial covering prediction market basics, whale tracking, and arbitrage detection.

### Main Menu
```
1/m = monitor        5/a = analytics      9/arb = arbitrage
2/l = live monitor   6/p = portfolio     10/pred = predictions
3/w = whales         7/e = export        11/wal = wallets
4   = watch          8/s = settings      12/alert = alerts
                                         13/ob = orderbook
                                         14/risk = risk assessment
                                         15/follow = copy trading
                                         16/parlay = parlay calculator
                                         17/bm = bookmarks

d   = dashboard      t   = tutorial       g   = glossary
sim = simulate       ch  = chart          cmp = compare
sz  = size           rec = recent         pa  = pricealert
cal = calendar       fee = fees           st  = stats
sr  = search         pos = position       nt  = notes
pr  = presets        sent = sentiment     corr = correlate
ex  = exitplan       dp  = depth          tr  = trade
tl  = timeline       an  = analyze        jn  = journal
hot = hot markets    pnl = profit/loss    u   = quick update
h/? = help           q   = quit
```

### Navigation
- **Numbers**: Press `1-17` for numbered features
- **Shortcuts**: Use the letter/abbreviation shortcuts shown above
- **Help**: Press `h` or `?` for documentation
- **Tutorial**: Press `t` to launch the interactive tutorial
- **Glossary**: Press `g` for prediction market terminology
- **Quit**: Press `q` to exit

---

## Notification Setup

### Telegram Notifications
1. Create a bot via [@BotFather](https://t.me/botfather)
2. Get your chat ID via [@userinfobot](https://t.me/userinfobot)
3. Configure in PolyTerm:
```bash
polyterm config --set notification.telegram.enabled true
polyterm config --set notification.telegram.bot_token "YOUR_BOT_TOKEN"
polyterm config --set notification.telegram.chat_id "YOUR_CHAT_ID"
```

### Discord Notifications
1. Create a webhook in your Discord server (Server Settings → Integrations → Webhooks)
2. Configure in PolyTerm:
```bash
polyterm config --set notification.discord.enabled true
polyterm config --set notification.discord.webhook_url "YOUR_WEBHOOK_URL"
```

### Test Notifications
```bash
polyterm alerts --test-telegram
polyterm alerts --test-discord
```

---

## JSON Output Mode

All commands support `--format json` for scripting and automation:

```bash
# Get markets as JSON
polyterm monitor --format json --limit 5 --once | jq '.markets[] | select(.probability > 0.8)'

# Get arbitrage opportunities
polyterm arbitrage --format json | jq '.opportunities[] | select(.net_profit > 2)'

# Get predictions
polyterm predict --format json | jq '.predictions[] | select(.confidence > 0.7)'

# Get wallet data
polyterm wallets --format json --type smart | jq '.wallets[] | select(.win_rate > 0.8)'
```

---

## Database & Storage

PolyTerm stores data locally in SQLite:
- **Location**: `~/.polyterm/data.db`
- **Tables**: wallets, trades, alerts, market_snapshots, arbitrage_opportunities

### Data Tracked
- Wallet profiles with win rates and tags
- Trade history with maker/taker addresses
- Alert history with severity scoring
- Market snapshots for historical analysis
- Arbitrage opportunities log

---

## Configuration

Configuration stored in `~/.polyterm/config.toml`:

```toml
[api]
gamma_base_url = "https://gamma-api.polymarket.com"
clob_rest_endpoint = "https://clob.polymarket.com"
clob_endpoint = "wss://ws-live-data.polymarket.com"

[whale_tracking]
min_whale_trade = 10000
min_smart_money_win_rate = 0.70
min_smart_money_trades = 10

[arbitrage]
min_spread = 0.025
fee_rate = 0.02

[notification]
[notification.telegram]
enabled = false
bot_token = ""
chat_id = ""

[notification.discord]
enabled = false
webhook_url = ""

[notification.system]
enabled = true

[notification.sound]
enabled = true
critical_only = true

[alerts]
probability_threshold = 5.0
check_interval = 60

[display]
refresh_rate = 2
max_markets = 20
```

---

## Architecture

```
polyterm/
├── api/              # API clients
│   ├── gamma.py          # Gamma REST API
│   ├── clob.py           # CLOB REST + WebSocket
│   └── aggregator.py     # Multi-source aggregator
├── core/             # Business logic
│   ├── whale_tracker.py  # Whale & insider detection
│   ├── notifications.py  # Multi-channel alerts
│   ├── arbitrage.py      # Arbitrage scanner
│   ├── orderbook.py      # Order book analysis
│   ├── predictions.py    # Signal-based predictions
│   ├── correlation.py    # Market correlations
│   ├── historical.py     # Historical data API
│   └── portfolio.py      # Portfolio analytics
├── db/               # Database layer
│   ├── database.py       # SQLite manager
│   └── models.py         # Data models
├── cli/              # CLI commands
│   ├── main.py           # Entry point
│   └── commands/         # Individual commands
├── tui/              # Terminal UI
│   ├── controller.py     # Main loop
│   ├── menu.py           # Main menu
│   └── screens/          # TUI screens
└── utils/            # Utilities
    ├── config.py         # Configuration
    ├── json_output.py    # JSON formatting
    └── formatting.py     # Rich formatting
```

---

## Testing

```bash
# Full test suite
pytest

# Specific test categories
pytest tests/test_core/ -v          # Core logic tests
pytest tests/test_db/ -v            # Database tests
pytest tests/test_cli/ -v           # CLI tests
pytest tests/test_tui/ -v           # TUI tests
pytest tests/test_api/ -v           # API tests
pytest tests/test_live_data/ -v     # Live API tests (may fail due to data changes)
```

---

## Development

### Setup
```bash
git clone https://github.com/NYTEMODEONLY/polyterm.git
cd polyterm
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### Build & Publish
```bash
rm -rf dist/ build/ *.egg-info
python -m build
python -m twine upload dist/*
```

---

## Known Limitations

- **Portfolio tracking**: Limited due to Subgraph API deprecation (uses local trade history)
- **Individual trades**: WebSocket required for real-time individual trade data
- **Kalshi integration**: Requires Kalshi API key for cross-platform features

---

## Support

- **Issues**: [GitHub Issues](https://github.com/NYTEMODEONLY/polyterm/issues)
- **Documentation**: See this README and inline `--help`
- **Updates**: `polyterm update` or `pipx upgrade polyterm`

---

## License

MIT License - see [LICENSE](LICENSE) file.

---

**Built for the PolyMarket community**

*Your terminal window to prediction market alpha*

*a [nytemode](https://nytemode.com) project*