# Scanna

> Prediction market intelligence for AI agents and quant funds. Real-time signals, ML mispricing detection, smart money tracking, and cross-venue arbitrage across Polymarket and Kalshi.

This document contains the full content of all documentation pages for AI consumption.

---

## Scanna

**URL:** https://docs.scanna.xyz/docs
**Description:** The prediction market intelligence platform for AI agents and quant funds — real-time signals, ML mispricing detection, smart money tracking, and cross-venue arbitrage across Polymarket and Kalshi, delivered through an API, an MCP server, SDKs, and more.

**The prediction market intelligence platform for AI agents and quant funds.**
Scanna turns raw Polymarket and Kalshi activity into real-time signals, ML
mispricing detection, smart money tracking, and cross-venue arbitrage — and
delivers it through whichever surface fits your stack.

`20,000+ markets · 20.5M trades · 407K wallets`

## Products

  
**REST API**

    The core intelligence API — heat scores, ML predictions, smart money, divergence, and raw market data over HTTP. Live.
  
  
**MCP Server**

    Scanna as tools inside Claude, Cursor, and other AI agents — connect in one command. Live (beta).
  
  
**Marketplace**

    The Scanna plugin for Claude Code — skills, slash commands, and the MCP server. Beta.
  
  
**SDKs**

    Typed TypeScript and Python clients over the API. Pre-release.
  
  
**Simulation**

    A proprietary multi-agent simulation engine for scenario modeling. Private beta.
  
  
**Mobile · Scanna Pulse**

    A consumer prediction-market chatbot for iOS and Android. Private beta.
  

## Get started

  
**Get an API key**

    Free email signup — no card required. One key works across the API, MCP, and SDKs.
  
  
**Quickstart**

    Make your first authenticated request in minutes.
  

## What the intelligence gives you

- **Trending signals** — a ranked feed of the hottest markets by a composite [heat score](/docs/concepts/signal-engine), with whale activity and human-readable signals.
- **ML predictions** — independent probability estimates for resolved and live markets from a daily-retrained model. See [AI Predictions](/docs/api/predict).
- **Smart money** — performance-ranked wallets so you can see where informed capital is moving. See [Smart Money](/docs/concepts/smart-money).
- **Cross-venue arbitrage** — price gaps for the same event across Polymarket and Kalshi via [Divergence](/docs/api/divergence).
- **Raw data** — markets, prices, order books, trades, holders, wallets, and leaderboards. See [Raw Data](/docs/api/markets).
- **Training data** — labeled, time-sliced features for your own models via [Training Data Export](/docs/api/training-data-export).

---

## Marketplace

**URL:** https://docs.scanna.xyz/docs/marketplace
**Description:** Scanna's Claude Code plugin — skills, slash commands, and the MCP server in a single install.

