Clearmarket MCP Server

ClearMarket

Institutional reference layer for prediction market data. Structures, classifies, grades, and links markets across Polymarket and Kalshi so research, risk, and data teams can use them like any other asset class.

Live now: clearmarket.fyi · REST api.clearmarket.fyi/v1 · MCP api.clearmarket.fyi/mcp · daily wire feed at /signals. Open and read-only — no key required.

Coverage: the live Kalshi + Polymarket universe (untraded placeholder slots excluded; counts on the site refresh with each ingest). Every market carries a Resolution Clarity Grade (RCG A/B/C) and full source provenance — the resolution source is named where the venue commits to one, and where it doesn't, that absence is classified and graded (that gap is the point). Markets listing the same question on both venues carry cross-venue links. Prices refresh hourly.

v0.2 · June 2026

---

Quickstart

No key, no signup — open and read-only.

# REST — search the graded universe
curl -s "https://api.clearmarket.fyi/v1/events?q=fed"

# one event, fully graded (markets + resolution provenance + cross-venue links)
curl -s "https://api.clearmarket.fyi/v1/events/kxfed-26jul"

# the daily CM Signal wire feed
curl -s "https://clearmarket.fyi/signals.json"

MCP (agent clients — Claude Desktop, Cursor, VS Code): streamable HTTP at https://api.clearmarket.fyi/mcp, six read-only tools (list_events, get_event, get_market, list_upcoming_catalysts, list_signals, get_signal). One-click install:

# Claude Code
claude mcp add --transport http clearmarket https://api.clearmarket.fyi/mcp

…or add it by hand:

