ClearMarket

ClearMarket

面向机构的预测市场数据参考层。它对 Polymarket 和 Kalshi 上的市场进行结构化、分类、评级和关联，让研究、风险和数据团队能像使用其他资产类别一样使用这些数据。

现已上线： clearmarket.fyi · REST api.clearmarket.fyi/v1 · MCP api.clearmarket.fyi/mcp · 每日动态源，见 /signals。开放且只读——无需密钥。

覆盖范围： Kalshi + Polymarket 上的全部实时市场（不包括尚未交易的占位市场；网站上的数量会在每次数据导入后更新）。每个市场都有一个结算清晰度等级（RCG A/B/C）和完整的来源溯源信息——当交易平台指定了结算来源时，会注明该来源；若未指定，则会对这一缺失进行分类和评级（这正是评级要揭示的问题）。两个平台上列出相同问题的市场会相互关联。价格每小时更新。

v0.2 · 2026 年 6 月

---

快速入门

无需密钥，无需注册——开放且只读。

# 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 客户端——Claude Desktop、Cursor、VS Code）：通过 https://api.clearmarket.fyi/mcp 使用可流式传输的 HTTP，提供六个只读工具（list_events、get_event、get_market、list_upcoming_catalysts、list_signals、get_signal）。get_market 接受 ClearMarket ID、交易平台原生 ID/代码或市场 URL（尽力解析——Kalshi URL 可解析；对于 Polymarket，请传入 conditionId）；对于包含大量市场的事件，get_event 可使用 detail=concise，获取精简的等级/价格视图。Agent 清单见 /AGENTS.md。一键安装：

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

……或者手动添加：

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

每个 URL 还提供对应的 .json、嵌入式 JSON-LD，以及 /llms.txt 中的条目——Agent 无需抓取 HTML。

---

等级能否预测结算风险？一项涵盖 7,166 份合约的回测

预测市场合约可能准确预测了事件，却仍会因细则而产生不同的结算结果。结算清晰度等级仅根据规则文本为每份 Kalshi 和 Polymarket 合约评估结算风险，且评估发生在市场结算之前。使用 Polymarket 公开的链上争议记录进行测试（数据截至 2026-07-23）：

等级	结算时遭到质疑	合约数	比率
A	3	2,587	0.12%
B	0	1,302	0.00%
C	52	3,277	1.59%

55 份存在争议的合约中，有 52 份在结算前被评为 C 级。 C 级合约遭到质疑的比率约为 A 级和 B 级合约总和的 20 倍（相对风险为 20.6x，95% CI 为 6.4x 至 65.8x）。按交易量四分位数分组后，这种差异依然存在（最高四分位：A+B 为 0.22%，C 为 4.94%），因此该等级并非市场规模的替代指标。所有三起针对 A 级合约的质疑均未获支持。预注册的争议定义、Wilson 区间、交易量控制及来源承诺分组详见 docs/BACKTEST.md；数据集已提交至 data/backtest/，所有数字均可通过一条命令复现，且无需 API 密钥：

python3 scripts/backtest_stats.py data/backtest/dispute-labels-2026-07-23.csv

---

问题

Polymarket 和 Kalshi 发布的市场数据对零售交易很有用，但尚未做好直接用于机构研究或风险分析的准备。买方会立即遇到三个缺口：

1. 你无法判断结算数据来自何处。 按数量计算，约 65% 的 Polymarket 机构类别市场——按美元加权约为 80%——都没有承诺指定的结算来源（例如“一致认可的可信报道”这类占位措辞，或不具约束力的保留条款）。Kalshi 会列出来源，但有时表述比较宽泛（例如，S&P 500 合约中写着“例如 Google Finance”）。
2. 同一事件在不同平台上的定价方式不同。 Polymarket 将 2026 年 4 月的美联储利率决议列为 4 个方向性的 yes/no 问题；Kalshi 则列出 11 个利率区间。两个 API 都没有说明它们定价的是同一件事。
3. 相关市场没有归组，无论是在单一平台内还是跨平台。 Polymarket 上关于伊朗冲突何时结束的 9 个合约，在 API 中是 9 个独立条目，彼此毫无关联。跨平台的缺口更大。

