README.md

# 🤖 Polymarket Ultra Bot

Un bot de trading ultra efficace pour [Polymarket](https://polymarket.com), basé sur la recherche académique la plus récente.

## 🎯 3 Stratégies Basées sur la Recherche

| # | Stratégie | Source | Performance |
|---|-----------|--------|-------------|
| 1 | **Arbitrage Intra-Marché** | [arxiv:2508.03474](https://arxiv.org/abs/2508.03474) | $40M profit réalisé sur Polymarket |
| 2 | **Value Bet + Kelly** | [arxiv:2604.14199](https://arxiv.org/abs/2604.14199) (PolyBench) | +17.6% CWR (MiMo-V2-Flash) |
| 3 | **Leader-Follower Sémantique** | [arxiv:2512.02436](https://arxiv.org/abs/2512.02436) | 47.5% ROI mensuel (Juin 2025) |

## 🏗️ Architecture

```
polymarket_bot/
├── __init__.py          # Package exports
├── config.py            # Configuration & constantes
├── data.py              # Gamma API, CLOB, WebSocket feeds
├── execution.py         # Moteur d'exécution & gestion des positions
├── strategies.py        # 3 stratégies de trading
├── bot.py               # Orchestrateur principal
└── monitor.py           # Monitoring, métriques, alertes

run_bot.py               # Script de lancement CLI
scan_markets.py          # Scanner de marchés (one-shot)
```

## 🚀 Quick Start

### Installation

```bash
pip install py-clob-client web3 requests websockets aiohttp numpy scikit-learn sentence-transformers
```

### Paper Trading (mode simulation)

```bash
# Lancer le bot en mode simulation
python run_bot.py

# Avec durée limitée (1 heure)
python run_bot.py --duration 3600

# Scanner les marchés sans trader
python scan_markets.py
```

### Configuration avancée

```bash
# Stratégie arbitrage seule avec haute fréquence
python run_bot.py --strategies arbitrage --poll-interval 1.0

# Toutes les stratégies avec capital élevé
python run_bot.py --capital 50000 --max-exposure 25000 --strategies arbitrage,value_bet,leader_follower

# Kelly agressif (demi-Kelly au lieu de quart)
python run_bot.py --kelly 0.5 --max-daily-loss 1000
```

### Mode Live ⚠️

```bash
# ATTENTION: utilise de vrais fonds sur Polygon
python run_bot.py --live --private-key 0xYOUR_POLYGON_PRIVATE_KEY
```

## 📊 Stratégies en Détail

### 1. Arbitrage Intra-Marché (Sans Risque)

**Principe:** Sur Polymarket, YES + NO pour une même condition = $1 garanti à la résolution. Si `best_ask(YES) + best_ask(NO) < $1`, acheter les deux = profit garanti.

**Paramètres clés:**
- `arb_min_spread`: Spread minimum (défaut: 2%)
- `arb_max_position_usd`: Max $500 par trade (limité par la liquidité)
- `arb_max_price_filter`: Ignore les tokens > $0.95

**Recherche:** $40M extraits sur Polymarket (Avr 2024–Avr 2025). Sports = plus fréquent, Politique = plus gros profits individuels.

### 2. Value Bet avec Kelly Sizing

**Principe:** Identifier les marchés où le prix ne reflète pas la vraie probabilité, en utilisant:
- Asymétrie du carnet d'ordres (bid/ask depth)
- Momentum des prix
- Signaux de volume

**Sizing:** Critère de Kelly (quart-Kelly par défaut = conservateur)

```python
kelly = (b * p_true - q) / b * 0.25  # Cap à 20% du bankroll
```

### 3. Leader-Follower Sémantique

**Principe:** Les marchés corrélés (ex: "Will Weinstein get 10-20 years?" vs "Will Weinstein get 20-30 years?") bougent avec un délai. Quand le "leader" bouge, le "follower" suit.

**Technologie:** Embeddings via `sentence-transformers/all-MiniLM-L6-v2` + similarité cosinus

## 🛡️ Gestion des Risques

| Paramètre | Défaut | Description |
|-----------|--------|-------------|
| `max_total_exposure_usd` | $5,000 | Exposition max totale |
| `max_single_market_exposure_pct` | 10% | Max par marché |
| `kelly_fraction` | 0.25 | Quart Kelly (conservateur) |
| `max_daily_loss_usd` | $500 | Stop-loss journalier |
| `max_concurrent_positions` | 20 | Max positions ouvertes |
| `min_market_volume` | $10K | Volume minimum des marchés |
| `excluded_tags` | Crypto | Catégories exclues (Crypto = catastrophique) |

**Alertes automatiques:**
- ⚠️ WARN: Perte journalière > 50% du max, drawdown > 10%
- ❌ ERROR: Perte journalière max atteinte → arrêt automatique

## 📈 Dashboard

Le bot affiche un dashboard en temps réel dans les logs :

```
╔══════════════════════════════════════════════════════════════╗
║                   POLYMARKET BOT DASHBOARD                   ║
╠══════════════════════════════════════════════════════════════╣
║ Uptime:        2.5h
║ Balance:       $10,450.00 (start: $10,000.00)
║ Total PnL:     $+450.00 (+4.50%)
║ PnL/Hour:      $+180.00
║ Max Drawdown:  1.20%
║ Trades:        47
║ Positions:     8
║ Alerts:        12 (⚠️1 ❌0)
╚══════════════════════════════════════════════════════════════╝
```

## 🔧 API Polymarket

Le bot utilise deux API :

| API | URL | Auth | Usage |
|-----|-----|------|-------|
| **Gamma** | `gamma-api.polymarket.com` | Publique | Marchés, prix, métadonnées |
| **CLOB** | `clob.polymarket.com` | L1+L2 | Carnets d'ordres, placement d'ordres |

Contrats on-chain (Polygon) :
- CTF Exchange: `0x4D97DCd97eC945f40cF65F87097ACe5EA0476045`
- NegRisk Exchange: `0xC5d563A36AE78145C45a50134d48A1D45eD1D83e`

## ⚖️ Disclaimer

Ce bot est fourni à des fins éducatives et de recherche. Le trading de marchés prédictifs comporte des risques financiers. Utilisez toujours le mode paper trading pour tester. Les performances passées ne garantissent pas les résultats futurs. Les résidents américains sont interdits d'accès à Polymarket.

## 📚 Références

- [Unravelling the Probabilistic Forest: Arbitrage in Prediction Markets](https://arxiv.org/abs/2508.03474) (2025)
- [PolyBench: A Benchmark for LLM-Based Prediction Market Trading](https://arxiv.org/abs/2604.14199) (2026)
- [Semantic Trading: Agentic AI for Clustering](https://arxiv.org/abs/2512.02436) (2025)
- [SoK: Decentralized Prediction Markets](https://arxiv.org/abs/2510.15612) (2025)