// claude_desktop_config.json  /  ~/.cursor/mcp.json
{ "mcpServers": { "clearmarket": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.clearmarket.fyi/mcp"] } } }

Every URL also ships a parallel .json, embedded JSON-LD, and a row in /llms.txt — agents never have to scrape HTML.

---

The problem

Polymarket and Kalshi publish market data that is useful for retail trading but not ingestion-ready for institutional research or risk. Three gaps a buyer hits immediately:

1. You can't tell where the resolution data comes from. On ~65% of institutional-category Polymarket markets by count — ~80% dollar-weighted — the venue commits to no named resolution source (placeholder language like "a consensus of credible reporting", or non-binding hedges). Kalshi names sources but sometimes loosely ("for example, Google Finance" on S&P 500 contracts).
2. The same event is priced differently on each platform. Polymarket lists the Fed April 2026 rate decision as four directional yes/no questions; Kalshi lists eleven rate-level brackets. Nothing in either API tells you they are pricing the same thing.
3. Related markets aren't grouped, on a single platform or across them. Nine Polymarket contracts on when the Iran conflict ends sit in the API as nine separate items, with nothing connecting them. Cross-platform, the gap is wider still.

Institutions solving any of these gaps in-house end up with one-off parses that do not generalize. ClearMarket ships a normalized schema, an enrichment pipeline, and machine-readable specimens you can diff against.

---

Before and after

What the platforms give you

Polymarket on the April 2026 Fed rate decision (1 of 4 directional markets):

{
  "question": "Will the Fed decrease interest rates by 50+ bps after the April 2026 meeting?",
  "endDate": "2026-04-30T23:00:00Z",
  "resolutionSource": "",
  "volume": 1530000,
  "description": "This market will resolve 'Yes' if ... [rules embedded in prose]"
}

Kalshi on the same Fed decision (1 of 11 strike markets):

{
  "ticker": "KXFED-26APR-T3.25",
  "title": "Will the upper bound of the federal funds rate be above 3.25%...",
  "close_time": "2026-04-29T17:55:00Z",
  "rules_primary": "If the upper bound of the target federal funds rate... [prose]",
  "settlement_sources": [{"name": "Federal Reserve Board of Governors", "url": "..."}]
}

Empty resolutionSource. Rules buried in prose. No catalyst calendar. And nothing telling you these are two of fifteen markets pricing the same Fed meeting.

What ClearMarket gives you

{
  "event_id": "CM-EVT-KXFED26APR",
  "slug": "kxfed-2026-apr",
  "question": "What will the Fed announce at the April 2026 FOMC meeting?",
  "category": "macro",

  // events are single-venue; this is Kalshi's bundle of the decision
  "venues_covered": ["kalshi"],

  // shared labels for searching across the universe
  "tags": ["macro", "fed-rate-decisions", "fomc", "monetary-policy"],

  // real-world events that move the price
  "catalyst_dates": [
    {"date": "2026-04-29", "type": "fomc", "label": "FOMC meeting Day 1"},
    {"date": "2026-04-30", "type": "fomc", "label": "FOMC statement + press conference"}
  ],

  "markets": [
    {
      "market_id": "CM-MKT-KXFED26APR-T325",
      "question_id": "CMX-FED26APR-UB325",   // the venue-independent question
      "rcg": {"grade": "A"},
      "resolution": {"source": "Federal Reserve Board of Governors", "arbitration_model": "kalshi_staff"},
      // the same question priced on the other venue
      "also_on": [{"venue": "polymarket", "market_id": "CM-MKT-0xA1B2", "price": 0.62}]
    }
  ],

  "editorial_notes": "Kalshi prices this decision as eleven rate-level strike markets; Polymarket as four directional questions. They are separate single-venue events; ClearMarket links the matching questions across them by question_id (surfaced as also_on)."
}

Two single-venue events — one Kalshi, one Polymarket — each graded, each on the FOMC catalyst calendar, with the Federal Reserve named as the source. The matching questions are linked across venues by a shared question_id, and each market's also_on surfaces its twin on the other venue with a live price.

Full record at samples/fed-apr-2026/specimen.json — a legacy combined-bundle specimen captured before the single-venue split; the live API now serves these as two single-venue events linked by question_id.

---

What's here

The live product (site, REST API, MCP, daily wire feed) serves the full live universe. This repo is the open schema + enrichment pipeline + reference specimens behind it:

• JSON Schemas for the four ClearMarket tables (events, markets, marks, resolution_log)
• Postgres DDL matching the schemas
• An Enhancement Script (enhance.py) that transforms raw Polymarket + Kalshi API pulls into ClearMarket-shaped records, with AI-drafted editorial enrichment
• Reference specimens (15 canonical events, 55 markets) you can diff against — the worked examples below
• The CFTC ANPRM comment (cftc-anprm/) — the cross-venue resolution-divergence analysis filed with the Commission (RIN 3038-AF65)

All specimens validate against the JSON Schemas. All records carry per-field field_provenance flagging whether a value came from the platform API, ClearMarket editorial, a derived computation, an imputed proxy, or a known venue limitation.

---

The four specimens

Open any samples/<id>/specimen.json for the full bundle. The top-level _meta.editorial_review_notes block lists every AI-drafted field and the rules that govern them.

---

The wedge in one sentence

ClearMarket is the independent enrichment layer above those feeds. It parses what the platforms don't publish in structured form: canonical questions, authoritative data sources, parsed resolution structures, cross-platform linkage, thematic families, and per-field provenance.

Two products sit on top of the same schema (a third is on the roadmap):

---

Architecture

Three steps. The first two are deterministic Python; the third is the editorial layer that platforms do not ship.

 ┌────────────────────────────────────────────────────────────────┐
 │  1. INGESTION (plain HTTP, zero LLM cost)                      │
 │                                                                │
 │     • Polymarket Gamma API   → event + market metadata         │
 │     • Polymarket CLOB API    → 4-side order book               │
 │     • Kalshi Trade API       → markets + series metadata       │
 └────────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌────────────────────────────────────────────────────────────────┐
 │  2. DETERMINISTIC TRANSFORMS (Python, zero LLM cost)           │
 │                                                                │
 │     • Field mapping (Poly endDate → ClearMarket close_at)      │
 │     • Type coercion, status inference                          │
 │     • Derived fields: spread, mid, venues_covered,             │
 │       also_on, current_primary_mark                            │
 │     • field_provenance flags (platform_api vs. editorial)      │
 └────────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌────────────────────────────────────────────────────────────────┐
 │  3. EDITORIAL ENRICHMENT (LLM-based, cached)                   │
 │                                                                │
 │     Per market:                                                │
 │       • underlying_reference   ← named data source             │
 │                                                                │
 │     Per event:                                                 │
 │       • editorial_notes        ← institutional framing         │
 │       • tags                   ← thematic / attribute / entity │
 │       • question               ← canonical grammar rewrite     │
 │                                                                │
 │     Cached to .enhance-cache/llm/ by input hash.               │
 │     Re-runs cost $0 unless the input changes.                  │
 └────────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌────────────────────────────────────────────────────────────────┐
 │  4. STORAGE + API (LIVE)                                       │
 │                                                                │
 │     • Cloudflare D1 + Worker: api.clearmarket.fyi/v1/*         │
 │     • REST + MCP (/mcp) + parallel JSON / JSON-LD              │
 │     • Hourly price refresh; daily CM Signal wires              │
 └────────────────────────────────────────────────────────────────┘

Every paying consumer read hits cached storage. Zero LLM cost at read time.

---

The editorial layer, concretely

What AI drafts vs. what the platform ships, per record:

Markets table, AI-drafted fields:

• underlying_reference: a one-sentence identification of the real-world data source
• resolution_source: only when the platform API ships empty (Polymarket only; Kalshi is always authoritative via settlement_sources)

Events table, AI-drafted fields:

• editorial_notes: 2-3 sentence institutional framing
• tags: 4-6 tags mixing thematic, attribute, and entity
• question: canonical grammar rewrite of raw platform prose when needed

Everything else is either a deterministic transform (Python), a derived field (computed at serve time), a platform API value, or flagged with null_by_venue_limitation if the venue does not expose it.

Rules the editorial layer respects

• Kalshi resolution_source and source_citation are ALWAYS pulled from series settlement_sources. No UMA-style subjective default ever. Kalshi has structured settlement metadata; use it.
• Polymarket resolution_source uses editorial default language ("Credible news reporting, subjective") ONLY when the Polymarket API ships an empty field. Where Polymarket description prose names a specific URL (e.g., Fed markets citing federalreserve.gov), the platform-shipped value wins.
• Index and data-product markets are normalized to the authoritative calculator, not platform shorthand. "S&P 500" resolves to "S&P Dow Jones Indices," not "Google Finance," regardless of what Kalshi series metadata says.
• All generated prose anchors on close_at or resolve_at for the authoritative date. The AI does not infer future years from present-day reasoning.

These rules are enforced in enhance.py system prompts and the per-specimen configuration, not by hoping the model gets it right.

---

Schema overview

Four tables. Full definitions in schema/.

Design decisions worth noting

• Flat events with tag-based grouping, not recursive hierarchy. Every event has ≥1 market. Thematic families (Iran conflict, Fed decisions) are expressed via shared tags, not parent/child hierarchy. Matches Bloomberg / Stripe conventions. Consumers filter families with GET /events?tag=<name>.
• Resolution mechanism vs. resolution source type are separate fields. arbitration_model is who arbitrates (UMA oracle, Kalshi staff, platform auto, etc.). source_type is what data is cited (central bank, regulated data vendor, media consensus, subjective, etc.). Previously conflated; split makes it possible to filter for "UMA-resolved but with a named central-bank source" (e.g., Poly Fed markets).
• resolution_proposer enum on markets captures UMA's MOOV2 upgrade (August 2025, a managed whitelist of 37 proposers), distinct from Kalshi's platform-staff model or permissionless proposals.
• field_provenance on every row. Per-field flag with five values: platform_api, clearmarket_editorial, derived, imputed, null_by_venue_limitation. Lets a consumer audit which fields are raw vs. enriched at field granularity.
• Derived fields are computed at API serve time, not stored. spread, mid, venues_covered, also_on, current_primary_mark: all reshaped from the normalized tables on demand.

---

What's shipped (v0.2)

Live

• Public site, REST API, and MCP server over the full live universe
• Resolution Clarity Grade (RCG A/B/C) on every market + named resolution source wherever the venue commits to one (uncommitted sources are classified, not hidden)
• Cross-venue claim linking (the same graded claim across Kalshi + Polymarket)
• CM Signal daily wire feed (news-cycle, volume-spike, cross-venue divergence, benchmark-drift)
• Hourly price refresh; four-format output (HTML + JSON-LD + parallel JSON + llms.txt)

In this repo

• 4-table schema (JSON Schema + Postgres DDL)
• Enhancement Script (enhance.py) with CLOB + LLM enrichment
• Reference specimens: 15 events, 55 markets, 55 marks
• field_provenance on every record
• Deterministic canonical event + market IDs

Known limitations (called out honestly)

• resolution_log ships empty. UMA subgraph reader lands in v0.3; Kalshi lifecycle events are editorial-gated. Shipping zero rows beats shipping thin rows that oversell the capability.
• open_interest_usd is null for Polymarket. Requires on-chain subgraph; v0.2+.
• size fields are top-of-book only. Full-book depth requires a dedicated crawler; deferred to v0.2.
• liquidity field dropped entirely. Kalshi ships liquidity_dollars as top-of-book; Polymarket ships liquidityNum as full-book. They are not comparable. Revisit with an own-crawler for both.
• resolution_triggers parsing of rules prose is deferred. The raw rules text ships today; LLM-parsed structured triggers, thresholds, and exclusions are next.

Roadmap

---

Running the Enhancement Script locally

# 1. Clone the repo
git clone https://github.com/JDSource/clearmarket.git
cd clearmarket

# 2. Python 3.9+ with a few packages
pip install anthropic python-dotenv requests jsonschema

# 3. Add your Anthropic API key
cat > .env <<'EOF'
ANTHROPIC_API_KEY=sk-ant-api03-...your-key...
EOF

# 4. Point the script at a raw API pull directory
#    (sample raw pulls at raw/clearmarket-api-pulls-apr22/)

# 5. Run
python3 enhance.py

# Output lands in samples/<specimen_id>/specimen.json
# Each file validates against the 4 schemas in schema/

The script fetches Polymarket CLOB order books live on first run (cached locally thereafter). It skips CLOB fetches for resolved/closed markets. LLM calls are cached by input hash; re-runs hit cache and cost zero.

Run python3 enhance.py --no-llm to skip LLM enrichment and produce structurally valid specimens with rule-based editorial defaults only.

---

Repository layout

clearmarket/
├── README.md                           this file
├── web/                                Astro site (clearmarket.fyi): pages, components, wire content
├── api/                                Cloudflare Worker: REST /v1/* + MCP /mcp, D1 schema + seed
├── cftc-anprm/                         CFTC ANPRM comment + reproducible analysis (RIN 3038-AF65)
├── enhance.py                          Enhancement Script
├── schema/
│   ├── events.schema.json              JSON Schema
│   ├── markets.schema.json
│   ├── marks.schema.json
│   ├── resolution_log.schema.json
│   └── ddl.sql                         Postgres DDL
├── samples/
│   ├── iran/specimen.json              4-table bundle for Iran family
│   ├── fed-apr-2026/specimen.json      Cross-platform Fed decision
│   ├── netanyahu/specimen.json         Netanyahu tenure family
│   └── sp500-2026/specimen.json        S&P 500 yearly strike ladder
├── raw/
│   └── clearmarket-api-pulls-apr22/    Raw API dumps used to generate v0.1.0
├── .env                                (gitignored: API key)
├── .enhance-cache/                     (gitignored: LLM + CLOB cache)
└── .gitignore

---

Acknowledgments

This release uses public data from Polymarket and Kalshi. Editorial enrichment uses Claude Haiku 4.5 from Anthropic. Schema design draws on conventions from Markit, Bloomberg Open Symbology (BSYM), and Refinitiv PermID.

---

Status

Live. The site, REST API, and MCP server are public over the full universe, and CM Signal wires publish daily. Feedback welcome via GitHub issues or direct contact.

Built by: Jeremy Dietz. Ran Digital Products at the Toronto Stock Exchange. VP Product at Coinsquare, the first fully regulated crypto exchange in Canada. Independently built Catalyst Signal, an AI research platform covering 220+ public equities. Now building ClearMarket.