Whale Watcher

NOTA: il repository sta diventando un bot di trading completo, un agente simile a openclaw con cui parlare su Telegram con il potere di schierare un team di agenti per fare ricerche prima di prendere una decisione.

Uno strumento CLI in Rust che monitora le grandi transazioni sui mercati di previsione Polymarket e Kalshi. Avvisi in tempo reale per attività di mercato significative con rilevamento anomalie integrato.

Repository: https://github.com/neur0map/polymaster

ESCLUSIONE DI RESPONSABILITÀ

Questo strumento è solo a scopo informativo e di ricerca. Utilizza questi dati esclusivamente per prendere decisioni informate e analisi di mercato.

Funzionalità

Monitoraggio Principale

• Monitoraggio in tempo reale delle transazioni Polymarket e Kalshi
• Kalshi WebSocket per rilevamento istantaneo delle transazioni (fallback HTTP polling)
• Filtro lato server di Polymarket — l'API pre-filtra le transazioni delle balene, nessuna larghezza di banda sprecata
• Soglia personalizzabile (predefinita $25.000) e intervallo di polling
• Avvisi audio con triplo beep per attori ripetuti
• Filtraggio per categoria di mercato (10 categorie, 35+ sottocategorie)
• Selezione piattaforma (solo Polymarket, solo Kalshi, o entrambi)

Intelligenza sulle Balene (Polymarket)

• Profili balena — valore del portafoglio, posizione in classifica, profitto, tasso di vincita, posizioni aperte
• Ricerca in classifica — verifica se un portafoglio è tra i primi 500 trader Polymarket
• Memoria portafoglio di 12 ore — rileva balene ricorrenti, doubling delle posizioni e flippate delle balene
• Maggiori detentori — mostra i primi 5 detentori e la loro concentrazione di quote per mercato
• Profili memorizzati nella cache per 30 minuti, classifica per 1 ora

Intelligence di Mercato

• Profondità del book ordini per entrambe le piattaforme (Polymarket CLOB + Kalshi orderbook)
• Contesto di mercato — quote YES/NO, spread, volume 24h, interesse aperto, variazione prezzo, liquidità
• Categorie Kalshi native dall'API (più accurate della corrispondenza per parole chiave)
• Tag Polymarket estratti dall'API Gamma
• Rilevamento anomalie per scommesse estreme, posizioni contrarie e grandi capitali

Monitoraggio Portafogli

• Avvisi elevati per attori ripetuti (2+ transazioni in 1 ora)
• Avvisi ad alta priorità per attori pesanti (5+ transazioni in 24 ore)
• Traccia volume e frequenza delle transazioni per portafoglio
• Rilevamento balene ricorrenti (raddoppio, flippatura posizioni)
• Memoria portafoglio persistente su SQLite tra riavvii

Integrazioni

• Notifiche webhook verso n8n, Zapier, Make, Discord o qualsiasi endpoint
• Payload JSON ricco con contesto di mercato, profilo balena, book ordini e maggiori detentori
• Server MCP di scoring per punteggio degli avvisi e filtraggio delle preferenze

Infrastruttura

• Database SQLite per cronologia avvisi e memoria portafoglio
• Conservazione dati configurabile (7, 30, 90 giorni o per sempre)
• Procedura guidata di configurazione in 6 passi
• Nessuna chiave API richiesta per funzionalità di base (tutti dati pubblici)
• Veloce ed efficiente, scritto in Rust

Avvio Rapido

git clone https://github.com/neur0map/polymaster.git
cd polymaster
cargo install --path .
wwatcher watch

Tutto qui. Nessuna chiave API necessaria — tutti i dati provengono da endpoint pubblici. Vedrai gli avvisi delle balene nel tuo terminale in pochi secondi.

Esegui wwatcher setup per configurare piattaforme, categorie, soglie, webhook e chiavi API opzionali.

Vedi QUICKSTART.md per istruzioni di configurazione dettagliate e integrazione webhook.

Installazione

Dal Codice Sorgente

git clone https://github.com/neur0map/polymaster.git
cd polymaster
cargo build --release

Il binario si troverà in target/release/wwatcher. Oppure installalo a livello di sistema:

cargo install --path .

Informazioni API

wwatcher utilizza 15 endpoint API su 3 API Polymarket, 1 API REST Kalshi e 1 WebSocket Kalshi. Vedi docs/API_REFERENCE.md per la documentazione completa degli endpoint.

Polymarket (3 API, nessuna autenticazione richiesta)

Kalshi (REST + WebSocket)

Tutti gli endpoint sono pubblici — nessuna chiave API necessaria. Per un accesso Kalshi migliorato, esegui wwatcher setup.