机构若自行弥补这些缺口，最终得到的往往是无法推广的一次性解析方案。ClearMarket 提供标准化架构、增强管线，以及可供差异比对的机器可读样本。

---

前后对比

平台提供的数据

Polymarket 上关于 2026 年 4 月美联储利率决议的市场（4 个方向性市场之一）：

{
  "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 上关于同一美联储决议的市场（11 个执行价市场之一）：

{
  "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": "..."}]
}

resolutionSource 为空。规则埋在文字说明中。没有催化事件日历。也没有任何信息告诉你，这些是为同一次美联储会议定价的 15 个市场中的两个。

ClearMarket 提供的数据

{
  "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)."
}

两个单一平台事件——一个来自 Kalshi，一个来自 Polymarket——都已分级，都列入 FOMC 催化事件日历，并将美联储列为来源。匹配的问题通过共享的 question_id 跨平台关联；每个市场的 also_on 字段则显示另一平台上对应的市场及其实时价格。

完整记录见 samples/fed-apr-2026/specimen.json——这是在拆分为单一平台事件之前采集的旧版合并包样本；实时 API 现在将其作为两个通过 question_id 关联的单一平台事件提供。

---

内容

实时产品（网站、REST API、MCP、每日快讯）提供完整的实时市场范围。本仓库是其背后的开放架构 + 增强管线 + 参考样本：

• JSON Schema，用于 ClearMarket 的 4 张表（events、markets、marks、resolution_log）
• Postgres DDL，与这些架构相匹配
• 增强脚本（enhance.py），可将 Polymarket + Kalshi API 的原始数据提取结果转换为 ClearMarket 格式的记录，并使用 AI 起草编辑性增强内容
• 参考样本（15 个规范事件、55 个市场），可供差异比对——下方提供了示例
• CFTC ANPRM 评论（cftc-anprm/）——提交给委员会的跨平台结算分歧分析（RIN 3038-AF65）

所有样本均通过 JSON Schema 验证。所有记录都包含逐字段的 field_provenance 标记，指明某个值来自平台 API、ClearMarket 编辑内容、派生计算、估算代理值，还是已知的平台限制。

四个样本

样本	平台	事件	市场	演示内容
samples/iran/	Polymarket	9	9	主题系列（9 个相关问题，共享标签 iran-conflict）。采用 UMA 乐观预言机进行主观判定。开放市场提供完整的四方 CLOB 价格；已结算子市场提供 resolved_at 时间戳。
samples/fed-apr-2026/	Polymarket + Kalshi	1	15	旧版合并数据包（拆分为单一平台之前）：4 个由 UMA 判定的 Polymarket 方向性市场，以及 11 个由工作人员判定的 Kalshi 行权价市场，共用一个 event_id。当前实时 API 将其建模为两个通过 question_id 关联的单一平台事件。
samples/netanyahu/	Polymarket	4	4	带有截止日期变体的主题系列。与伊朗市场采用相同的主观 UMA 模式。
samples/sp500-2026/	Kalshi	1	27	行权价阶梯。27 个二元市场均以同一个收盘值为判定依据。将 Kalshi 宽泛的来源命名（“例如 Google Finance”）编辑完善为权威计算机构（S&P Dow Jones Indices）。
总计		15	55

打开任意 samples/<id>/specimen.json 查看完整数据包。顶层 _meta.editorial_review_notes 块列出了所有由 AI 起草的字段及其适用规则。

---

一句话说明切入点

ClearMarket 是这些数据源之上的独立增强层。它解析各平台未以结构化形式发布的内容：规范问题、权威数据源、已解析的判定结构、跨平台关联、主题系列，以及逐字段来源追踪。

同一套架构支撑两款产品（第三款已列入路线图）：

