ToxFlow

Inspiration

Every trading bot on Polymarket is doing the same thing — copy trading, latency arb, or sentiment analysis. Meanwhile, institutional market makers on Wall Street have spent a decade using orderflow toxicity analysis to detect when informed traders are moving. The key paper — Easley, Lopez de Prado & O'Hara (2012) — introduced VPIN and literally detected the 2010 Flash Crash before it happened. Nobody has ever applied this to prediction markets. We wanted to bring that institutional edge to Polymarket.

What it does

ToxFlow detects when smart money is entering a Polymarket prediction market and identifies which side (YES or NO) they're betting on.

It does this through three core capabilities:

VPIN Engine — Buckets trades by volume (not time) and measures how one-sided the orderflow is. High VPIN = informed traders are aggressively consuming liquidity.
Directional VPIN — Our novel extension that reveals not just that smart money is active, but which direction they're trading. Standard VPIN only measures magnitude — ours tells you the side.
Composite Signal — Combines VPIN toxicity with real Polymarket data from Synthesis API. When both agree on direction, confidence multiplies. When they disagree, the signal is suppressed.

The system includes a full Monte Carlo backtesting engine, live market analysis on real Polymarket trades, and a React dashboard for visualization.

How we built it

Core engine in Python — VPIN computation, signal generation, wallet tracking, and strategy execution with NumPy
Data layer via Synthesis API — real Polymarket trades with wallet addresses, live prices, orderbooks, all through a single unified API (no auth needed for market data)
Backtesting with synthetic market generation that models realistic microstructure: background noise trading, informed trader bursts, and gradual price discovery toward resolution
FastAPI backend serving full time-series data (VPIN readings, price series, signals, P&L curves) to the frontend
React + TypeScript + Recharts dashboard with VPIN/price overlay charts, cumulative P&L curves, signal heatmaps, Monte Carlo histograms, and trade logs
uv + pyproject.toml for dependency management, Tailwind CSS v4 for styling

Strategy Logic

Volume Bucketing — Trades grouped into $100 USDC buckets instead of time intervals, normalizing for prediction market burstiness.
VPIN — (1/N) x SUM |V_buy - V_sell| / V_total over 30 buckets. Values above 0.6 = high toxicity.
Directional VPIN — Signed variant: positive = smart money buying YES, negative = buying NO.
Composite Signal — (0.50 x toxicity) + (0.25 x direction) + (0.25 x synthesis_edge), scaled by 2.0x when VPIN and Synthesis agree, 0.3x when they disagree. Trades fire above 0.40 threshold.
Position Management — 12% profit target, 4% stop loss, 600s time exit, VPIN reversal exit, 3-8% position sizing scaled by signal strength.

Architecture

                    +---------------------------+
                    |     Synthesis API          |
                    |  (Real Polymarket Data)    |
                    +-------------+-------------+
                                  |
                                  v
                    +---------------------------+
                    |      VPIN Engine           |
                    |  Volume Bucketing          |
                    |  Tick Rule Classification  |
                    +-------------+-------------+
                                  |
                    +-------------+-------------+
                    |     Spike Detector         |
                    |  Z-Score vs EMA Baseline   |
                    +-------------+-------------+
                                  |
                    +-------------+-------------+
                    |   Signal Compositor        |
                    |  VPIN + Synthesis Edge     |
                    |  Agreement Multiplier      |
                    +-------------+-------------+
                                  |
                    +-------------+-------------+
                    |    Strategy Engine         |
                    |  Entry/Exit Rules          |
                    |  Position Sizing           |
                    +-------------+-------------+
                                  |
              +-------------------+-------------------+
              |                                       |
              v                                       v
+---------------------------+       +---------------------------+
|   Backtesting Engine      |       |      FastAPI Server       |
|  Walk-Forward Simulation  |       |   /api/backtest/single    |
|  Monte Carlo (100+ runs)  |       |   /api/backtest/monte-carlo
+---------------------------+       +-------------+-------------+
                                                  |
                                                  v
                                    +---------------------------+
                                    |    React Dashboard        |
                                    |  VPIN Charts | P&L Curve  |
                                    |  Signal Heatmap | Trades  |
                                    |  Monte Carlo Histogram    |
                                    +---------------------------+

Performance Metrics

Single Backtest: Total P&L, win rate, profit factor, Sharpe ratio, max drawdown, total fees, avg trade P&L — all computed per run with realistic 1% taker fees.

Monte Carlo (100 runs): Mean/median P&L, 5th/95th percentile bounds, profitable runs %, mean Sharpe, mean drawdown — statistical confidence across randomized markets.

Live Analysis: Tested on 3,000+ real Polymarket trades via Synthesis API — 1,108 VPIN readings, 95 toxicity spikes detected, 543 trade signals generated with wallet-level granularity.

Challenges we ran into

Adapting VPIN for binary outcomes — The original paper targets continuous-price equities. Prediction markets have YES/NO tokens, bursty volume patterns, and different fee structures. We had to rethink volume bucketing in USDC notional and adapt the tick rule for CLOB orderflow.
Numpy serialization — numpy.bool isn't JSON-serializable, which silently broke our FastAPI responses until we tracked it down.
Signal noise — Raw VPIN generates too many false positives. The composite signal with agreement/disagreement multipliers was critical to filtering noise, and tuning the z-score threshold required extensive Monte Carlo testing.
Realistic backtesting — Synthetic markets needed to model informed trader bursts realistically. Getting the balance between noise trading and informed flow right took multiple iterations.

Accomplishments that we're proud of

First-ever VPIN implementation for prediction markets — We searched GitHub, academic papers, and crypto forums. Nobody has done this before.
Directional VPIN — A genuine innovation on top of the original paper. Standard VPIN tells you toxicity is high; ours tells you which side to trade.
Live data working — Pulled 3,000+ real Polymarket trades via Synthesis API, ran VPIN analysis, detected 95 toxicity spikes with wallet-level granularity. Not simulated, not delayed — real orderflow.
Full-stack in 48 hours — Core engine, backtesting, live analysis, FastAPI backend, React dashboard with 7 chart components, all wired together and working end-to-end.
6/6 unit tests passing — VPIN bucket completion, symmetric flow detection, informed burst detection, spike detection, directional sell pressure, and engine reset all verified.

What we learned

Market microstructure translates — VPIN was designed for equities, but the core insight (volume-synchronized toxicity measurement) maps beautifully to prediction markets where activity is naturally bursty.
Synthesis API is powerful — A single API for market discovery, trade history with wallet addresses, live prices, and orderbooks. No auth needed for reads. Made the data layer trivial to build.
Agreement multipliers matter — VPIN alone generates signals, but combining it with market data and requiring directional agreement dramatically improved signal quality. The composite approach is what makes it tradeable.
Monte Carlo over single backtests — A single backtest can always be cherry-picked. Running 100+ simulations with randomized parameters gives real statistical confidence in whether the strategy has an edge.

What's next for ToxFlow

Real-time WebSocket streaming — Connect to Synthesis trade WebSocket for live VPIN updates instead of polling historical trades
Paper trading mode — Execute simulated trades against live Polymarket orderbooks to measure real-world performance without capital risk
Multi-market scanner — Monitor 50+ active markets simultaneously, ranking them by current VPIN toxicity to surface the best opportunities
Wallet graph analysis — Cluster wallets not just by accuracy but by co-trading patterns to identify coordinated informed groups
On-chain execution — Wire up actual trade execution via Synthesis trading endpoints with position sizing and risk management
Historical validation — Backtest against real resolved Polymarket markets to measure whether VPIN spikes actually predicted outcomes