Integrazione Webhook

wwatcher invia payload JSON ricchi a qualsiasi URL webhook con: contesto di mercato, profilo balena, profondità book ordini, maggiori detentori e attività del portafoglio.

Vedi docs/WEBHOOK_REFERENCE.md per:

• Schema completo del payload con tutti i campi
• Template di messaggi per n8n Telegram/Discord
• Esempi di filtri (attori pesanti, prime 100 balene, solo uscite)
• Campi calcolati (punteggio qualità balena, squilibrio bid/ask)

Esempio di Avviso

Quando viene rilevata una transazione balena, vedrai un output arricchito:

[ALERT] TRANSAZIONE IMPORTANTE RILEVATA - Polymarket
======================================================================
Domanda:   Bitcoin raggiungerà 100k entro la fine del 2026?
Posizione: ACQUISTO quote 'Yes'
Previsione: Il mercato crede che 'Yes' abbia il 65.0% di probabilità

DETTAGLI TRANSAZIONE
Importo:     $50,000.00
Contratti:  76923.08 @ $0.6500 ciascuno
Azione:     ACQUISTO quote
Timestamp:  2026-02-13T18:00:00Z

[ATTIVITÀ PORTAFOGLIO]
Portafoglio:   0x742d35...f0bEb
Txns (1h):  2
Txns (24h): 5
Volume (24h): $380,000.00
Stato: ATTORE PESANTE (5+ transazioni in 24h)

[CONTESTO DI MERCATO]
Quote:          YES 65.0% | NO 35.0%
Spread:        $0.02 (stretto)
Volume 24h:    $450,000
Interesse Aperto: $2,100,000
Variazione 24h:      +3.2%
Liquidità:     $180,000
Tag:          crypto, bitcoin

[PROFILO BALENA]
Classifica:  #45 (TOP 50)
Profitto:       +$890,000
Portafoglio:    $2,340,000
Posizioni Aperte:     12
Tasso Vincita:     73.0%
Mercati:      195

[BOOK ORDINI]
Miglior Acquisto:   $0.6400  |  Miglior Vendita: $0.6600  |  Spread: $0.0200
Profondità Acquisti:  $45,000 (12 livelli)  |  Profondità Vendite: $38,000 (9 livelli)
Squilibrio:  54% acquisti / 46% vendite (moderata pressione acquisti)

[MAGGIORI DETENTORI]
  #1: 0x742d...bEb — 150,000 quote (12.0%)
  #2: 0x8a3f...1D  — 120,000 quote (9.6%)
  #3: 0x5b9c...aF  — 95,000 quote (7.6%)
  Top 3 controllano il 29.2% delle quote
======================================================================

Comandi

wwatcher watch                        # Avvia il monitoraggio (predefinita: soglia $25k, intervallo 5s)
wwatcher watch -t 50000               # Imposta soglia a $50.000
wwatcher watch -t 10000 -i 10         # Soglia $10k, intervallo polling 10s
wwatcher setup                        # Procedura guidata di configurazione in 6 passi
wwatcher status                       # Visualizza configurazione corrente e statistiche DB
wwatcher history                      # Visualizza ultimi 20 avvisi
wwatcher history -l 50 -p polymarket  # Ultimi 50 avvisi Polymarket
wwatcher history --json               # Output cronologia avvisi come JSON
wwatcher test-sound                   # Test suoni avviso
wwatcher test-webhook                 # Invia payload webhook di test

Vedi QUICKSTART.md per istruzioni di configurazione dettagliate.

Configurazione

La configurazione è salvata in ~/.config/wwatcher/config.json (macOS/Linux) o %APPDATA%\wwatcher\config.json (Windows).

Esegui wwatcher setup per una procedura guidata in 6 passi che configura:

1. Piattaforme — Polymarket, Kalshi o entrambe
2. Categorie — Sport, Crypto, Politica, Economia, ecc. con drill-down sottocategorie
3. Soglia e Conservazione — Dimensione minima transazione e periodo di conservazione cronologia
4. Chiavi API — Credenziali Kalshi opzionali
5. Salva e Riepilogo

Documentazione

• docs/WEBHOOK_REFERENCE.md — Schema completo payload webhook, template n8n, esempi di filtri
• docs/API_REFERENCE.md — Tutti i 15 endpoint API con esempi di richiesta/risposta
• docs/plans/ — Documenti di progettazione per ogni fase di implementazione

Sviluppo

Costruito con:

• Rust — Linguaggio di programmazione di sistema
• Tokio — Runtime asincrono
• Reqwest — Client HTTP
• tokio-tungstenite — Client WebSocket (transazioni real-time Kalshi)
• rusqlite — Database SQLite (cronologia avvisi + memoria portafoglio)
• Clap — Parsing argomenti CLI
• Serde — Serializzazione JSON
• Colored — Output colore terminale