产品	功能	客户
CM Data（已上线）	参考层：对判定清晰度评级（RCG A/B/C）、命名判定来源、关联不同平台上的同一主张，并追踪逐字段来源。采用类似 Markit 的结构，可授权使用。	数据分销商（Bloomberg、ICE、Tradeweb、VettaFi）、研究与风险部门、AI Agent。
CM Signal（已上线）	基于 CM Data 的每日资讯流，提供新闻周期、成交量激增、跨平台分歧和基准漂移简报，并发布到网页、JSON 和 MCP。	跟踪预测市场隐含信号的分析师和部门。
Rate（路线图）	利用历史 UMA 模式量化争议风险。需要 UMA 子图读取器。	为尾部风险定价的互换部门，以及评估抵押品规模的中后台交易对手方。

---

架构

三个步骤。前两个由确定性 Python 实现；第三个是平台不会提供的编辑层。

 ┌────────────────────────────────────────────────────────────────┐
 │  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              │
 └────────────────────────────────────────────────────────────────┘

每次付费用户读取数据时都会访问缓存存储。读取时的大模型成本为零。

---

具体说明编辑层

逐条记录说明 AI 起草的内容与平台提供的内容有何不同：

Markets 表中由 AI 起草的字段：

• underlying_reference：用一句话指出现实世界中的数据来源
• resolution_source：仅当平台 API 返回空值时填写（仅限 Polymarket；Kalshi 的 settlement_sources 始终提供权威来源）

Events 表中由 AI 起草的字段：

• editorial_notes：2–3 句话的机构视角说明
• tags：4–6 个标签，涵盖主题、属性和实体
• question：必要时将平台原始文案改写为规范表述

其他所有内容要么是确定性转换（Python）、派生字段（在服务时计算）、平台 API 值，要么在平台未提供该字段时标记为 null_by_venue_limitation。

编辑层遵循的规则

• **Kalshi 的 resolution_source 和 source_citation 始终取自系列的 settlement_sources。**绝不采用 UMA 式的主观默认值。Kalshi 有结构化的结算元数据，应使用这些数据。
• **只有当 Polymarket API 返回的字段为空时，Polymarket 的 resolution_source 才使用编辑默认语句（“可信新闻报道，主观判断”）。**如果 Polymarket 的描述文本提到了特定 URL（例如，引用 federalreserve.gov 的 Fed 市场），则以平台提供的值为准。
• 指数和数据产品市场会规范为权威计算机构，而非平台的简称。“S&P 500”对应“S&P Dow Jones Indices”，而非“Google Finance”，无论 Kalshi 系列元数据中写的是什么。
• **所有生成的文本都以 close_at 或 resolve_at 作为权威日期的依据。**AI 不会根据对当前日期的推理来推断未来年份。

这些规则通过 enhance.py 中的系统提示词和各样本的配置强制执行，而不是寄希望于模型自行处理正确。

---

架构概览

共 4 张表。完整定义见 schema/。

表	作用	行数	主键	主要外键
events	规范化的可交易问题。编辑层。	每个规范化问题对应一行。	event_id（以 CM 为前缀的 12 字符稳定 ID）	primary_market_id → markets
markets	各平台的合约。原始平台数据 + 编辑补充数据。	每个平台上的每个市场对应一行。	market_id（BIGSERIAL）	event_id → events（可为空）
marks	每日价格快照。每个市场每个 UTC 日期对应一行。	基数较高。	mark_id	market_id → markets
resolution_log	仅追加的生命周期审计跟踪。	v0.1 中较精简；v0.3 通过 UMA 子图读取器扩展。	log_id	market_id → markets

值得注意的设计决策

• **采用带标签分组的扁平 events 结构，而非递归层级结构。**每个事件至少有 1 个市场。主题系列（伊朗冲突、Fed 决策）通过共享标签表示，而非父子层级。与 Bloomberg / Stripe 的惯例一致。使用者可通过 GET /events?tag=<name> 筛选系列。
• 结算机制与结算来源类型是分开的字段。arbitration_model 表示由谁仲裁（UMA 预言机、Kalshi 员工、平台自动处理等）。source_type 表示引用了哪类数据（央行、受监管的数据供应商、媒体共识、主观判断等）。此前这两者被混为一谈；拆分后便可筛选“由 UMA 结算、但使用具名央行来源”的市场（例如 Poly Fed 市场）。
• markets 上的 resolution_proposer 枚举记录 UMA 的 MOOV2 升级（2025 年 8 月，管理的 37 名提案者白名单），以区别于 Kalshi 的平台员工模式或无需许可的提案。
• **每行都有 field_provenance。**每个字段的标记有 5 个取值：platform_api、clearmarket_editorial、derived、imputed、null_by_venue_limitation。使用者可按字段粒度审计哪些字段是原始数据，哪些经过了补充。
• 派生字段在 API 提供数据时计算，而非存储。spread、mid、venues_covered、also_on、current_primary_mark 都会按需从规范化表中转换得出。

