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)

API	URL Base	Endpoint Utilizzati
Data API	data-api.polymarket.com	trades, value, positions, closed-positions, leaderboard, top-holders
Gamma API	gamma-api.polymarket.com	markets (contesto + tag)
CLOB API	clob.polymarket.com	book (profondità book ordini)

Kalshi (REST + WebSocket)

API	URL Base	Endpoint Utilizzati
REST API	api.elections.kalshi.com/trade-api/v2	markets/trades, markets/{ticker}, markets/{ticker}/orderbook
WebSocket	wss://api.elections.kalshi.com/trade-api/ws/v2	canale trade (real-time)

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