Poly-Sentinel

Real-time Polymarket insider trading detector. Monitors geopolitics prediction markets via WebSocket, detects anomalies through multi-signal statistical analysis, and triggers an AI verification pipeline that produces PDF reports.

How It Works

Polymarket WebSocket --> anomaly-engine --> alert-router
                                                |
                              LOW:  log only    |
                              MED:  terminal    |
                              HIGH: ----------->|
                                                v
                                          claude-client (Anthropic API)
                                                |
                                                v
                                          lumen-bridge (SSOTCS MCP)
                                                |
                                                v
                                          pdf-generator (Typst)
                                                |
                                                v
                                          Save + auto-open + terminal alert

Trade data streams in via WebSocket. Four statistical signals are computed in real-time and combined into a composite anomaly score. When the score crosses the HIGH threshold (>= 0.8), the system:

1. Calls Claude to analyze the anomaly and produce a verdict
2. Pipes Claude's narrative through Lumen's SSOTCS verification system
3. If the trust score passes (> 0.7), generates a PDF report with full analysis

Anomaly Detection Signals

Signal	Formula	What It Detects
Volume Z-Score	z = (v - mean) / stddev	Sudden volume spikes vs. rolling baseline
Price-Volume Divergence	PVD = dV% / max(dP%, e)	Large volume without proportional price movement
Order Flow Imbalance	OFI = |V_buy - V_sell| / (V_buy + V_sell)	One-sided buying/selling pressure
Herfindahl Index	HHI = sum(s_i / S)^2	Trade size concentration (few large actors)

Composite score: S = w1*sig(z_vol) + w2*sig(z_pvd) + w3*OFI + w4*HHI

Alert Tiers

Tier	Condition	Action
LOW	S < 0.5	Structured log entry
MEDIUM	0.5 <= S < 0.8	Terminal alert with score breakdown
HIGH	S >= 0.8	Full pipeline: Claude analysis -> Lumen verification -> PDF report

Project Structure

Crate	Purpose
sentinel-types	Shared types: Trade, Market, AnomalyScore, Config, Report
polymarket-client	WebSocket consumer + Gamma API market discovery
anomaly-engine	Rolling windows, 4 statistical signals, composite scorer
alert-router	Tiered alert dispatch (log / terminal / pipeline)
claude-client	Anthropic Messages API wrapper with 3x retry
lumen-bridge	MCP client spawning Lumen's SSOTCS server for verification
pdf-generator	Typst-based PDF report rendering with auto-open
poly-sentinel	Main binary orchestrator wiring everything together

Prerequisites

• Rust (edition 2024)
• Typst CLI (cargo install typst-cli)
• Anthropic API key (set as ANTHROPIC_API_KEY env var)
• Lumen (included as git submodule)

Setup

# Clone with submodules
git clone --recurse-submodules ssh://git@tu-po.com/xemmerling/Poly-Sentinel.git
cd Poly-Sentinel

# Or if already cloned without submodules
git submodule update --init --recursive

# Install typst CLI
cargo install typst-cli

# Build
cargo build --release

# Set your API key
export ANTHROPIC_API_KEY="your-key-here"

# Run
cargo run --release

Configuration

All configuration lives in sentinel.toml. See docs/configuration.md for the full reference.

Key sections:

• polymarket -- categories and specific market IDs to monitor
• detection -- window size, signal weights, alert thresholds
• claude -- API key env var name, model selection
• lumen -- path to Lumen repo, MCP server name
• output -- report directory, auto-open behavior

Documentation

• Architecture
• Anomaly Detection Math
• Configuration Reference
• Analysis Pipeline

License

See LICENSE for details.