---

已发布内容（v0.2）

已上线

• 覆盖完整实时市场范围的公共网站、REST API 和 MCP 服务
• 每个市场都标注 Resolution Clarity Grade（RCG A/B/C）；若平台承诺提供具名结算来源，则同时显示该来源（未承诺的来源会分类说明，不会隐藏）
• 跨平台主张关联（Kalshi + Polymarket 上的同一分级主张）
• CM Signal 每日信息流（新闻周期、成交量激增、跨平台背离、基准漂移）
• 每小时刷新价格；输出 4 种格式（HTML + JSON-LD + 并行 JSON + llms.txt）

本仓库中

• 4 表架构（JSON Schema + Postgres DDL）
• 增强脚本（enhance.py），包含 CLOB + 大模型增强
• 参考样本：15 个 events、55 个 markets、55 个 marks
• 每条记录都有 field_provenance
• 确定性的规范事件 ID 和市场 ID

已知限制（如实说明）

• resolution_log 当前为空。 UMA 子图读取器将在 v0.3 中推出；Kalshi 生命周期事件需经编辑审核。宁可发布零条记录，也不发布少量记录来夸大功能。
• Polymarket 的 open_interest_usd 为 null。 需要链上子图；计划在 v0.2+ 实现。
• size 字段仅反映最优报价。 完整盘口深度需要专用爬虫；推迟至 v0.2。
• 完全移除了 liquidity 字段。 Kalshi 提供的是最优报价的 liquidity_dollars；Polymarket 提供的是完整盘口的 liquidityNum。两者不可比较。待为两者部署自有爬虫后再重新评估。
• 暂缓解析 resolution_triggers 中的规则文本。 目前会提供原始规则文本；接下来将由 LLM 解析结构化触发条件、阈值和排除项。

路线图

版本	发布内容	状态
v0.1	Schema + Enhancement Script + 参考样例	已于 2026 年 4 月发布
v0.2	在线网站 + REST API + MCP、RCG 评级、跨平台关联、CM Signal 数据流、每小时价格	已于 2026 年 6 月发布
v0.3	通过 UMA 子图读取器提供 resolution_log、为 docs/BACKTEST.md 提供第 2 级（推翻判决）争议标签、完整盘口深度、Polymarket 未平仓量	计划中

---

在本地运行 Enhancement Script

# 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/

脚本首次运行时会实时获取 Polymarket CLOB 订单簿（之后会在本地缓存）。对于已结算或已关闭的市场，会跳过 CLOB 获取。LLM 调用按输入哈希缓存；重新运行时会命中缓存，不产生费用。

运行 python3 enhance.py --no-llm 可跳过 LLM 增强，仅使用基于规则的编辑默认值，生成结构有效的样例。

---

仓库结构

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

---

致谢

本版本使用来自 Polymarket 和 Kalshi 的公开数据。编辑增强使用 Anthropic 的 Claude Haiku 4.5。Schema 设计借鉴了 Markit、Bloomberg Open Symbology（BSYM）和 Refinitiv PermID 的惯例。

---

状态

已上线。网站、REST API 和 MCP 服务已面向全部市场公开，CM Signal 数据流每日发布。欢迎通过 GitHub issues 或直接联系来反馈意见。

构建者： Jeremy Dietz。曾负责 Toronto Stock Exchange 的数字产品业务，曾任 Coinsquare（加拿大首家完全受监管的加密货币交易所）产品副总裁。他独立构建了 Catalyst Signal，这是一个覆盖 220 多家上市公司的 AI 研究平台。目前正在构建 ClearMarket。