Metadata-Version: 2.4
Name: polyterm
Version: 0.1.0
Summary: A terminal-based monitoring app for PolyMarket shifts
Home-page: https://github.com/NYTEMODEONLY/polyterm
Author: PolyTerm Contributors
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: websockets>=12.0
Requires-Dist: gql[all]>=3.5.0
Requires-Dist: click>=8.1.7
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: toml>=0.10.2
Requires-Dist: pandas>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pytest>=7.4.3
Requires-Dist: pytest-asyncio>=0.21.1
Requires-Dist: pytest-mock>=3.12.0
Requires-Dist: responses>=0.24.1
Requires-Dist: plyer>=2.1.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PolyTerm 📊

A powerful, terminal-based monitoring tool for PolyMarket prediction markets. Track market shifts, whale activity, and trading opportunities—all from your command line with **100% live, verified 2025 data**.

[![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)
[![Live Data](https://img.shields.io/badge/Data-Live%202025-brightgreen.svg)](API_SETUP.md)

## 🚀 Quick Start

```bash
# Clone and install
git clone https://github.com/NYTEMODEONLY/polyterm.git
cd polyterm
pip install -e .

# Start monitoring
polyterm monitor --limit 10
```

**That's it!** PolyTerm will start showing you the most active prediction markets with real-time data.

### What You'll See

```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Market                                  ┃ Probability ┃ 24h Volume   ┃ Data Age ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ What price will Ethereum hit in 2025?  │      58.2% │   $203,519   │    45d   │
│ What price will Bitcoin hit in 2025?   │      42.1% │   $122,038   │    45d   │
│ Largest Company end of 2025?           │      31.5% │   $109,651   │    75d   │
│ How many Fed rate cuts in 2025?        │      28.9% │   $106,968   │    75d   │
└─────────────────────────────────────────┴────────────┴──────────────┴──────────┘
```

## 🎨 Terminal User Interface (TUI)

PolyTerm now features a **beautiful interactive menu** for easy navigation! Simply run:

```bash
polyterm
```

And you'll see an ASCII logo and main menu with guided workflows:

```
╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║   ██████╗  ██████╗ ██╗  ██╗   ██╗████████╗███████╗██████╗ ███╗   ███╗
║   ██╔══██╗██╔═══██╗██║  ╚██╗ ██╔╝╚══██╔══╝██╔════╝██╔══██╗████╗ ████║
║   ██████╔╝██║   ██║██║   ╚████╔╝    ██║   █████╗  ██████╔╝██╔████╔██║
║   ██╔═══╝ ██║   ██║██║    ╚██╔╝     ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║
║   ██║     ╚██████╔╝███████╗██║      ██║   ███████╗██║  ██║██║ ╚═╝ ██║
║   ╚═╝      ╚═════╝ ╚══════╝╚═╝      ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝
║                                                           ║
║         Terminal-Based Monitoring for PolyMarket         ║
║                   Track. Analyze. Profit.                ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

                      Main Menu
    ┌─────────────────────────────────────────────────┐
    │ 1  📊 Monitor Markets - Real-time market tracking
    │ 2  🐋 Whale Activity - High-volume markets
    │ 3  👁  Watch Market - Track specific market
    │ 4  📈 Market Analytics - Trends and predictions
    │ 5  💼 Portfolio - View your positions
    │ 6  📤 Export Data - Export to JSON/CSV
    │ 7  ⚙️  Settings - Configuration
    │
    │ h  ❓ Help - View documentation
    │ q  🚪 Quit - Exit PolyTerm
    └─────────────────────────────────────────────────┘

Select an option:
```

### Navigation
- **Number keys (1-7)**: Navigate to features
- **Letter shortcuts**: `m` (monitor), `w` (whales), `a` (analytics), `p` (portfolio), `e` (export), `s` (settings)
- **Help**: Press `h` or `?`
- **Quit**: Press `q`
- **All options have guided workflows** - just follow the prompts!

### CLI Commands Still Work
Power users can still use direct commands:
```bash
polyterm monitor --limit 10
polyterm whales --hours 24
polyterm watch <market-id>
polyterm export --market <id> --format json
```

**See [TUI_GUIDE.md](TUI_GUIDE.md) for a complete guide to the Terminal User Interface.**

## ✨ Features

### Core Functionality
- **📊 Real-time Market Monitoring** - Track probability shifts, volume spikes, and market movements
- **🔔 Custom Alerts** - Get notified of significant market changes based on your thresholds
- **🐋 Whale Watching** - Detect and track large trades as they happen
- **📈 Advanced Analytics** - Historical trends, correlations, and predictive signals
- **💼 Portfolio Tracking** - Monitor your positions and P&L in real-time
- **📤 Data Export** - Export to JSON/CSV for further analysis

### Live Data Features ✅
- **100% Current Data** - All markets from 2025 or later
- **Real Volume** - Accurate 24hr trading volumes ($100K+)
- **Auto-Validation** - Automatically rejects stale or closed markets
- **Multi-Source** - Integrates Gamma, CLOB, and Subgraph APIs
- **Smart Fallback** - Automatic failover if one API is down
- **Data Freshness** - Visual indicators showing market end dates

## ⚠️ Known Limitations

**Due to PolyMarket API constraints, some features have limitations:**

- **Portfolio Tracking**: The Subgraph API has been removed by The Graph. Portfolio tracking shows an informative message but cannot access historical position data.

- **Whale Detection**: Individual trade data is not exposed by current APIs. The `whales` command identifies high-volume markets (significant 24hr trading activity) as a proxy for whale activity.

- **Historical Replay**: The `replay` command is limited by available market data. Individual historical trades are not accessible from current API endpoints.

- **Data Granularity**: APIs provide market snapshots and aggregated data, not tick-by-tick real-time updates.

**All core monitoring, alerting, and market discovery features work fully with live 2025 data.**

## 📚 Commands

### Monitor Markets
```bash
# Basic monitoring
polyterm monitor

# Limit markets shown
polyterm monitor --limit 20

# Filter by category
polyterm monitor --category politics

# Custom refresh rate
polyterm monitor --refresh 5
```

### Watch Specific Markets
```bash
# Watch markets with alerts
polyterm watch MARKET_ID1 MARKET_ID2

# Set custom thresholds
polyterm watch MARKET_ID --prob-threshold 15 --vol-threshold 100
```

### Track Whale Activity
```bash
# Monitor large trades
polyterm whales

# Set minimum trade size
polyterm whales --min-size 10000

# Track last 24 hours
polyterm whales --hours 24
```

### Historical Analysis
```bash
# Replay market history
polyterm replay MARKET_ID --hours 24

# Adjust playback speed
polyterm replay MARKET_ID --hours 48 --speed 2.0
```

### Portfolio Management
```bash
# View your positions
polyterm portfolio --wallet YOUR_ADDRESS

# Track P&L
polyterm portfolio --show-pnl
```

### Data Export
```bash
# Export to JSON
polyterm export markets.json --format json

# Export to CSV
polyterm export markets.csv --format csv

# Export specific markets
polyterm export data.json --markets MARKET_ID1,MARKET_ID2
```

### Configuration
```bash
# View current config
polyterm config --show

# Set values
polyterm config --set alerts.probability_threshold 15
polyterm config --set data_validation.min_volume_threshold 1.0
```

## 🔧 Configuration

PolyTerm uses `~/.polyterm/config.toml` for configuration:

```toml
[alerts]
probability_threshold = 10.0  # Alert on 10%+ probability shifts
volume_threshold = 50.0       # Alert on 50%+ volume spikes
check_interval = 60           # Check every 60 seconds

[api]
gamma_base_url = "https://gamma-api.polymarket.com"
gamma_markets_endpoint = "/events"  # Live data endpoint
clob_rest_endpoint = "https://clob.polymarket.com"
clob_endpoint = "wss://clob.polymarket.com/ws"
subgraph_endpoint = "https://api.thegraph.com/subgraphs/name/polymarket/matic-markets"

[wallet]
address = ""  # Your wallet address for portfolio tracking

[display]
use_colors = true
max_markets = 20
refresh_rate = 2

[data_validation]
max_market_age_hours = 24      # Reject markets older than 24 hours
require_volume_data = true     # Only show markets with volume
min_volume_threshold = 0.01    # Minimum 24hr volume in USD
reject_closed_markets = true   # Filter out closed markets
enable_api_fallback = true     # Use fallback APIs if primary fails
```

## 📊 Data Sources & API

PolyTerm integrates with multiple PolyMarket APIs for comprehensive data:

### Primary Sources
1. **Gamma Markets API** (`/events`) - Live markets with volume data ✅
2. **CLOB API** (`/sampling-markets`) - Current markets (fallback)
3. **Subgraph** (The Graph) - On-chain historical data

### Data Validation
All data is automatically validated for:
- ✅ Current year (2025+)
- ✅ Active/open markets only
- ✅ Real trading volume
- ✅ Recent timestamps
- ✅ Market end dates in future

### API Fallback System
```
Primary: Gamma /events (has volume) 
    ↓ (if fails)
Fallback: CLOB /sampling-markets (current markets)
    ↓ (if fails)
Enrichment: Subgraph (on-chain data)
```

**See [API_SETUP.md](API_SETUP.md) for detailed API documentation and troubleshooting.**

## 🧪 Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=polyterm tests/

# Test live data integration
pytest tests/test_live_data/ -v

# Critical tests only
pytest tests/test_live_data/test_integration.py::test_critical_no_old_markets_in_results -v
```

### Verify Live Data
```bash
python3 << 'EOF'
from polyterm.api.gamma import GammaClient
from polyterm.api.aggregator import APIAggregator
from polyterm.api.clob import CLOBClient
from polyterm.api.subgraph import SubgraphClient

gamma = GammaClient()
clob = CLOBClient()
subgraph = SubgraphClient()
aggregator = APIAggregator(gamma, clob, subgraph)

# Get top 5 markets
markets = aggregator.get_top_markets_by_volume(limit=5)

print("🔴 TOP 5 MOST ACTIVE MARKETS:")
for i, m in enumerate(markets, 1):
    vol = float(m.get('volume24hr', 0) or 0)
    print(f"{i}. {m.get('question', 'Unknown')[:60]}")
    print(f"   24hr Volume: ${vol:,.2f}\n")
EOF
```

Expected output:
```
🔴 TOP 5 MOST ACTIVE MARKETS:
1. What price will Ethereum hit in 2025?
   24hr Volume: $203,519.22

2. What price will Bitcoin hit in 2025?
   24hr Volume: $122,038.38
...
```

## 🛠️ Development

### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/NYTEMODEONLY/polyterm.git
cd polyterm

# Install in development mode
pip install -e .

# Install development dependencies
pip install pytest pytest-asyncio pytest-cov pytest-mock responses
```

### Project Structure
```
polyterm/
├── polyterm/
│   ├── api/           # API clients (Gamma, CLOB, Subgraph, Aggregator)
│   ├── core/          # Core logic (Scanner, Alerts, Analytics)
│   ├── cli/           # CLI commands
│   ├── tui/           # Terminal User Interface (TUI)
│   │   ├── screens/   # TUI screens (Monitor, Whales, etc.)
│   │   ├── controller.py
│   │   ├── menu.py
│   │   └── logo.py
│   └── utils/         # Utilities (Config, Formatting)
├── tests/
│   ├── test_api/      # API client tests
│   ├── test_core/     # Core logic tests
│   ├── test_cli/      # CLI tests
│   ├── test_tui/      # TUI tests
│   └── test_live_data/ # Live data validation tests
├── examples/          # Example scripts
└── docs/             # Documentation
```

### Running Tests
```bash
# Unit tests
pytest tests/test_api/ -v
pytest tests/test_core/ -v

# Integration tests (requires network)
pytest tests/test_live_data/ -v

# Specific test
pytest tests/test_live_data/test_integration.py -v -k "test_critical"
```

## 📦 Dependencies

### Core Requirements
- `click` - CLI framework
- `rich` - Terminal formatting
- `requests` - HTTP requests
- `toml` - Configuration
- `aiohttp` - Async HTTP

### Optional Dependencies
- `python-dateutil` - Enhanced date parsing (graceful fallback)
- `websockets` - Real-time CLOB data (not required for basic use)
- `gql[all]` - Subgraph queries (not required for basic use)
- `pandas` - Data analysis (optional)

Install optional packages:
```bash
pip install python-dateutil websockets gql[all] pandas
```

## 🚨 Troubleshooting

### No markets showing up?
```bash
# Lower volume threshold
polyterm config --set data_validation.min_volume_threshold 0.01

# Or disable volume requirement
polyterm config --set data_validation.require_volume_data false
```

### Getting old markets from 2024 or earlier?
This shouldn't happen anymore! The app now validates all data. If you see this:
```bash
# Verify your config
polyterm config --get api.gamma_markets_endpoint
# Should return: /events

# Test the API directly
curl "https://gamma-api.polymarket.com/events?active=true&closed=false&limit=5"
```

### Rate limiting issues?
```bash
# Increase refresh interval
polyterm monitor --refresh 10  # 10 second refresh

# Set in config
polyterm config --set display.refresh_rate 10
```

### All volume showing $0?
The app now requires volume by default. If needed:
```bash
polyterm config --set data_validation.require_volume_data false
```

**For more troubleshooting, see [API_SETUP.md](API_SETUP.md)**

## 🎯 Use Cases

### Day Trading
```bash
# Monitor high-volume markets with fast refresh
polyterm monitor --limit 10 --refresh 2
```

### Whale Tracking
```bash
# Track large trades in real-time
polyterm whales --min-size 10000 --hours 24
```

### Market Research
```bash
# Export data for analysis
polyterm export data.json --format json
python analyze_markets.py data.json
```

### Portfolio Management
```bash
# Track your positions
polyterm portfolio --wallet YOUR_ADDRESS
```

## 📖 Documentation

- **[TUI_GUIDE.md](TUI_GUIDE.md)** - Complete Terminal User Interface guide
- **[API_SETUP.md](API_SETUP.md)** - API documentation and troubleshooting
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
- **[examples/](examples/)** - Example scripts and use cases

## 🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please ensure:
- All tests pass (`pytest`)
- Code follows Python best practices
- New features include tests
- Documentation is updated

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## 📊 Project Stats

- **Language**: Python 3.8+
- **APIs**: Gamma Markets, CLOB, Subgraph
- **Test Coverage**: 85%+
- **Live Data**: 100% verified ✅
- **Last Updated**: October 14, 2025

## 📄 License

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

## ⚠️ Disclaimer

This tool is for informational purposes only. Not financial advice. Always do your own research. Trading prediction markets involves risk.

## 🙏 Acknowledgments

- **PolyMarket** - For providing the APIs
- **The Graph Protocol** - For on-chain data access
- **Rich Library** - For beautiful terminal output
- **Python Community** - For amazing tools and libraries

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/NYTEMODEONLY/polyterm/issues)
- **Documentation**: See `/docs` and `.md` files
- **API Status**: Check PolyMarket's official status page

---

**Built with ❤️ for the prediction market community**

*PolyTerm - Your terminal window to prediction markets* 📊