Struttura del Progetto

src/
├── main.rs              # Punto di ingresso CLI (clap)
├── config.rs            # Caricamento/salvataggio configurazione
├── db.rs                # Database SQLite (schema, query, migrazione)
├── categories.rs        # Sistema di categorie di mercato (10 categorie, 35+ sottocategorie)
├── whale_profile.rs     # Intelligenza balene (portafoglio, classifica, tasso vincita)
├── types.rs             # Tipi condivisi, tracciamento portafoglio
├── alerts/
│   ├── mod.rs           # Struttura AlertData, costruttore payload
│   ├── display.rs       # Output terminale (tutte le funzioni di visualizzazione)
│   ├── anomaly.rs       # Rilevamento anomalie
│   ├── history.rs       # Cronologia avvisi SQLite
│   ├── sound.rs         # Avvisi audio
│   └── webhook.rs       # Invio webhook
├── commands/
│   ├── mod.rs
│   ├── watch.rs         # Ciclo principale di monitoraggio
│   ├── setup.rs         # Procedura guidata di configurazione in 6 passi
│   ├── status.rs        # Visualizzazione stato
│   └── test.rs          # Test suono + webhook
├── platforms/
│   ├── mod.rs
│   ├── polymarket.rs    # API Polymarket (transazioni, contesto mercato, book ordini, maggiori detentori)
│   └── kalshi.rs        # API Kalshi (transazioni, contesto mercato, book ordini, categorie)
└── ws/
    ├── mod.rs
    └── kalshi.rs         # Client WebSocket Kalshi (stream transazioni real-time)

Risoluzione dei Problemi

Avviso di configurazione non trovata

È normale. Lo strumento funziona senza configurazione utilizzando API pubbliche. Esegui wwatcher setup solo se desideri aggiungere l'autenticazione Kalshi.

Errori API

• Polymarket: L'endpoint pubblico dovrebbe funzionare senza problemi
• Kalshi: L'endpoint pubblico funziona senza autenticazione, ma potrebbero applicarsi limiti di frequenza

Limitazione di Frequenza

Se ricevi limitazioni di frequenza:

• Aumenta --interval per eseguire poll meno frequentemente
• Per Kalshi: Aggiungi credenziali API tramite wwatcher setup

Collaboratori

Grazie a questi collaboratori per le loro idee e miglioramenti:

• @fuzmik - Suggerito la funzionalità di registrazione cronologia avvisi

Integrazione (MCP)

wwatcher include un server MCP di scoring con due strumenti: score_alert e check_preferences. Nessuna chiave API richiesta.

Vedi integration/README.md per configurazione e dettagli degli strumenti.

Prowl Bot (Pianificato)

Un bot Telegram conversazionale con un team multi-agente per mercati di previsione. Il bot parla con te, analizza gli avvisi balena e può piazzare transazioni su Kalshi e Polymarket dopo la tua approvazione.

Vedi docs/plans/2026-02-25-prowl-bot-design.md per il documento di progettazione completo.

Architettura

Tu (CEO) ←→ Telegram ←→ Manager Bot
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
                Ricercatore   Analista    Rischio
                    └─────────┼─────────┘
                              ▼
                      Decisione + Approvazione
                              ▼
                    Esecutore (Kalshi + Polymarket)

• Manager — IA conversazionale con personalità (soul.md), memoria persistente e competenze. Delega al team.
• Ricercatore — raccoglie dati di mercato, notizie, sentiment (ONNX)
• Analista — legge la cronologia balene di wwatcher, assegna punteggi agli avvisi, rileva pattern
• Rischio — valuta dimensioni delle posizioni, gestione del bankroll
• Esecutore — piazza transazioni dopo la tua approvazione

Ogni agente ha la propria anima (personalità), competenze (istruzioni) e memoria (partizione SQLite). LLM cloud per ragionamento (OpenRouter), modelli locali per compiti economici (Ollama), ONNX per ML (sentiment, riordinamento, serie temporali).

Roadmap

Apprendimento Continuo

Il bot raccoglie previsioni dal primo giorno. Quando i mercati si risolvono, costruisce automaticamente dati di addestramento. Ottimizza un modello 7B locale (MLX su Mac, gratuito) che migliora sui tuoi mercati specifici nel tempo. Basato su Turtel et al. 2025 — lo stesso approccio che ha eguagliato la precisione di o1 su Polymarket con un modello 14B.

Licenza

Questo strumento è per scopi educativi e di monitoraggio. Rivedi i termini di servizio per le API di Polymarket e Kalshi.