Whale Watcher

NOTE: o repositório está em transição para um bot de negociação completo, um agente estilo openclaw com o qual você conversa no seu Telegram, com poder para implantar uma equipe de agentes para realizar pesquisas antes de tomar uma decisão.

Uma ferramenta de CLI em Rust que monitora grandes transações nos mercados de previsão Polymarket e Kalshi. Alertas em tempo real para atividades significativas do mercado com detecção de anomalias integrada.

Repositório: https://github.com/neur0map/polymaster

AVISO LEGAL

Esta ferramenta é apenas para fins informativos e de pesquisa. Use estes dados exclusivamente para tomada de decisão informada e análise de mercado.

Recursos

Monitoramento Central

Monitoramento em tempo real de transações Polymarket e Kalshi
Kalshi WebSocket para detecção instantânea de negociações (fallback de polling HTTP)
Filtragem no lado do servidor Polymarket — a API pré-filtra negociações de baleias, sem desperdício de largura de banda
Limite personalizável (padrão $25,000) e intervalo de polling
Alertas sonoros com triplo bip para atores repetidos
Filtragem por categoria de mercado (10 categorias, 35+ subcategorias)
Seleção de plataforma (somente Polymarket, somente Kalshi ou ambas)

Inteligência de Baleias (Polymarket)

Perfis de baleias — valor da carteira, posição no ranking, lucro, taxa de vitória, posições abertas
Consulta ao leaderboard — verifica se a carteira está entre os 500 maiores traders da Polymarket
Memória de carteira de 12 horas — detecta baleias que retornam, duplicação de posição e inversões de baleias
Maiores detentores — mostra os 5 maiores detentores e sua concentração de participação por mercado
Perfis em cache por 30 min, leaderboard em cache por 1 hora

Inteligência de Mercado

Profundidade do livro de ordens para ambas as plataformas (CLOB da Polymarket + orderbook da Kalshi)
Contexto de mercado — probabilidades SIM/NÃO, spread, volume 24h, juros em aberto, variação de preço, liquidez
Categorias nativas da Kalshi via API (mais precisas do que correspondência por palavras-chave)
Tags da Polymarket extraídas da API Gamma
Detecção de anomalias para apostas extremas, posições contrárias e grande capital

Rastreamento de Carteiras

Alertas elevados para atores repetidos (2+ transações em 1 hora)
Alertas de alta prioridade para atores pesados (5+ transações em 24 horas)
Rastreia volume e frequência de transações por carteira
Detecção de baleias recorrentes (aumento de aposta, inversão de posições)
Memória persistente de carteiras com suporte SQLite entre reinicializações

Integrações

Notificações via webhook para n8n, Zapier, Make, Discord ou qualquer endpoint
Payload JSON rico com contexto de mercado, perfil de baleia, livro de ordens e maiores detentores
Servidor MCP de pontuação para pontuar alertas e filtrar preferências

Infraestrutura

Banco de dados SQLite para histórico de alertas e memória de carteiras
Retenção de dados configurável (7, 30, 90 dias ou para sempre)
Assistente de configuração guiado em 6 etapas
Nenhuma chave de API necessária para a funcionalidade básica (todos os dados públicos)
Rápido e eficiente, construído em Rust

Início Rápido

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

É isso. Nenhuma chave de API é necessária — todos os dados vêm de endpoints públicos. Você verá alertas de baleias no seu terminal em segundos.

Execute wwatcher setup para configurar plataformas, categorias, limites, webhooks e chaves de API opcionais.

Consulte QUICKSTART.md para instruções detalhadas de configuração e integração de webhook.

Instalação

A Partir do Código-Fonte

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

O binário estará em target/release/wwatcher. Ou instale-o em todo o sistema:

cargo install --path .

Informações da API

O wwatcher usa 15 endpoints de API em 3 APIs da Polymarket, 1 API REST da Kalshi e 1 WebSocket da Kalshi. Consulte docs/API_REFERENCE.md para a documentação completa dos endpoints.

Polymarket (3 APIs, sem autenticação necessária)

API	Base URL	Endpoints Utilizados
Data API

Kalshi (REST + WebSocket)