The Scanna **Marketplace** is a [Claude Code](https://claude.com/claude-code)
plugin marketplace. The `scanna` plugin brings Scanna's prediction-market
intelligence into your editor as skills, slash commands, and the
[MCP server](/docs/mcp/overview) — so you can ask about markets, signals,
wallets, and divergence without leaving Claude Code.

Beta (v0.1.0). The slash commands below work today against the live API with any
valid Scanna key. Richer skill flows that use the bundled MCP server roll out as
`@scanna/mcp` is published to npm.

## Install

```bash
/plugin marketplace add scanna-xyz/scanna-marketplace
/plugin install scanna@scanna-marketplace
```

## Configure

The plugin needs a Scanna API key —
[get one free](https://api.scanna.xyz/get-api-key). Set `SCANNA_API_KEY` in your
environment:

```bash

```

…or in `~/.claude/settings.json`:

```json
{
  "env": {
    "SCANNA_API_KEY": "sk_live_..."
  }
}
```

Then run `/scanna-doctor` to confirm your key and the API are healthy.

## Slash commands

| Command | Description |
| --- | --- |
| `/scanna-setup` | Guided onboarding |
| `/scanna-doctor [limit]` | Check your key + API health |
| `/scanna-hot [limit]` | Top trending markets |
| `/scanna-market <id>` | Deep-dive a specific market |

## Skills

Skills activate automatically from natural-language intent:

- **scanna-onboarding** — first-time setup and key configuration
- **scanna-market-intel** — discover trending markets and ML signals
- **scanna-divergence-and-arb** — find arbitrage and cross-venue divergence
- **scanna-wallet-and-flow-analysis** — score wallets and surface smart money
- **scanna-agent-development** — build production agents on Scanna

## How it works

Slash commands call the [Scanna REST API](/docs/api/introduction) directly; the
bundled [MCP server](/docs/mcp/overview) powers the richer skill flows as it
ships. One Scanna key powers all of it.

---

## Mobile · Scanna Pulse

**URL:** https://docs.scanna.xyz/docs/mobile
**Description:** Scanna Pulse, a consumer prediction-market chatbot for iOS and Android (private beta).

**Private beta**

Scanna Pulse is built and working in private beta — not yet on the public app
stores. This page is a preview; detailed guides land closer to launch.

**Scanna Pulse** brings the intelligence Scanna provides to quant funds and AI
agents to your phone, as a chat interface anyone can use. Ask about a market and
get the signal stack, ML probability, and smart-money context back in plain
language.

## Platforms

iOS and Android, built with React Native and Expo.

## What it does

A conversational interface over Scanna's market intelligence — a live market
ticker, market-intel cards, and paper trading (read-only intel plus simulated
trades, no real funds). It's the same data behind the [API](/docs/api/introduction)
and [MCP server](/docs/mcp/overview), packaged for everyday use.

## Status

In private beta; not yet on the App Store or Google Play. Follow
[@scanna_app](https://x.com/scanna_app) for launch news.

---

## Plans & Pricing

**URL:** https://docs.scanna.xyz/docs/plans
**Description:** Scanna API access tiers — Free, Pro, and Enterprise — plus usage-based plans, with a full feature comparison.

Self-serve. Free email signup — no card required — or Stripe Checkout for
Pro/Enterprise. Your key lands in your inbox within 30 seconds.

## Tiers

  
**Free — $0/mo**

    Raw market data for evaluation and side projects. 10 requests/minute. Markets, prices, trades, books, wallets, leaderboards, plus smart-money + divergence signals. No card.
  
  
**Pro — $49/mo**

    For production bots and small quant teams. 60 requests/minute. All free endpoints plus ML predictions, signals, and arbitrage. Email support.
  
  
**Enterprise — $299/mo**

    For funds and agents running at scale. 300 requests/minute. Everything in Pro plus early access to new endpoints. Priority support and SLA.
  

Two usage-based options round out the lineup:

- **Pay-per-call** *(coming soon)* — metered, per-request billing via Stripe for bursty workloads, with no monthly commitment. Same endpoints as Pro.
- **x402** *(agents, live beta)* — HTTP-native agent payments on Base & Solana via the x402 protocol (EIP-3009 / SVM exact). No account required — pay per request in USDC from a wallet. Ideal for autonomous AI agents. [View on GitHub →](https://github.com/scanna-xyz)

## Compare plans

| | Free | Pro | Enterprise | PAYG | x402 |
| --- | --- | --- | --- | --- | --- |
| **Price** | $0 | $49/mo | $299/mo | TBD | Per call |
| **Rate limit** | 10/min | 60/min | 300/min | TBD | Protocol-limited |
| **Raw data** | Yes | Yes | Yes | Yes | Yes |
| **ML + Track A** | — | Yes | Yes | Yes | Yes |
| **Auth** | API key | API key | API key | API key | x402 payment |
| **Billing** | None | Stripe monthly | Stripe monthly | Stripe metered | On-chain (Base/Solana) |
| **Support** | Community | Email | Priority + SLA | Community | GitHub |
| **Status** | Live | Live | Live | Coming soon | Live (beta) |

Already have an account? [Log in](https://api.scanna.xyz/login) to retrieve your
key. Need to talk first? [contact@scanna.xyz](mailto:contact@scanna.xyz).

---

## Quickstart

**URL:** https://docs.scanna.xyz/docs/quickstart
**Description:** Get a Scanna API key and make your first authenticated request in minutes.

Get from zero to your first signal in three steps.

**Get an API key**

[Sign up free](https://api.scanna.xyz/get-api-key?plan=free) — no card required.
Your key lands in your inbox within ~30 seconds. Pro and Enterprise keys are
available via Stripe Checkout on the [plans page](/docs/plans).

**Make your first call**

Fetch the top trending markets in a single request:

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/hot?limit=5"
```

**Read the response**

Each market comes back with a composite `heat_score`, whale activity, and
human-readable signals:

```json
{
  "markets": [
    {
      "market_id": "0xfb1835...",
      "question": "Will Manchester City win the 2025-26 EPL?",
      "heat_score": 0.6,
      "volume_spike_x": 1.2,
      "hours_to_resolve": 1566,
      "liquidity_usd": 388845,
      "whale_activity": {
        "count": 3,
        "total_notional": 4678,
        "direction": "buy"
      },
      "volume_24h": 19274,
      "price_yes": 0.09,
      "flow_bias": "buy",
      "tags": [],
      "end_date": "2026-05-27T00:00:00Z",
      "signals": [
        "3 whale buys totaling $4,678",
        "Net buyers dominating",
        "Trade frequency above baseline"
      ]
    }
  ],
  "updated_at": "2026-03-22T18:06:24.950Z"
}
```

**Go deeper**

Drill into a single market with [`POST /heat`](/docs/api/heat), score
a market or wallet with [Analytics](/docs/api/risk-score), or pull an
[ML prediction](/docs/api/predict). When you're ready to wire it
into a bot, copy a working [integration example](/docs/api/examples).

A good first lap: `GET /health` (no auth) → `GET /hot` → `POST /heat` on an
interesting market → `GET /predict` for a model probability.

## Suggested testing order

When evaluating the full surface, work through it roughly in this order:

1. **Health** — `GET /health` confirms the service is up (no key needed).
2. **Trending** — `GET /hot` for the ranked feed.
3. **Deep dive** — `POST /heat` for one market's full signal breakdown.
4. **Prediction** — `GET /predict` (resolved) or `GET /live-predict` (active).
5. **Risk & signals** — `GET /risk-score`, `GET /signals`.
6. **Wallets** — `GET /smart-money`, `GET /wallet/{address}`.
7. **Cross-venue** — `GET /divergence`.
8. **Export** — `GET /export` for training data.
9. **Monitoring** — `GET /metrics` for cache, DB, and model status.

---

## Simulation

**URL:** https://docs.scanna.xyz/docs/simulation
**Description:** Scanna's proprietary multi-agent simulation engine for scenario modeling (private beta).

**Private beta**

The simulation engine is built and running internally — it's in private beta and
not yet publicly available, so there's no public endpoint to call today. This
page describes what it does and how to get early access.

Scanna has built a proprietary **multi-agent simulation engine**. Given a
scenario — a press release, news article, policy draft, or counterfactual — it
spins up a synthetic population of agents that post, argue, and trade across a
simulated social layer and prediction market, then produces an analysis of how
the event would likely play out.

## How it works

The pipeline extracts entities from the scenario into a knowledge graph,
generates grounded personas, runs a concurrent multi-round simulation across a
social layer and a prediction market, and writes a report citing the simulated
activity. Outputs are designed as **data exports** — a trajectory file, a
reproducibility fingerprint, and a Markdown report — meant to feed back into
Scanna's analytics rather than a chat UI.

## Status

End-to-end runs have been validated internally. The engine is in private beta
today; public access opens once it's deployed behind a public API. Want early
access for research or validation? [Reach out](mailto:contact@scanna.xyz).

---

## Signal Engine

**URL:** https://docs.scanna.xyz/docs/concepts/signal-engine
**Description:** How Scanna's composite heat score is built from a weighted blend of market signals.

The heat score (0-1) is a weighted composite of 5 signals:

| Signal | Weight | What it measures |
| --- | --- | --- |
| Volume Spike | 30% | Multiplier vs historical baseline (5x+ = max component) |
| AMM Liquidity | 25% | Percentile rank of Gamma pool liquidity |
| Order Flow | 25% | Net buy vs sell pressure from recent trades |
| Activity | 10% | Trade frequency vs baseline |
| Urgency | 10% | Time to market resolution (closer = higher) |

Whale trades ($1,000+ notional) in the last 4 hours provide an additional score
boost (+0.05 per whale, max 3).

## Human-readable signals

Alongside the score, the engine emits human-readable signal strings, for example:

- `Volume 5.3x baseline — surging`
- `3 whale buys totaling $4,678`
- `Net buyers dominating`
- `Resolves in 48h`

These appear in the `signals` array on [`/hot`](/docs/api/hot) and
`POST /heat`. See the [response format](/docs/api/response-format) for the
full field list.

---

## Smart Money

**URL:** https://docs.scanna.xyz/docs/concepts/smart-money
**Description:** How Scanna identifies and ranks high-performing wallets to surface smart money activity.

Scanna tracks wallet performance across thousands of resolved Polymarket
markets. Wallets with ≥10 trades and ≥65% win rate are labeled **smart money**.

When a whale trade on [`/hot`](/docs/api/hot) or `POST /heat` comes
from a smart money wallet, the `smart_money_count` field tells you. This is the
"Nansen for prediction markets" signal that bots can't replicate without
maintaining their own wallet database.

Use [`GET /smart-money`](/docs/api/smart-money) to see the full leaderboard
and identify which wallets to watch.

---

## Arbitrage

**URL:** https://docs.scanna.xyz/docs/api/arbitrage
**Description:** Scan all markets for intra-market and correlated arbitrage.

`GET /arbitrage`

Requires a **Pro** or **Enterprise** key. See [Plans](/docs/plans).

Scans all cached markets for profit opportunities: intra-market (YES + NO < $1
after fees) and correlated (similar questions priced >2.5% apart).

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-100 | 20 | Max opportunities per category |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/arbitrage?limit=20"
```

---

## Authentication

**URL:** https://docs.scanna.xyz/docs/api/authentication
**Description:** How to authenticate Scanna API requests with your API key, including header precedence and error responses.

Pass your API key via the `x-api-key` header on every request (except
`/health`, which is public and unmetered).

```bash
curl -H "x-api-key: YOUR_KEY" "https://api.scanna.xyz/hot"
```

## Header precedence

`x-api-key` is the preferred, canonical header. `Authorization: Bearer YOUR_KEY`
is also accepted as a fallback for SDKs and generated code that default to
Bearer auth. Both are bucketed per-key by the rate limiter.

```bash
# Equivalent — Bearer fallback
curl -H "Authorization: Bearer YOUR_KEY" "https://api.scanna.xyz/hot"
```

Production keys are formatted as `sk_live_` followed by 64 hex characters.

## Errors

A missing or invalid key returns `401`:

```json
{
  "error": "UNAUTHORIZED",
  "message": "Valid API key required. Pass via x-api-key header (preferred) or Authorization: Bearer <key>."
}
```

If a correctly-formatted key is presented but the database is temporarily
unreachable, the API returns `503 SERVICE_UNAVAILABLE` rather than a misleading
`401` — so you can distinguish "bad key" from "try again shortly".

All error responses share the shape `{ "error": "<CODE>", "message": "<text>" }`.

---

## Clusters

**URL:** https://docs.scanna.xyz/docs/api/clusters
**Description:** Wallet entity clustering via timing and market overlap.

`GET /clusters`

Requires a **Pro** or **Enterprise** key. See [Plans](/docs/plans).

Wallet entity clustering via timing correlation (trades within 30s) and market
overlap (Jaccard >70%). Background pre-computed every 30 min.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-100 | 20 | Max clusters per category |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/clusters?limit=20"
```

---

## Divergence

**URL:** https://docs.scanna.xyz/docs/api/divergence
**Description:** Detect price gaps for the same event across Polymarket and Kalshi with the divergence endpoint.

## Divergence

`GET /divergence`

Detects price gaps between Polymarket and Kalshi for the same event. When the
same event is priced 7 cents apart across venues, one platform is wrong — that's
a direct arbitrage signal.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-100 | 20 | Number of pairs to return |
| `min_divergence` | number | 0 | Minimum price gap (0-1 scale) |
| `sport` | string | — | Filter by sport (nba, nfl, nhl, mlb, etc.) |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/divergence?sport=nba&min_divergence=0.05"
```

```json
{
  "pairs": [{
    "event_key": "nba-lal-bos-2026-03-25",
    "question": "Nba Lal Bos 2026 03 25",
    "sport": "nba",
    "polymarket_slug": "nba-lal-bos-2026-03-25",
    "kalshi_ticker": "KXNBAGAME-26MAR25LALBOS-LAL",
    "poly_price": 0.62,
    "kalshi_price": 0.55,
    "divergence": 0.07
  }],
  "total_matched": 11,
  "updated_at": "2026-03-24T..."
}
```

Divergence data is available when sports games are scheduled. Coverage: NBA,
NFL, NHL, MLB, CFB, CBB, PGA, Tennis. Returns empty when no games are live.

---

## Integration Examples

**URL:** https://docs.scanna.xyz/docs/api/examples
**Description:** Drop-in examples for calling the Scanna API from Python, TypeScript/Node, and an LLM agent tool.

Drop-in starting points for the most common integrations. Each filters the
trending feed for actionable markets — whale activity plus a high
[heat score](/docs/concepts/signal-engine).

**Python**

```python

API_KEY = "your-key-here"
BASE = "https://api.scanna.xyz"

# Get top 10 hottest markets
resp = requests.get(f"{BASE}/hot?limit=10", headers={"x-api-key": API_KEY})
markets = resp.json()["markets"]

for m in markets:
    if m["whale_activity"] and m["heat_score"] > 0.7:
        print(f"HOT: {m['question']}")
        print(f"  Score: {m['heat_score']}  Spike: {m['volume_spike_x']}x")
        print(f"  Whales: {m['whale_activity']['count']} ({m['whale_activity']['direction']})")
        print(f"  Signals: {m['signals']}")
```

**TypeScript / Node**

```typescript
const API_KEY = "your-key-here";
const BASE = "https://api.scanna.xyz";

const res = await fetch(`${BASE}/hot?limit=10`, {
  headers: { "x-api-key": API_KEY },
});
const { markets } = await res.json();

// Find markets with whale activity + high heat
const actionable = markets.filter(
  (m: any) => m.whale_activity && m.heat_score > 0.6
);

for (const m of actionable) {
  console.log(`${m.question} — score: ${m.heat_score}, spike: ${m.volume_spike_x}x`);
  console.log(`  Whales: ${m.whale_activity.count} ${m.whale_activity.direction}`);
}
```

**LLM / AI agent tool**

```bash
# Use as a tool in your LangChain / CrewAI / custom agent:
#
# Tool: get_hot_markets
# Description: Returns the hottest prediction markets with signals
# Input: limit (number), min_volume (number)
# Output: JSON array of markets with heat_score, whale_activity, signals
#
# The agent can use heat_score and signals to decide which markets
# to analyze further or trade on.

curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/hot?limit=5"
```

Ready to go further? Grab a [free API key](https://api.scanna.xyz/get-api-key?plan=free)
and browse the [API reference](/docs/api/introduction).

---

## Health

**URL:** https://docs.scanna.xyz/docs/api/health
**Description:** Service health and cache status. No auth required.

`GET /health`

No auth required. Returns cache status.

```bash
curl https://api.scanna.xyz/health
# {"status":"ok","markets_cached":19946}
```

---

## Market heat

**URL:** https://docs.scanna.xyz/docs/api/heat
**Description:** Full single-market signal analysis.

`POST /heat`

Single-market deep dive — full signal analysis for one market.

```bash
curl -X POST \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"market_id": "0xfb1835...", "lookback_minutes": 60}' \
  "https://api.scanna.xyz/heat"
```

Returns everything from [`/hot`](/docs/api/hot) plus:

| Field | Type | Description |
| --- | --- | --- |
| `volume_lookback` | number | USD volume in lookback window |
| `flow_score` | number | -1 (all sell) to 1 (all buy) |
| `volatility` | string | "low", "medium", or "high" |
| `price_no` | number | NO outcome price (0-1) |

`POST /heat` is the most compute-heavy endpoint and carries an extra per-route
rate cap on top of the [global limit](/docs/api/rate-limits).

---

## Holders

**URL:** https://docs.scanna.xyz/docs/api/holders
**Description:** Top wallets for a market, enriched with win-rate.

`GET /holders/{condition_id}`

Top wallets for a market, enriched with win-rate. Proxies Polymarket Data API
`/holders` and joins with our `wallet_stats` table so each holder includes
win-rate + total trades inline.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `condition_id` | string | — | **Required.** Polymarket conditionId of the market (path param) |
| `limit` | 1-100 | 50 | Number of top holders |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/holders/0xfb1835...?limit=20"
```

---

## Trending markets

**URL:** https://docs.scanna.xyz/docs/api/hot
**Description:** Ranked feed of the hottest markets by composite heat score.

`GET /hot`

Ranked trending markets feed. Returns the hottest markets by composite heat
score. See [Response Format](/docs/api/response-format) for the shared fields.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-50 | 10 | Number of markets to return |
| `category` | string | — | Filter by tag (e.g. "crypto", "politics") |
| `min_volume` | number | 0 | Minimum 24h USD volume |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/hot?limit=10&min_volume=5000"
```

---

## Insider score

**URL:** https://docs.scanna.xyz/docs/api/insider-score
**Description:** Wallet insider-risk score (0–100) from 4 factors.

`GET /insider-score`

Requires a **Pro** or **Enterprise** key. See [Plans](/docs/plans).

Wallet insider risk score (0–100) from 4 factors: wallet age (0–25), position
size (0–25), win-rate anomaly (0–25), trading pattern (0–15). Risk levels:
high / medium / low.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `wallet` | string | Yes | Wallet address (e.g. `0x...`) |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/insider-score?wallet=0x66fbe4344c..."
```

---

## Introduction

**URL:** https://docs.scanna.xyz/docs/api/introduction
**Description:** The Scanna REST API — base URL, authentication, and what it covers.

The Scanna REST API is the core surface for prediction market intelligence. It
serves trending markets, ML predictions, smart money, cross-venue divergence,
analytics, and raw market data over HTTP — the same data that powers the
[MCP server](/docs/mcp/overview) and the [SDKs](/docs/sdks/typescript).

**Base URL:** `https://api.scanna.xyz`

Every endpoint requires an API key except `/health` — see
[Authentication](/docs/api/authentication).
[Get a key](https://api.scanna.xyz/get-api-key) (free, no card required).

```bash
curl -H "x-api-key: YOUR_KEY" "https://api.scanna.xyz/hot?limit=5"
```

## In this section

  
**Authentication**

    API key header precedence and error responses.
  
  
**Rate Limits**

    Per-key limits and 429 behavior.
  
  
**Signals**

    Trending markets, market heat, smart money, health, and metrics.
  
  
**Market Data**

    Markets, prices, books, trades, wallets, and leaderboards.
  
  
**Analytics**

    Risk score, arbitrage, signals, insider score, clusters (Pro).
  
  
**AI Predictions**

    Resolved and live ML predictions, plus model details (Pro).
  
  
**Cross-Venue Divergence**

    Price gaps for the same event across Polymarket and Kalshi.
  
  
**Training Data Export**

    Labeled, time-sliced features as CSV or JSON (Pro).
  
  
**Integration Examples**

    Drop-in Python, TypeScript, and LLM agent examples.

---

## Leaderboard

**URL:** https://docs.scanna.xyz/docs/api/leaderboard
**Description:** Top traders with win-rate enrichment.

`GET /leaderboard`

Top traders with win-rate enrichment. Proxies Polymarket Data API
`/v1/leaderboard`, cached 5 min.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-100 | 50 | Number of top traders |
| `order` | string | PNL | Sort key: `PNL` or `VOLUME` |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/leaderboard?limit=20&order=VOLUME"
```

---

## Live predict

**URL:** https://docs.scanna.xyz/docs/api/live-predict
**Description:** Independent probability estimate for active markets.

`GET /live-predict`

Requires a **Pro** or **Enterprise** key. See [Plans](/docs/plans).

Live prediction for **active** markets. Computes features from accumulated trade
data and returns an independent probability estimate that can diverge from the
market price.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `market_id` | string | — | **Required.** Polymarket condition_id |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/live-predict?market_id=0x306d10..."
```

The response includes computed features, market price, model prediction, and the
divergence between them.

The live model is trained on time-sliced snapshots of resolved markets. Use
[`/export?sliced=true`](/docs/api/training-data-export) to access the training
data.

---

## Get market by id

**URL:** https://docs.scanna.xyz/docs/api/market-detail
**Description:** Single market detail by condition id.

`GET /markets/{condition_id}`

Single market detail. Falls back to `market_resolutions` if the market has
closed and is no longer in the live cache.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `condition_id` | string | Yes | Polymarket conditionId or Kalshi market identifier (path param) |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/markets/0xfb1835..."
```

---

## List markets

**URL:** https://docs.scanna.xyz/docs/api/markets
**Description:** Paginated list of active prediction markets from Polymarket and Kalshi.

`GET /markets`

Paginated list of active prediction markets from Polymarket + Kalshi. Pure
cache-backed; updates every 60s. Forward-only keyset pagination on
`(volume24hr DESC, conditionId DESC)` — pass the returned `next_cursor` as
`?cursor=<token>` to fetch the next page.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-500 | 50 | Page size |
| `platform` | string | — | Filter by platform: `polymarket` or `kalshi` |
| `category` | string | — | Substring match against market tags (case-insensitive) |
| `min_volume` | integer | 0 | Minimum 24h USD volume |
| `cursor` | string | — | Opaque keyset cursor returned by the previous page |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/markets?limit=50&min_volume=5000"
```

---

## Metrics

**URL:** https://docs.scanna.xyz/docs/api/metrics
**Description:** System health metrics — cache, DB, model, and job status.

`GET /metrics`

System health metrics: cache stats, DB activity, model info, and background job
status. Returns JSON.

```bash
curl -H "x-api-key: YOUR_KEY" https://api.scanna.xyz/metrics
```

---

## Model details

**URL:** https://docs.scanna.xyz/docs/api/model-details
**Description:** How the Scanna prediction model is built and validated.

The prediction model behind [`/predict`](/docs/api/predict) and
[`/live-predict`](/docs/api/live-predict).

| Property | Value |
| --- | --- |
| Algorithm | CatBoost gradient boosting |
| Features | 22 ML features: order flow imbalance (OFI), smart money tracking, VWAP, trade microstructure, wallet concentration |
| Training data | 2,799+ resolved markets (growing ~100–450/day) |
| Retrain schedule | Daily at 4am UTC (automated) |
| Validation | Walk-forward expanding window, no look-ahead bias |
| BSS (backtest) | +0.72 on 170K uncertain markets |

---

## Open interest

**URL:** https://docs.scanna.xyz/docs/api/open-interest
**Description:** Polymarket aggregate or per-market open interest.

`GET /open-interest`

Polymarket aggregate or per-market open interest. Proxies Polymarket Data API
`/oi` with 60s cache.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `market_id` | string | — | Omit for aggregate OI across Polymarket; set for per-market OI |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/open-interest"
```

---

## Order book

**URL:** https://docs.scanna.xyz/docs/api/orderbook
**Description:** Current order book features for a market.

`GET /orderbook/{condition_id}`

Current order book features. Top-100 markets by 24h volume are kept warm by the
order-book cache (5-min refresh). Long-tail markets return **404** — CLOB token
IDs for those need to be resolved via Gamma first (tracked as a follow-up).

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `condition_id` | string | Yes | Polymarket conditionId (path param). Top-100 by volume only. |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/orderbook/0xfb1835..."
```

---

## Predict

**URL:** https://docs.scanna.xyz/docs/api/predict
**Description:** ML prediction for a market from the resolved-market model.

`GET /predict`

Requires a **Pro** or **Enterprise** key. See [Plans](/docs/plans).

AI-powered prediction for any market. CatBoost model retrained daily on 2,799+
resolved markets. **Brier Skill Score +0.72** — beating market prices by 72% on
uncertain predictions.

**What is BSS?**

Brier Skill Score measures improvement over a baseline (market prices). **+0.72
means 72% less prediction error** than using market prices alone. Validated via
walk-forward backtest on 170,000 uncertain markets (price 0.2–0.8).

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `market_id` | string | Yes | Polymarket condition ID |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/predict?market_id=0xfb1835..."
```

```json
{
  "market_id": "0xfb1835...",
  "predicted_probability": 0.845,
  "confidence_interval": [0.72, 0.94],
  "model_source": "catboost_calibrated",
  "converged": true,
  "features_used": 22
}
```

Predictions require computed features, which are only available for resolved
markets. For active markets, use [Live predict](/docs/api/live-predict).

---

## Bulk prices

**URL:** https://docs.scanna.xyz/docs/api/prices
**Description:** Current YES/NO prices for up to 50 markets.

`GET /prices`

Bulk current YES/NO prices for up to 50 markets by condition_id.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `ids` | string | Yes | Comma-separated condition_ids, max 50 |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/prices?ids=0xfb1835...,0x306d10..."
```

---

## Rate Limits

**URL:** https://docs.scanna.xyz/docs/api/rate-limits
**Description:** Per-key request limits across all authenticated Scanna endpoints, and how 429 responses behave.

A single per-key cap applies across **all authenticated endpoints** — calls to
`/hot`, `/predict`, `/signals`, and everything else share one budget per minute
per key.

| Plan | Limit (global, per key) |
| --- | --- |
| Free | 10 requests / min |
| Pro | 60 requests / min |
| Enterprise | 300 requests / min |

`POST /heat` carries an additional, stricter per-route cap on top of the global
limit — it's the most compute-heavy endpoint. `GET /health` is public and
unmetered.

## Exceeding the limit

Exceeding the limit returns `429` with a `Retry-After` header indicating how
many seconds to wait before retrying:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

Back off for the indicated interval and retry. Need a higher ceiling? See
[Plans & Pricing](/docs/plans).

---

## Resolutions

**URL:** https://docs.scanna.xyz/docs/api/resolutions
**Description:** Recently resolved markets with their winning side.

`GET /resolutions`

Recently resolved markets with their `winning_side` outcome. Ordered by
`resolved_at DESC`.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-500 | 50 | Page size |
| `since` | string | — | ISO 8601 date or unix milliseconds — only resolutions on or after this point |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/resolutions?limit=20"
```

---

## Response Format

**URL:** https://docs.scanna.xyz/docs/api/response-format
**Description:** Common Scanna response fields and the whale_activity object returned by signal endpoints.

Signal endpoints like [`/hot`](/docs/api/hot) and `POST /heat` share
a common set of fields.

## Common fields

| Field | Type | Description |
| --- | --- | --- |
| `heat_score` | 0-1 | Composite score (higher = hotter) |
| `volume_spike_x` | number | Volume multiplier vs historical baseline |
| `hours_to_resolve` | number | Hours until market resolves |
| `liquidity_usd` | number | AMM pool liquidity in USD |
| `whale_activity` | object \| null | Large trades ($1K+) in last 4 hours |
| `flow_bias` | string | "buy", "sell", or "neutral" |
| `signals` | string[] | Human-readable signal descriptions |
| `volume_24h` | number | 24-hour USD volume |
| `price_yes` | number | YES outcome price (0-1) |

## whale_activity object

| Field | Type | Description |
| --- | --- | --- |
| `count` | number | Number of large trades |
| `total_notional` | number | Total USD value |
| `direction` | string | "buy", "sell", or "mixed" |

See the [Signal Engine](/docs/concepts/signal-engine) for how `heat_score` and
the human-readable `signals` are derived.

---

## Risk score

**URL:** https://docs.scanna.xyz/docs/api/risk-score
**Description:** Market risk grade A–F with a 6-factor breakdown.

`GET /risk-score`

Requires a **Pro** or **Enterprise** key. See [Plans](/docs/plans).

Market risk grade A–F with a 6-factor breakdown: resolution clarity (25%),
liquidity (20%), time risk (15%), volume quality / wash-trade detection (15%),
spread (15%), and category risk (10%).

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `market_id` | string | Yes | Polymarket conditionId |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/risk-score?market_id=0xfb1835..."
```

---

## Signals

**URL:** https://docs.scanna.xyz/docs/api/signals
**Description:** 6-factor signal engine with a bullish/bearish/neutral direction.

`GET /signals`

Requires a **Pro** or **Enterprise** key. See [Plans](/docs/plans).

6-factor signal engine: momentum (25%), volume (15%), whale (20%), smart money
(25%), order book (10%), technical / RSI (5%). Combines into a bullish /
bearish / neutral direction with per-signal confidence.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `market_id` | string | Yes | Polymarket conditionId |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/signals?market_id=0xfb1835..."
```

---

## Smart money leaderboard

**URL:** https://docs.scanna.xyz/docs/api/smart-money
**Description:** Top-performing wallets by win rate across resolved markets.

`GET /smart-money`

Smart money wallet leaderboard. Shows top-performing wallets by win rate across
resolved Polymarket markets. See [Smart Money](/docs/concepts/smart-money) for
how the leaderboard is built.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-100 | 20 | Number of wallets to return |
| `min_trades` | number | 10 | Minimum resolved trades |
| `min_win_rate` | number | 0.6 | Minimum win rate (0-1) |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/smart-money?limit=10"
```

```json
{
  "wallets": [{
    "address": "0x66fbe4344c...",
    "win_rate": 1.0,
    "trades": 26,
    "pnl": 27961,
    "total_notional": 25364,
    "last_seen": "2026-03-22T15:00:00Z"
  }],
  "total_tracked": 3053,
  "updated_at": "2026-03-23T..."
}
```

---

## Trades

**URL:** https://docs.scanna.xyz/docs/api/trades
**Description:** Recent trades for a market, with keyset pagination.

`GET /trades`

Recent trades for a market. Keyset pagination on composite
`(timestamp DESC, id DESC)` within `condition_id`. Pass the returned
`next_cursor` to advance; use `since` for forward-only consumers.

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `market_id` | string | — | **Required.** Polymarket conditionId to query trades for |
| `limit` | 1-500 | 100 | Page size |
| `cursor` | string | — | Opaque keyset cursor returned by the previous page |
| `since` | integer | — | Unix **seconds**. Only trades with `timestamp ≥ since`. Passing milliseconds will silently exclude every real row. |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/trades?market_id=0xfb1835...&limit=100"
```

---

## Export

**URL:** https://docs.scanna.xyz/docs/api/training-data-export
**Description:** Export historical, time-sliced market features and labels as CSV or JSON for model training.

The export endpoint requires **Pro** or **Enterprise**. See
[Plans & Pricing](/docs/plans).

## Export

`GET /export`

Labeled ML training data. Returns computed features for every resolved market,
ready for model training. Each row has 22 ML features plus outcome label and
metadata (28 columns total).

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | 1-10000 | 1000 | Number of rows to return |
| `min_trades` | number | 0 | Minimum trade count per market |
| `format` | string | json | "json" or "csv" |
| `category` | string | — | Filter by market type: crypto_short, crypto, sports, politics, weather, other |
| `condition_id` | string | — | Get features for a specific market |
| `price_min` | 0-1 | — | Minimum median_price_at_trade (filters out decided markets) |
| `price_max` | 0-1 | — | Maximum median_price_at_trade (filters out decided markets) |
| `sliced` | boolean | false | Return time-sliced training data (features at 25/50/75% lifecycle) for live model training |

```bash
# JSON format
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/export?limit=100&min_trades=5"

# CSV format (directly loadable by pandas)
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/export?format=csv&limit=1000" > training_data.csv
```

## Features per market

| Feature | Description |
| --- | --- |
| `volume_total` | Total USD volume |
| `volume_zscore` | Volume z-score vs all markets |
| `buy_ratio` | Buy volume / total volume |
| `whale_trade_count` | Trades ≥$1K notional |
| `whale_notional_ratio` | Whale volume / total volume |
| `smart_money_*` | Smart money participation, buy ratio, trade count (point-in-time) |
| `hours_to_resolve` | Duration from first trade to resolution |
| `unique_traders` | Distinct wallet count |
| `price_volatility` | Standard deviation of trade prices |
| `ofi_normalized` | Order flow imbalance [-1, 1] (buy pressure vs sell pressure) |
| `vwap` | Volume-weighted average price |
| `vwap_deviation` | Median price minus VWAP (late informed money signal) |
| `late_money_*` | Volume fraction and OFI of last 25% of trades |
| `price_momentum` | Last trade price minus first trade price |
| `price_autocorr` | Momentum continuation (+1) vs reversal (-1) |
| `wallet_hhi` | Wallet concentration index (0=dispersed, 1=dominated) |
| `winning_side` | Outcome label: "side_a" or "side_b" |

---

## Wallet positions

**URL:** https://docs.scanna.xyz/docs/api/wallet-positions
**Description:** A wallet's open positions with unrealized PnL.

`GET /wallet/{address}/positions`

Wallet open positions with unrealized PnL. Proxies Polymarket Data API
`/positions`, cached 30s.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | Yes | Polymarket proxy wallet address, case-insensitive (path param) |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/wallet/0x66fbe4344c.../positions"
```

---

## Wallet reputation

**URL:** https://docs.scanna.xyz/docs/api/wallet
**Description:** Win-rate, trade count, notional, and PnL for a wallet.

`GET /wallet/{address}`

Wallet reputation: win-rate, trade count, total notional, and PnL from our
`wallet_stats` table. Address is lowercased before lookup. Returns 404 when the
wallet is not tracked.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | Yes | Polymarket proxy wallet address, case-insensitive (path param) |

```bash
curl -H "x-api-key: YOUR_KEY" \
  "https://api.scanna.xyz/wallet/0x66fbe4344c..."
```

---

## Install

**URL:** https://docs.scanna.xyz/docs/mcp/install
**Description:** Connect the Scanna MCP server to Claude Code, Cursor, and other MCP clients.

The Scanna MCP server is hosted at `https://mcp.scanna.xyz/mcp` over streamable
HTTP. You'll need a Scanna API key —
[get one here](https://api.scanna.xyz/get-api-key?plan=pro).

## Claude Code

```bash
claude mcp add --transport http scanna https://mcp.scanna.xyz/mcp \
  --header "x-api-key=YOUR_SCANNA_API_KEY"
```

## Other MCP clients

Any client that supports a remote (streamable HTTP) MCP server can connect with
the URL and an `x-api-key` header. Exact config differs per client, but a
typical entry looks like:

```json
{
  "mcpServers": {
    "scanna": {
      "type": "http",
      "url": "https://mcp.scanna.xyz/mcp",
      "headers": { "x-api-key": "YOUR_SCANNA_API_KEY" }
    }
  }
}
```

Authentication reuses your Scanna API key — the same key from
[api.scanna.xyz/get-api-key](https://api.scanna.xyz/get-api-key).
`Authorization: Bearer <key>` is also accepted.

Once connected, your assistant can call the [Scanna tools](/docs/mcp/tools).

---

## MCP Overview

**URL:** https://docs.scanna.xyz/docs/mcp/overview
**Description:** The Scanna MCP server exposes prediction market intelligence as tools for AI agents and assistants.

The Scanna MCP server exposes Scanna's prediction-market intelligence as
[Model Context Protocol](https://modelcontextprotocol.io) tools, so AI
assistants and agents — Claude Code, Cursor, Windsurf, and others — can query
markets, signals, wallets, and divergence directly, without leaving the chat or
copy-pasting from a dashboard.

It's hosted at **`https://mcp.scanna.xyz/mcp`** and wraps the same
[REST API](/docs/api/introduction), so it reuses your Scanna API key, rate limits,
and billing — no separate credentials.

Live (beta). Six tools are available — see [Tools](/docs/mcp/tools). Connect in
one command — see [Install](/docs/mcp/install).

## How it works

- **Transport** — remote, streamable HTTP (SSE). Nothing to run locally.
- **Auth** — your Scanna API key via the `x-api-key` header.
- **Backend** — proxies `api.scanna.xyz`, so the data, key, and limits are identical to the REST API.

---

## Tools

**URL:** https://docs.scanna.xyz/docs/mcp/tools
**Description:** The tools the Scanna MCP server exposes to AI agents.

The Scanna MCP server registers the following tools. Each maps to the
[REST API](/docs/api/introduction) and runs under your API key.

## get_markets

Browse and filter active prediction markets across Polymarket and Kalshi by
heat, liquidity, risk, and time-to-resolve.

## get_market_intel

Deep dive on a single market: ML predicted probability vs market price,
divergence, the signal stack, and a full feature snapshot.

## scan_divergence

Find markets where Scanna disagrees with consensus beyond a threshold, or where
cross-venue arbitrage exists.

## analyze_wallet

Wallet reputation: insider risk score (0–100), smart-money classification, win
rate, PnL, and entity-cluster membership.

## get_history

Time-series and backtest export — 22 ML feature columns plus the outcome label —
as JSON or CSV, with optional time-sliced features.

## find_convergence

Multi-venue probability comparison for a single event.

`find_convergence` is coming soon — it currently returns a "not yet shipped"
response while the underlying endpoint is finished.

---

## Python SDK

**URL:** https://docs.scanna.xyz/docs/sdks/python
**Description:** Python client for the Scanna API, with async, LangChain, and OpenAI function-calling helpers.

**Pre-release**

The `scanna` package is pre-release (0.1.x) and not yet published to PyPI. The
interface below is what ships; publishing is coming soon. Until then you can
build against the [REST API](/docs/api/introduction) directly.

A Python client for the [Scanna API](/docs/api/introduction) with sync and async
clients, plus LangChain and OpenAI function-calling integrations.

```bash
pip install scanna
```

```python
from scanna import ScannaClient

client = ScannaClient(api_key="sk_...")

# Trending markets
hot = client.get_hot(limit=5)
for m in hot.markets:
    print(f"{m.question}: heat={m.heat_score:.2f}")

# Mispricing signal
pred = client.get_live_predict(market_id="0x...")
print(f"Market: {pred.market_price}, Model: {pred.predicted_probability}, Divergence: {pred.divergence}")
```

## Async

```python
from scanna import AsyncScannaClient

async with AsyncScannaClient(api_key="sk_...") as client:
    hot = await client.get_hot(limit=5)
```

## LangChain

```bash
pip install scanna[langchain]
```

```python
from scanna.integrations.langchain import get_all_tools

tools = get_all_tools(api_key="sk_...")
# Use with any LangChain agent
```

## OpenAI function calling

Scanna ships OpenAI function-calling helpers so an assistant can call the API as
tools. Methods mirror the [REST API](/docs/api/introduction): `get_hot`,
`get_heat`, `get_signals`, `get_predict`, `get_live_predict`, `get_risk_score`,
`get_arbitrage`, `get_insider_score`, `get_clusters`, `get_smart_money`,
`get_divergence`, and `get_export`.

---

## TypeScript SDK

**URL:** https://docs.scanna.xyz/docs/sdks/typescript
**Description:** Typed TypeScript client for the Scanna API (@scanna/sdk).

**Pre-release**

`@scanna/sdk` is pre-release (0.1.x) and not yet published to npm. The interface
below is what ships; package publishing is coming soon. Until then you can build
against the [REST API](/docs/api/introduction) directly.

A zero-dependency TypeScript client for the [Scanna API](/docs/api/introduction),
with dual ESM + CJS output and full types.

```bash
npm install @scanna/sdk
```

```typescript

const scanna = new ScannaClient({ apiKey: 'sk_...' });

// Trending markets
const hot = await scanna.getHot({ limit: 5 });
for (const m of hot.markets) {
  console.log(`${m.question}: heat=${m.heat_score.toFixed(2)}`);
}

// Mispricing signal
const pred = await scanna.getLivePredict({ marketId: '0x...' });
console.log(`Market: ${pred.market_price}, Model: ${pred.predicted_probability}, Divergence: ${pred.divergence}`);
```

## Methods

| Method | Endpoint | Description |
| --- | --- | --- |
| `getHot()` | GET /hot | Trending markets by heat score |
| `getHeat()` | POST /heat | Single-market deep dive |
| `getSignals()` | GET /signals | 6-factor signal analysis |
| `getPredict()` | GET /predict | AI prediction (resolved model) |
| `getLivePredict()` | GET /live-predict | Live mispricing signal |
| `getRiskScore()` | GET /risk-score | Market risk grade (A–F) |
| `getArbitrage()` | GET /arbitrage | Arbitrage scanner |
| `getInsiderScore()` | GET /insider-score | Wallet insider risk (0–100) |
| `getClusters()` | GET /clusters | Wallet entity clustering |
| `getSmartMoney()` | GET /smart-money | Smart money leaderboard |
| `getDivergence()` | GET /divergence | Cross-venue price gaps |
| `getExport()` | GET /export | ML training data |
| `getHealth()` | GET /health | Health check |

## Error handling

```typescript

```

Errors are typed, so you can catch `AuthError`, `NotFoundError`, and
`RateLimitError` distinctly.

---

## Links

- [GitHub](https://github.com/scanna-xyz)
- [X](https://x.com/scanna_app)
- [Support](mailto:contact@scanna.xyz)