Docs — Bellwether

Overview

API Live — v2

Bellwether tracks every political prediction market on Polymarket and Kalshi. The API provides canonical tickers, volume-weighted prices, cross-platform matching, and manipulation resistance scores — updated continuously via live order book and trade data.

Open access. The API is currently public with no authentication required. Email [email protected] for questions or support. Academic and research use is free.

Base URL

https://api.bellwethermetrics.com/api

Response Format

All responses are JSON. Timestamps are ISO 8601. Prices are decimal probabilities (0.00 – 1.00). Volume is in contracts traded (not USD).

Quick Start

Fetch a market by its Bellwether event slug:

          cURL
          GET
        

curl https://api.bellwethermetrics.com/api/metrics/event/bwr-fitzgerald-win-pres-ie

Response

{
  "slug": "bwr-fitzgerald-win-pres-ie",
  "ticker": "BWR-FITZGERALD-WIN-PRES_IE-CERTIFIED-ANY-2025",
  "title": "Will Frances Fitzgerald win the Irish Presidential Election?",
  "category": "ELECTORAL",
  "country": "ie",
  "bellwether_price": 0.6234,
  "price_tier": 1,
  "price_label": "6h VWAP across platforms",
  "price_source": "6h_vwap",
  "robustness": {
    "cost_to_move_5c": 31400,
    "reportability": "caution",
    "raw_reportability": "caution",
    "weakest_platform": "kalshi"
  },
  "vwap_details": {
    "window_hours": 6,
    "trade_count": 47,
    "total_volume": 18420
  },
  "orderbook_midpoint": 0.62,
  "fetched_at": "2026-02-26T17:30:00.000Z"
}

Events

Events represent Bellwether's unified view of a market — potentially spanning both platforms. Each event has a slug and an optional canonical ticker.

GET /api/metrics/event/{slug} Get single event with live data

Returns live price, VWAP, robustness metrics, and reportability for an event resolved via the market index. Data is fetched from native Polymarket and Kalshi APIs in real time (cached for 30 seconds).

Parameter	Type	Description
slugrequired	string	Bellwether event slug. E.g. `bwr-fitzgerald-win-pres-ie`

Response fields

Field	Type	Description
bellwether_price	float	Volume-weighted price (VWAP). Null if insufficient trade data.
price_tier	int	Data quality tier: 1 (6h VWAP, 10+ trades), 2 (12-24h VWAP), 3 (stale or no data).
price_label	string	Human-readable description of the price source. E.g. `6h VWAP across platforms`.
price_source	string	Machine-readable source: `6h_vwap`, `12h_vwap`, `24h_vwap`, `stale_vwap`, or `no_data`.
robustness	object	Contains `cost_to_move_5c`, `cost_to_move_up_5c`, `cost_to_move_down_5c`, `reportability`, `raw_reportability`, and `weakest_platform`.
vwap_details	object	Contains `window_hours`, `trade_count`, and `total_volume`.
orderbook_midpoint	float	Best bid/ask midpoint from current order book.
orderbook_summary	object	Contains `bid_levels`, `ask_levels`, `best_bid`, `best_ask`, `top_5_bids`, `top_5_asks`. For cross-platform markets, each entry includes a `platform` field (`"polymarket"` or `"kalshi"`).
fetched_at	datetime	When upstream data was last fetched. Cached for 30 seconds.

Markets

GET /api/markets/{ticker} Get market by BWR ticker

Returns live price, VWAP, robustness metrics, reportability, and platform availability for a market identified by its canonical Bellwether ticker. This is the primary way to look up a specific market.

Parameter	Type	Description
tickerrequired	string	Bellwether ticker. E.g. `BWR-DEM-WIN-SENATE_TX-CERTIFIED-ANY-2026`

Response fields

Field	Type	Description
ticker	string	Canonical BWR ticker.
slug	string	URL-friendly identifier.
title	string	Human-readable market title.
category	string	Political category. E.g. `ELECTORAL`.
country	string	ISO country code. E.g. `us`.
platforms	array	Platforms this market trades on: `["polymarket", "kalshi"]`.
volume_usd	float	Total trading volume in USD.
bellwether_price	float	Volume-weighted price (VWAP). Null if insufficient data.
price_tier	int	Data quality tier: 1, 2, or 3.
robustness	object	Contains `cost_to_move_5c`, `cost_to_move_up_5c`, `cost_to_move_down_5c`, `reportability`, `weakest_platform`.
orderbook_summary	object	Contains `bid_levels`, `ask_levels`, `best_bid`, `best_ask`, `top_5_bids`, `top_5_asks`. For cross-platform markets, entries include `platform`.
fetched_at	datetime	When upstream data was last fetched.

For direct access to platform-specific data. These endpoints fetch live order book and trade data from the native Polymarket CLOB and Kalshi Elections APIs.

GET /api/metrics/{platform}/{token_id} Platform market data

Returns tiered VWAP price, midpoint, order book depth, and reportability for a single platform market.