API	Base URL	Endpoints Utilizados
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`	canal de negociação (tempo real)

Todos os endpoints são públicos — nenhuma chave de API é necessária. Para acesso aprimorado à Kalshi, execute wwatcher setup.

Integração via Webhook

O wwatcher envia payloads JSON ricos para qualquer URL de webhook com: contexto de mercado, perfil de baleia, profundidade do livro de ordens, maiores detentores e atividade de carteira.

Consulte docs/WEBHOOK_REFERENCE.md para:

Esquema completo do payload com todos os campos
Modelos de mensagem do n8n para Telegram/Discord
Exemplos de filtros (atores pesados, 100 maiores baleias, somente saídas)
Campos calculados (pontuação de qualidade da baleia, desequilíbrio entre compra/venda)

Exemplo de Alerta

Quando uma transação de baleia é detectada, você verá uma saída enriquecida:

[ALERT] LARGE TRANSACTION DETECTED - Polymarket
======================================================================
Question:   Will Bitcoin reach 100k by end of 2026?
Position:   BUYING 'Yes' shares
Prediction: Market believes 'Yes' has 65.0% chance

TRANSACTION DETAILS
Amount:     $50,000.00
Contracts:  76923.08 @ $0.6500 each
Action:     BUY shares
Timestamp:  2026-02-13T18:00:00Z

[WALLET ACTIVITY]
Wallet:   0x742d35...f0bEb
Txns (1h):  2
Txns (24h): 5
Volume (24h): $380,000.00
Status: HEAVY ACTOR (5+ transactions in 24h)

[MARKET CONTEXT]
Odds:          YES 65.0% | NO 35.0%
Spread:        $0.02 (tight)
24h Volume:    $450,000
Open Interest: $2,100,000
24h Move:      +3.2%
Liquidity:     $180,000
Tags:          crypto, bitcoin

[WHALE PROFILE]
Leaderboard:  #45 (TOP 50)
Profit:       +$890,000
Portfolio:    $2,340,000
Open Pos:     12
Win Rate:     73.0%
Markets:      195

[ORDER BOOK]
Best Bid:   $0.6400  |  Best Ask: $0.6600  |  Spread: $0.0200
Bid Depth:  $45,000 (12 levels)  |  Ask Depth: $38,000 (9 levels)
Imbalance:  54% bid / 46% ask (moderate bid pressure)

[TOP HOLDERS]
  #1: 0x742d...bEb — 150,000 shares (12.0%)
  #2: 0x8a3f...1D  — 120,000 shares (9.6%)
  #3: 0x5b9c...aF  — 95,000 shares (7.6%)
  Top 3 control 29.2% of shares
======================================================================

Comandos

wwatcher watch                        # Start monitoring (default: $25k threshold, 5s interval)
wwatcher watch -t 50000               # Set threshold to $50,000
wwatcher watch -t 10000 -i 10         # $10k threshold, 10s polling interval
wwatcher setup                        # 6-step guided configuration wizard
wwatcher status                       # View current configuration and DB stats
wwatcher history                      # View last 20 alerts
wwatcher history -l 50 -p polymarket  # Last 50 Polymarket alerts
wwatcher history --json               # Output alert history as JSON
wwatcher test-sound                   # Test alert sounds
wwatcher test-webhook                 # Send test webhook payloads

Consulte QUICKSTART.md para instruções detalhadas de configuração.

Configuração

A configuração é armazenada em ~/.config/wwatcher/config.json (macOS/Linux) ou %APPDATA%\wwatcher\config.json (Windows).

Execute wwatcher setup para um assistente guiado em 6 etapas que configura:

Plataformas — Polymarket, Kalshi ou ambas
Categorias — Esportes, Cripto, Política, Economia, etc. com detalhamento por subcategoria
Limite e Retenção — Tamanho mínimo da negociação e período de retenção do histórico
Chaves de API — Credenciais opcionais da Kalshi
Salvar e Resumo

Documentação

docs/WEBHOOK_REFERENCE.md — Esquema completo do payload de webhook, modelos n8n, exemplos de filtros
docs/API_REFERENCE.md — Todos os 15 endpoints de API com exemplos de requisição/resposta
docs/plans/ — Documentos de design para cada fase de implementação

Desenvolvimento

Construído com:

Rust — Linguagem de programação de sistemas
Tokio — Runtime assíncrono
Reqwest — Cliente HTTP
tokio-tungstenite — Cliente WebSocket (negociações em tempo real da Kalshi)
rusqlite — Banco de dados SQLite (histórico de alertas + memória de carteiras)
Clap — Análise de argumentos de CLI
Serde — Serialização JSON
Colored — Saída colorida no terminal

Estrutura do Projeto

src/
├── main.rs              # CLI entry point (clap)
├── config.rs            # Config loading/saving
├── db.rs                # SQLite database (schema, queries, migration)
├── categories.rs        # Market category system (10 categories, 35+ subcategories)
├── whale_profile.rs     # Whale intelligence (portfolio, leaderboard, win rate)
├── types.rs             # Shared types, wallet tracker
├── alerts/
│   ├── mod.rs           # AlertData struct, payload builder
│   ├── display.rs       # Terminal output (all display functions)
│   ├── anomaly.rs       # Anomaly detection
│   ├── history.rs       # SQLite alert history
│   ├── sound.rs         # Audio alerts
│   └── webhook.rs       # Webhook sender
├── commands/
│   ├── mod.rs
│   ├── watch.rs         # Main watch loop
│   ├── setup.rs         # 6-step setup wizard
│   ├── status.rs        # Status display
│   └── test.rs          # Sound + webhook tests
├── platforms/
│   ├── mod.rs
│   ├── polymarket.rs    # Polymarket API (trades, market context, order book, top holders)
│   └── kalshi.rs        # Kalshi API (trades, market context, order book, categories)
└── ws/
    ├── mod.rs
    └── kalshi.rs         # Kalshi WebSocket client (real-time trade stream)

Solução de Problemas

Aviso de configuração não encontrada

Isso é normal. A ferramenta funciona sem configuração usando APIs públicas. Execute wwatcher setup somente se quiser adicionar autenticação da Kalshi.

Erros de API

Polymarket: o endpoint público deve funcionar sem problemas
Kalshi: o endpoint público funciona sem autenticação, mas limites de taxa podem se aplicar

Limite de Taxa

Se você estiver sofrendo limite de taxa:

Aumente o --interval para fazer polling com menos frequência
Para Kalshi: adicione credenciais de API via wwatcher setup

Contribuidores

Agradecimentos a estes contribuidores por suas ideias e melhorias:

@fuzmik — Sugeriu o recurso de registro do histórico de alertas

Integração (MCP)

O wwatcher inclui um servidor MCP de pontuação com duas ferramentas: score_alert e check_preferences. Nenhuma chave de API é necessária.

Consulte integration/README.md para detalhes de configuração e das ferramentas.

Prowl Bot (Planejado)

Um bot conversacional do Telegram com uma equipe multiagente para mercados de previsão. O bot conversa com você, analisa alertas de baleias e pode colocar negociações na Kalshi e na Polymarket após sua aprovação.

Consulte docs/plans/2026-02-25-prowl-bot-design.md para o documento completo de design.

Arquitetura

You (CEO) ←→ Telegram ←→ Manager Bot
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
                Researcher  Analyst    Risk
                    └─────────┼─────────┘
                              ▼
                      Decision + Approval
                              ▼
                    Executor (Kalshi + Polymarket)

Manager — IA conversacional com personalidade (soul.md), memória persistente e habilidades. Delega para a equipe.
Researcher — coleta dados de mercado, notícias, sentimento (ONNX)
Analyst — lê o histórico de baleias do wwatcher, pontua alertas, detecta padrões
Risk — avalia dimensionamento de posição e gestão de banca
Executor — coloca negociações após sua aprovação

Cada agente tem sua própria alma (personalidade), habilidades (instruções) e memória (partição SQLite). LLMs em nuvem para raciocínio (OpenRouter), modelos locais para tarefas baratas (Ollama), ONNX para ML (sentimento, reordenação, séries temporais).

Roteiro

Aprendizado Contínuo

O bot coleta previsões desde o primeiro dia. Quando os mercados são resolvidos, ele constrói dados de treinamento automaticamente. Faça fine-tuning de um modelo local de 7B (MLX no Mac, gratuito) que melhora nos seus mercados específicos com o tempo. Baseado em Turtel et al. 2025 — a mesma abordagem que igualou a precisão do o1 na Polymarket com um modelo de 14B.

Licença

Esta ferramenta é para fins educacionais e de monitoramento. Revise os termos de serviço das APIs da Polymarket e da Kalshi.

Fase 1	Bot conversacional — Telegram, personalidade, memória, coleta de dados	Planejado
Fase 2	Criação de equipe — delegação multiagente, análise de baleias	Planejado
Fase 3	Pipeline de alertas — webhook do wwatcher aciona análise automática	Planejado
Fase 4	Execução — colocação de ordens na Kalshi + Polymarket	Planejado
Fase 5	Modelos de ML — sentimento ONNX, reordenação, séries temporais	Planejado
Fase 6	Aprendizado contínuo — Self-SFT + GRPO em resultados de mercados resolvidos	Planejado

polymaster

Mais Populares