first commit

docs/examples/sample_briefing.md

@@ -0,0 +1,84 @@
+# Daily Signal Briefing - 2026-04-15
+
+Generated at: 2026-04-16 10:00:03
+
+## Today's Overview
+
+- High-confidence information asymmetry signals: **3** (confidence >= 60%)
+- Abnormal price volatility events: **2**
+
+---
+
+## High-Confidence Information Asymmetry Signals
+
+### 1. Will MegaETH launch a token by June 30, 2026?
+
+| Metric | Value |
+|--------|-------|
+| Info Asymmetry | **72%** |
+| Direction | BUY Yes Token (Bullish) |
+| Entry Price | 0.4200 (Odds 2.4x) |
+| Trade Size | **$92,336** USDC |
+| Detected At | 2026-04-15 14:23:07 |
+
+**Analysis**: High-ranked trader (#47, PnL $284K) making concentrated bets. Unannounced smart contract deployed by MegaETH team 6 hours prior. KOL insider chatter on Twitter preceded the trade.
+
+**Insider Evidence**: New ERC-20 contract deployed by MegaETH deployer wallet, not yet publicly announced.
+
+### 2. US forces enter Iran by April 30
+
+| Metric | Value |
+|--------|-------|
+| Info Asymmetry | **65%** |
+| Direction | BUY Yes Token (Bullish) |
+| Entry Price | 0.3100 (Odds 3.2x) |
+| Trade Size | **$46,500** USDC |
+| Detected At | 2026-04-15 09:21:53 |
+
+**Analysis**: Top-50 trader with $500K+ PnL placing aggressive bets. Multiple high-ranked traders converging on the same direction. Trade occurred hours before Pentagon press briefing.
+
+### 3. Will the next Prime Minister of Hungary be Viktor Orban?
+
+| Metric | Value |
+|--------|-------|
+| Info Asymmetry | **61%** |
+| Direction | BUY No Token (Bearish) |
+| Entry Price | 0.2800 (Odds 3.6x) |
+| Trade Size | **$65,699** USDC |
+| Detected At | 2026-04-15 16:31:22 |
+
+**Analysis**: Verified trader with strong European politics track record betting against Orban. Telegram channels discussing potential coalition shift not yet covered by mainstream media.
+
+---
+
+## Abnormal Price Volatility
+
+| Market | Direction | Change | Start Price | End Price | Detected At |
+|--------|-----------|--------|-------------|-----------|-------------|
+| EdgeX FDV above 500M one day... | Up | 35.2% | 22.00% | 57.20% | 2026-04-15 03:41 |
+| Iran leadership change by Dec... | Up | 22.8% | 31.00% | 53.80% | 2026-04-15 11:15 |
+
+---
+
+## Signal History
+
+| Metric | Value |
+|--------|-------|
+| Total Signals | 847 |
+| Resolved | 312 |
+| Correct | 198 |
+| Win Rate | **63.5%** |
+| Avg ROI | **+28.3%** |
+| Theoretical Total PnL | **+42.71x** |
+
+### Performance by Confidence Tier
+
+| Confidence Range | Signals | Resolved | Win Rate | Avg ROI |
+|-----------------|---------|----------|----------|---------|
+| 0.8 - 1.0 | 23 | 15 | 80.0% | +52.1% |
+| 0.6 - 0.8 | 89 | 47 | 68.1% | +35.7% |
+| 0.4 - 0.6 | 284 | 132 | 59.1% | +18.4% |
+
+---
+
+*This briefing was automatically generated by Polymarket Whale Watcher*

docs/examples/sample_report.md

@@ -0,0 +1,139 @@
+
+======================================================================
+# Whale Trade Analysis Report
+======================================================================
+
+**Generated at**: 2026-05-04 16:00:00 UTC
+
+## Trade Summary
+
+| Field | Details |
+|-------|---------|
+| **Market** | US x Iran diplomatic meeting by June 30, 2026? |
+| **Trade Size** | $9,600.00 USDC |
+| **Direction** | BUY Yes Token (Bullish) |
+| **Trade Price** | 0.7142 (71.4%) |
+| **Current Odds** | Yes: 69.5% | No: 30.5% |
+| **Trade Time** | 2026-05-04 23:41:12 |
+| **Trader Rank** | #1733 (PnL: $84,695.33) |
+
+======================================================================
+
+## Full Analysis Report
+
+### Step 2: Trade Signal Analysis
+
+**Trader Profile Assessment:**
+- **Rank #1733** — mid-tier experienced trader, not top-tier elite
+- **PnL: $84,695** — solid positive track record across ~$4M lifetime volume
+- **Avg trade size: $10,018** — this $9,600 trade is perfectly in-line with his normal size, not an unusual outlier
+- **Large trade ratio: 66%** — consistent whale behavior, large trades are routine for this trader
+- **Domain expertise: Strong Iran/geopolitics focus** — recent trades include Iranian regime fall (April/June), US-Iran meetings (April/June), Russia-Ukraine ceasefire, Ukraine Donbas. This is clearly a geopolitics specialist with deep focus on Iran specifically.
+
+**Trade Timing:** The trade was made at 23:41 UTC on May 4, 2026. Given the active diplomatic situation, this is a routine positioning trade, not an oddly-timed pre-announcement bet.
+
+---
+
+### Step 3: Event-Related Position Analysis
+
+The whale has a **losing position** in the earlier "US x Iran diplomatic meeting by May 15, 2026?" market:
+- Holding Yes tokens @ avg 65.29%, now priced at **15.50%**
+- Cost basis: $8,534 | Current value: $2,026 | **PnL: -$6,508 (LOSS)**
+
+This is critical context:
+1. The trader **bet heavily on a May 15 meeting** and that bet is **nearly dead** (15.5% odds)
+2. The June 30 buy ($9,600) appears to be a **portfolio roll-forward** — doubling down on the same thesis with a later deadline to recoup losses
+3. This is NOT a fresh, confident insider bet — it's a **loss recovery / thesis extension trade**
+4. The pattern suggests the trader is sticking to a bullish Iran-diplomacy thesis despite being wrong on the nearer-term deadline
+
+---
+
+### Step 4: Market Long/Short Analysis
+
+**Bulls (Yes side):**
+- **anoin123** (Rank #2,682,942, PnL **-$5.54M**) — massive loser, leads the Yes side with $39K. This is a **red flag** — the biggest Yes holder is a chronic loser
+- **ArmageddonRewardsBilly** (Rank #278, PnL $525K) — elite trader, $11K on Yes. This is the strongest bull signal
+- **cezarn132** (the whale) — Rank #1733, $9.3K Yes
+
+**Bears (No side):**
+- **aaron107** (Rank #48,390) — low-ranked, leads No
+- **yungstalin** (Rank #1,969, PnL $73,759) — solid mid-tier trader on No side
+
+**Smart Money Consensus:** Mixed. One elite trader (Rank #278) is bullish, but the biggest Yes position belongs to a massive loser. The No side lacks elite concentration too. No clear smart money consensus signal in either direction.
+
+---
+
+### Step 5: Information Gap Analysis
+
+**Public Information Summary:**
+- There was already an indirect round of talks in Islamabad, Pakistan in late April 2026 (confirmed by Wikipedia)
+- US envoy Steve Witkoff stated Washington is "in conversation" with Iran
+- Iran's FM Araghchi has made public proposals for a 3-phase deal
+- Market odds for June 30 meeting are ~69.5% — already well-priced for the optimistic scenario
+- However, the **May 15 market is at just 15.5%**, showing markets believe a near-term meeting is unlikely
+- Twitter data shows @faststocknewss noting "POLYMARKET ODDS OF A US-IRAN DIPLOMATIC MEETING ARE FADING" — the June 30 market was previously at 80%+ and has dropped to 66-69%
+
+**Key Information Assessment:**
+- All available information about Iran-US diplomacy is extensively covered in public media
+- The market at 69.5% appears to **reasonably price** the known information
+- No evidence of non-public information advantage — this appears to be public-information-based analysis
+- The trade is consistent with this trader's established Iran geopolitics thesis
+
+---
+
+### Step 6: Historical Pattern
+
+This trader has a **clear and consistent pattern**:
+- Bought "Iranian regime fall by April 30" at 0.86 → **SOLD at 0.98** (big win)
+- Bought "Iranian regime fall by June 30" at 0.76 and 0.74 → Still holding
+- Bet on "US x Iran diplomatic meeting by April 25/May 15" → **LOSING** at 15.5%
+
+The pattern suggests this trader uses a "timeline ladder" approach — betting on Iran-related events across multiple deadlines. When early deadlines miss, they roll to later ones. This reduces the information asymmetry signal significantly.
+
+---
+
+## Step 7: Information Asymmetry Assessment
+
+```json
+{
+    "information_asymmetry_score": 0.32,
+    "trader_credibility": "MEDIUM",
+    "reasoning": "Trader cezarn132 (Rank #1733, PnL $84K) is a confirmed geopolitics specialist with deep Iran-focused trading history. However, several factors suppress the information asymmetry score: (1) The $9,600 trade is exactly in-line with this trader's average trade size ($10K), making it routine rather than an exceptional conviction bet. (2) The trader currently holds a heavily losing position in the nearer 'May 15' meeting market (down $6,508), and this June 30 buy appears to be a thesis roll-forward/loss recovery strategy rather than a fresh insider signal. (3) All supporting information (Islamabad talks, Witkoff statements, Iranian proposals) is extensively public and already priced into the ~69.5% market odds.",
+    "insider_evidence": "No insider evidence found. All information supporting the bullish Iran diplomacy view is widely reported in mainstream media. The trade is most consistent with a thesis-continuation/loss-recovery strategy following a losing May 15 position."
+}
+```
+
+---
+
+### Summary Table
+
+| Factor | Assessment | Signal Strength |
+|--------|-----------|-----------------|
+| Trader Rank/PnL | Rank #1733, $84K PnL | Moderate |
+| Trade Size vs. Normal | ~$9.6K vs. avg $10K | Routine — neutral |
+| Related Position | Heavy loser on May 15 meeting (-$6.5K) | Suppresses signal |
+| Domain Expertise | Iran geopolitics specialist | Supportive |
+| Public Info Coverage | Extensive public news on US-Iran talks | Reduces asymmetry |
+| Market Pricing | Already at 69.5% — well-priced | Reduces asymmetry |
+| Smart Money Bulls | Rank #278 also long | Modest support |
+| Biggest Yes Holder | Rank #2.6M, -$5.5M PnL | Negative signal |
+| **Overall** | **Likely thesis continuation, not insider signal** | **Low-Medium** |
+
+**Recommended Action: HOLD/PASS** — This trade reflects a geopolitics analyst rolling forward a losing thesis rather than a trader acting on non-public information.
+
+======================================================================
+## Information Asymmetry Assessment
+======================================================================
+
+| Field | Assessment |
+|-------|------------|
+| **Information Asymmetry** | Low Information Asymmetry (32%) |
+| **Trader Credibility** | Medium Credibility (#1733) |
+
+**Key Evidence**: No insider evidence found. All information supporting the bullish Iran diplomacy view is widely reported in mainstream media. The trade is most consistent with a thesis-continuation/loss-recovery strategy following a losing May 15 position.
+
+**Reasoning**: Trader cezarn132 (Rank #1733, PnL $84K) is a confirmed geopolitics specialist with deep Iran-focused trading history. However, several factors suppress the information asymmetry score: (1) routine trade size, (2) losing position on nearer deadline, (3) extensive public information coverage, (4) declining market odds, (5) mixed smart money picture, (6) large geopolitical market with many participants.
+
+======================================================================
+Disclaimer: This report is AI-generated for informational purposes only and does not constitute investment advice.
+======================================================================

docs/examples/sample_terminal.txt

@@ -0,0 +1,54 @@
+$ python -m src.main run
+
+╭──────────────────────────────────────────────────────────╮
+│              🐋 Polymarket Whale Watcher                 │
+│                                                          │
+│  Markets Monitored:  50                                  │
+│  Polling Interval:   15s                                 │
+│  Min Trade Size:     $1,000                              │
+│  Price Range:        0 - 0.7                             │
+╰──────────────────────────────────────────────────────────╯
+
+[14:22:41] 🔄 Refreshing trending markets... Found 50 active markets
+[14:22:43] 👀 Monitoring: Will MegaETH launch a token by June 30, 2026?
+[14:22:43] 👀 Monitoring: US forces enter Iran by April 30
+[14:22:43] 👀 Monitoring: Will the next Prime Minister of Hungary be Viktor Orban?
+           ... (47 more markets)
+
+[14:22:51] 🐋 WHALE DETECTED on "Will MegaETH launch a token by June 30, 2026?"
+           BUY Yes @ 0.4200 | $92,336 USDC | Wallet: 0x7a3b...f91e
+           Anomaly Score: 0.78/1.00
+
+[14:22:52] 🔍 Analyzing whale trade...
+           → Fetching trader ranking... Rank #47 (PnL: $284,521)
+           → Fetching trader history... 156 recent trades
+           → Fetching event positions... 3 related markets
+           → Fetching market top traders... 5 bulls, 5 bears
+
+[14:22:53] 🤖 LLM Analysis started (model: gemini-3-flash-preview)
+           → Tool call: search_web("MegaETH token launch date 2026")
+           → Tool call: search_twitter("MegaETH $METH token TGE")
+           → Tool call: get_protocol_tvl("megaeth")
+           → Tool call: get_contract_info("0x4f9b...2a1c")
+           → Tool call: search_telegram("MegaETH launch")
+
+[14:23:07] ✅ Analysis complete
+           Information Asymmetry Score: 0.72 (HIGH)
+           Recommendation: BUY Yes | Confidence: 0.75
+           Report saved: reports/20260415/20260415_142307_BUY_92336USD_MegaETH_token.md
+
+[14:23:07] 📧 Email alert sent (IAS >= 60%)
+
+[14:23:15] 🐋 WHALE DETECTED on "US forces enter Iran by April 30"
+           BUY Yes @ 0.3100 | $46,500 USDC | Wallet: 0x2c8e...a4d2
+           Anomaly Score: 0.71/1.00
+
+[14:23:16] 🔍 Analyzing whale trade...
+           ...
+
+[14:37:41] 🔄 Refreshing trending markets... Found 48 active markets (2 resolved)
+
+[15:00:00] 📊 Resolution check: 3 markets resolved since last check
+           → "EdgeX FDV above 400M" resolved YES — Signal was CORRECT (ROI: +142%)
+           → "Will Trump talk to Rutte" resolved NO — Signal was INCORRECT
+           → "Over 9M committed to P2P" resolved YES — Signal was CORRECT (ROI: +67%)