Parameter	Type	Description
platformrequired	string	`polymarket` or `kalshi`
token_idrequired	string	Polymarket token ID or Kalshi market ticker

Response fields

Field	Type	Description
bellwether_price	float	Tiered VWAP price. Null if insufficient trade data.
price_tier	int	Data quality tier: 1 (6h VWAP), 2 (12-24h VWAP), 3 (stale/no data).
price_label	string	Human-readable source label. E.g. `6h VWAP`.
price_source	string	Machine-readable source: `6h_vwap`, `12h_vwap`, `24h_vwap`, `stale_vwap`, or `no_data`.
robustness	object	Contains `cost_to_move_5c`, `cost_to_move_up_5c`, `cost_to_move_down_5c`, `reportability`, and `raw_reportability`.
vwap_details	object	Contains `window_hours`, `trade_count`, and `total_volume`.
orderbook_midpoint	float	Best bid/ask midpoint from current order book.
orderbook_summary	object	Contains `bid_levels`, `ask_levels`, `best_bid`, `best_ask`, `top_5_bids`, `top_5_asks`.
fetched_at	datetime	When upstream data was last fetched. Cached for 30 seconds.

GET /api/metrics/combined Cross-platform aggregation

Returns volume-weighted combined data for a matched pair. The combined VWAP is computed across trades from both platforms in the same time window.

Parameter	Type	Description
pm_tokenone required	string	Polymarket token ID
k_tickerone required	string	Kalshi market ticker

Provide at least one of pm_token or k_ticker. Provide both for cross-platform aggregation.

Response fields

Field	Type	Description
bellwether_price	float	Combined VWAP price across both platforms.
price_tier	int	Data quality tier: 1, 2, or 3.
robustness	object	Contains `cost_to_move_5c`, `cost_to_move_up_5c`, `cost_to_move_down_5c`, `reportability`, `raw_reportability`, `weakest_platform`.
orderbook_midpoint	float	Best bid/ask midpoint from merged order book.
orderbook_summary	object	Contains `bid_levels`, `ask_levels`, `best_bid`, `best_ask`, `top_5_bids`, `top_5_asks`. Each entry includes a `platform` field (`"polymarket"` or `"kalshi"`).
fetched_at	datetime	When upstream data was last fetched.

Reportability

Every market is scored for manipulation resistance based on live order book depth. The cost_to_move_5c field (nested inside robustness) tells you how many dollars it would take to shift the market price by 5 cents — the core metric behind the reportability tiers.

Rating	Cost to Move 5¢	Guidance
Reportable	≥ $100,000	Safe to cite. Price reflects broad market consensus.
Caution	$10,000 – $99,999	Cite with context. Note liquidity level.
Fragile	< $10,000	Do not cite as consensus. Easily manipulated.

Tier 2 data (12-24h VWAP window) downgrades reportable to caution and caution to fragile. Tier 3 data (stale VWAP or no data) is always rated fragile regardless of depth.

Tickers

Bellwether assigns a canonical ticker to every market using an automated matching engine. Tickers follow the format:

Ticker format

BWR-AGENT-ACTION-TARGET-MECHANISM-THRESHOLD-TIMEFRAME

Examples:
BWR-DEM-CONTROL-HOUSE-CERTIFIED-ANY-2026           Party control
BWR-FITZGERALD-WIN-PRES_IE-CERTIFIED-ANY-2025     Election
BWR-FED-CUT-FFR-SPECIFIC_MEETING-5BPS-JAN2026    Monetary policy
BWR-TRUMP-PARDON-MAXWELL-SIGNED_INTO_LAW-ANY-2026 Executive action

Two markets on different platforms match if and only if their tickers are identical. Post-processing rules normalize equivalent resolution mechanisms (e.g. "projected" = "certified" for elections, "primary" = "certified" for nominations).

Component	Description	Examples
AGENT	The actor, party, or institution	DEM, GOP, FED, TRUMP, ZELENSKYY
ACTION	What the agent does	WIN, CONTROL, CUT, HIKE, PARDON, LEAVE
TARGET	What the action applies to	PRES, SEN_PA, GOV_CA, FFR, HOUSE
MECHANISM	How the event resolves	CERTIFIED, SPECIFIC_MEETING, ANY_MEANS
THRESHOLD	Numeric threshold or qualifier	ANY, 5BPS, 25BPS, GT_2.0PCT
TIMEFRAME	When the event occurs	2026, JAN2026, 2025_Q4, DEC2025

Embed a Market

Drop a live Bellwether market card into any article. Paste a ticker below to preview the embed and copy the iframe snippet for your CMS.

Example tickers

Click a ticker to preview it.

BWR-NEWSOM-WIN-DEM_NOMINATION-CERTIFIED-ANY-NOV2028 BWR-DEM-CONTROL-HOUSE-CERTIFIED-ANY-FEB2027

MCP Server

The Bellwether MCP server gives AI agents direct access to live prediction market data. Compatible with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client.

