# Scanna

> Prediction market intelligence API. Real-time signals, AI predictions, smart money tracking, and cross-venue arbitrage detection across Polymarket and Kalshi.

## Free Tier

Sign up with email at https://api.scanna.xyz/get-api-key?plan=free for a free API key (10 requests/minute, no credit card required). Free tier includes raw market data (markets, prices, trades, order books, wallets, holders, leaderboard, open interest, resolutions) plus smart-money and cross-venue divergence signals. ML predictions and composite analytics require Pro ($49/mo) or Enterprise ($299/mo).

## Authentication

All endpoints except /health, /llms.txt, and /docs require an API key.

Pass it as either header:
- `x-api-key: <key>` (preferred)
- `Authorization: Bearer <key>` (also accepted; convenient for SDKs)

Both are bucketed per-key by the rate limiter.

## Endpoints

### GET /hot
Ranked trending markets by composite heat score.
Parameters: limit (1-50, default 10), category (string), min_volume (number), platform (polymarket|kalshi)
Returns: markets[] with heat_score, volume_spike_x, whale_activity, flow_bias, signals[], price_yes, hours_to_resolve

### POST /heat
Single-market deep dive with full signal analysis.
Body: { market_id: string, lookback_minutes?: number }
Returns: Same as /hot plus volume_lookback, flow_score, volatility, price_no, order_book, manifold_probability

### GET /signals
6-factor signal analysis (momentum, volume, whale, smart money, order book, technical).
Parameters: market_id (string, required)
Returns: { direction (bullish|bearish|neutral), probability_change, confidence, signal_summary, signals[] }

### GET /predict
AI probability prediction for a resolved-style market. CatBoost model retrained daily, BSS +0.72 on 170K uncertain markets.
Parameters: market_id (string, required)
Returns: { market_id, predicted_probability (0-1), confidence_interval [low, high], model_source, converged, features_used }

### GET /live-predict
Live mispricing signal for active markets. Computes features on demand and returns model probability vs market price.
Parameters: market_id (string, required)
Returns: { market_id, market_price, predicted_probability, divergence (predicted - market), pct_lifecycle_elapsed, time_remaining_hours, features_snapshot }

### GET /risk-score
Market risk grade (A-F) with 6-factor breakdown.
Parameters: market_id (string, required)
Returns: { grade, overall_score (0-100), factors { resolution_clarity, liquidity, time_risk, volume_quality, spread, category_risk }, warnings[] }

### GET /arbitrage
Scans cached markets for intra-market and correlated arbitrage opportunities.
Parameters: limit (1-100, default 20)
Returns: { intra_market[], correlated[], total, scanned } with net_profit_pct and confidence per row

### GET /insider-score
Wallet insider risk scoring (0-100).
Parameters: wallet (string, required)
Returns: { address, risk_score, risk_level (high|medium|low), risk_factors[], total_trades, win_rate, avg_position_size }

### GET /clusters
Wallet entity clustering via timing correlation and market overlap (pre-computed every 30 min).
Parameters: limit (1-100, default 20)
Returns: { timing[], market_overlap[], total }

### GET /smart-money
Smart money wallet leaderboard by win rate across resolved markets.
Parameters: limit (1-100, default 20), min_trades (number, default 10), min_win_rate (0-1, default 0.6)
Returns: wallets[] with address, win_rate, trades, pnl, total_notional, last_seen

### GET /divergence
Cross-venue price gaps between Polymarket and Kalshi for the same event (sports-only Phase 1).
Parameters: limit (1-100, default 20), min_divergence (0-1, default 0), sport (string)
Returns: pairs[] with event_key, poly_price, kalshi_price, divergence, sport

### GET /export
Labeled ML training data. 22 features per resolved market plus outcome label.
Parameters: limit (1-10000, default 1000), min_trades (number), format (json|csv), category (string), condition_id (string), price_min (0-1), price_max (0-1), sliced (boolean)
Returns: features[] with 22 ML features (OFI, VWAP, smart money, trade microstructure) + winning_side label

### GET /health
No auth required. Returns { status, markets_cached }.

## Features

22 ML features per market: volume_total, volume_zscore, buy_ratio, whale_trade_count, whale_notional_ratio, smart_money_trade_count, smart_money_buy_ratio, smart_money_participation, hours_to_resolve, unique_traders, avg_trade_size, median_price_at_trade, price_volatility, ofi_normalized, vwap, vwap_deviation, late_money_volume_frac, late_money_ofi, price_momentum, price_autocorr, wallet_hhi, trade_count

## Heat Score Weights

Spike 30%, Liquidity 25%, Order Flow 25%, Activity 10%, Urgency 10%. Whale trades ($1K+) boost score.

## Rate Limits

A single per-key cap applies across ALL authenticated endpoints: 10/min Free, 60/min Pro, 300/min Enterprise. /heat has an additional stricter per-route cap (20/min Pro). Only HTTP 2xx API-key responses count as billable usage; 4xx, 5xx, 429, 402, and x402 challenges are excluded.

## Contact

- X/Twitter: https://x.com/scanna_app
- Email: contact@scanna.xyz