Published on npm and the official MCP registry.

Setup

Run directly with npx:

npx bellwether-mcp

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bellwether": {
      "command": "npx",
      "args": ["bellwether-mcp"]
    }
  }
}

Claude Code — add via the CLI:

claude mcp add bellwether -- npx bellwether-mcp

Tools

TOOL search_markets Search markets by keyword

Search active political prediction markets by topic or keyword. Returns matching markets with tickers, categories, volumes, and platform availability.

Parameter	Type	Description
queryrequired	string	Topic or keyword. E.g. `senate`, `federal reserve`
category	string	Filter by category. E.g. `ELECTORAL`, `MONETARY_POLICY`
limit	number	Max results. Default 10, max 50.

TOOL get_market Live price for a market

Get live VWAP price, data quality tier, reportability, and editorial guidance for a specific market.

Parameter	Type	Description
tickerrequired	string	Bellwether ticker. E.g. `BWR-DEM-CONTROL-HOUSE-CERTIFIED-ANY-2026`

TOOL get_top_markets Most active markets

Get the most actively traded prediction markets, optionally filtered by category.

Parameter	Type	Description
category	string	Filter by category
limit	number	Max results. Default 10, max 50.

TOOL get_platform_spread Cross-platform price comparison

Compare prices between Kalshi and Polymarket for cross-platform matched markets. Returns spread in cents and direction.

Parameter	Type	Description
tickerrequired	string	Bellwether ticker for a matched market (`is_matched: true`)

TOOL get_reportability Editorial safety check

Check whether a market is safe to cite in published content. Returns reportability tier, cost to move price 5 cents, and editorial guidance.

Parameter	Type	Description
tickerrequired	string	Bellwether ticker

Example Workflow

// Step 1: Find markets
search_markets("2026 midterms")

// Step 2: Get live price
get_market("BWR-DEM-CONTROL-HOUSE-CERTIFIED-ANY-2026")

// Step 3: Check if safe to cite
get_reportability("BWR-DEM-CONTROL-HOUSE-CERTIFIED-ANY-2026")

Data Glossary

Reference for the data fields used across Bellwether's market datasets.

political_markets_master.csv

One row per market outcome. All markets classified into 15 political categories.

Identifiers

Field	Type	Description
market_id	string	Unique identifier for the market (platform-specific)
platform	string	Source platform: "polymarket" or "kalshi"
pm_condition_id	string	Polymarket condition ID (for price lookups)
pm_token_id_yes	string	Polymarket YES token ID
bellwether_ticker	string	Canonical Bellwether ticker for cross-platform matching

Classification

Field	Type	Description
question	string	Full market question text
political_category	string	One of 15 categories (see Categories section)
volume_usd	float	Total trading volume in USD
is_matched	bool	True if matched with a market on the other platform

price_histories.csv

Daily price observations at multiple time horizons before resolution. One row per market per time horizon.

Field	Type	Description
market_id	string	Links to master table
days_before_event	int	Days before resolution (60, 30, 14, 7, 3, 1)
prediction_price	float	Market price (0-1), interpretable as probability
actual_outcome	float	Resolution outcome (1.0 = Yes, 0.0 = No)
brier_score	float	Brier score: (prediction - outcome)²

liquidity_metrics.csv

Order book snapshots and derived liquidity metrics per market.

Field	Type	Description
market_id	string	Links to master table
spread_mean	float	Mean bid-ask spread (absolute, 0-1)
spread_median	float	Median bid-ask spread
depth_mean	float	Mean total order book depth (contracts at best bid + ask)
bid_depth_mean	float	Mean depth on bid side
ask_depth_mean	float	Mean depth on ask side
depth_imbalance_mean	float	Mean order book imbalance: (bid - ask) / (bid + ask)
n_snapshots	int	Number of order book snapshots collected

Code	Label	Markets
ELECTORAL	Elections & Nominations	5,405
MONETARY_POLICY	Central Bank & Interest Rates	1,674
INTERNATIONAL	International Affairs	685
POLITICAL_SPEECH	Statements & Public Speech	669
MILITARY_SECURITY	Military & Security	492
APPOINTMENTS	Appointments & Nominations	437
TIMING_EVENTS	Timing & Scheduling	310
JUDICIAL	Courts & Legal	261
PARTY_POLITICS	Party Politics	243
GOVERNMENT_OPERATIONS	Government Operations	222
REGULATORY	Regulatory	112
LEGISLATIVE	Legislation & Policy	108
POLLING_APPROVAL	Polls & Approval Ratings	55
STATE_LOCAL	State & Local Government	30
CRISIS_EMERGENCY	Crisis & Emergency	23

Documentation

Overview

Base URL

Response Format

Quick Start

Events

Response fields

Markets

Response fields

Response fields

Response fields

Reportability

Tickers

Embed a Market

Example tickers

MCP Server

Setup

Tools

Example Workflow

Data Glossary

Categories