dflow-kalshi-market-data

DFlow Kalshi 市场数据

获取已知 Kalshi 市场（或一组市场）的数据——订单簿、交易、价格、蜡烛图、预测、游戏内实时数据——可以是快照、历史范围或实时流。

前置条件

• DFlow docs MCP（https://pond.dflow.net/mcp）——按照仓库 README 安装。本技能是操作指南；MCP 是参考文档。查询参数、分页、确切的载荷架构、WebSocket 快照与差异语义，以及各类别特有的 live_data.details 结构都在其中——不要凭空猜测。

接口

本技能中的所有数据端点都通过 Metadata API（https://pond.dflow.net/resources/metadata-api）调用——REST 用于快照和历史数据，WebSocket 用于实时流。可从任何地方调用：命令行中的 curl、Node/Python 脚本、cron 作业、后端，或为浏览器 UI 提供代理服务的 Next.js。

如果用户说“从我的终端运行”，不要使用 dflow CLI——它没有市场数据子命令。请编写一个针对 Metadata API 的简短 HTTP/WS 脚本。

先选择数据形式

三种意图对应三种形式。根据用户的说法进行匹配，然后选择端点：

• 快照（“现在”“当前”）→ REST，调用一次。
• 历史数据（“过去一小时”“T1 到 T2 之间”“最近 N 笔交易”）→ REST，使用时间／数量限制参数。
• 数据流（“实时”“发生时”“有……时提醒我”）→ WebSocket 订阅。

数据 → 端点对照表

对于下面的每个数据集，单行说明涵盖全部三种形式。字段级详情（确切参数、分页令牌、载荷架构）→ docs MCP。

订单簿

• 快照：GET /api/v1/orderbook/{ticker} 或 /api/v1/orderbook/by-mint/{mint}（包含 sequence）。
• 数据流：orderbook 通道（每次更新中的 yes_bids + no_bids 映射；数据流载荷中没有 sequence）。

交易 — 两个端点，范围有重叠但并不相同

• GET /api/v1/trades（以及 /trades/by-mint/{mint}）——完整的市场成交记录。所有在 Kalshi 订单簿上成交的交易都包含在内，其中也包括 DFlow 链上成交（这些交易同样会进入 Kalshi 的订单簿；参见 FAQ“链上交易会出现在 Kalshi 的交易 WebSocket 中吗？”）。这是“显示此市场的交易”的默认选项。对应的数据流：trades 通道。
• GET /api/v1/onchain-trades（以及 /onchain-trades/by-market/{ticker}、/onchain-trades/by-event/{eventTicker}）——仅 DFlow 链上成交，包含 /trades 不提供的链上专属字段：wallet、transactionSignature、id、inputAmount、outputAmount、createdAt。这是 /trades 中数据的子集，但每行包含更丰富的信息。没有 WS 数据流。
• 选择方式：完整成交记录 → /trades。按钱包筛选的活动动态、DFlow 执行分析、交易签名查询 → /onchain-trades。要实时检测特定用户订单的成交 → 直接解析程序事件（参见 /prediction-markets/onchain-trade-parsing）。

最优买卖报价

• 快照：直接从市场对象读取 yesBid / yesAsk / noBid / noAsk（GET /api/v1/market/{ticker}——单数形式）——无需单独的端点。
• 数据流：prices 通道。

蜡烛图（OHLCV）

• 市场级别：GET /api/v1/market/{ticker}/candlesticks 或 /api/v1/market/by-mint/{mint}/candlesticks。
• 事件级别：GET /api/v1/event/{ticker}/candlesticks。
• 每次请求最多 5,000 根蜡烛图（参见注意事项）。

预测百分位历史

• 事件级别：GET /api/v1/event/{seriesTicker}/{eventId}/forecast_percentile_history（以及 /api/v1/event/by-mint/{mint}/forecast_percentile_history）。某个事件在 Kalshi 上的历史预测分布。

实时数据（Kalshi 透传）

• GET /api/v1/live_data、/live_data/by-event/{ticker}、/live_data/by-mint/{mint}。
• 响应包含一个 details 对象，其字段取决于里程碑类型——足球（美式）、足球（英式）、网球、高尔夫、MMA、棒球、板球和赛车各有各自已知的字段集。在处理 details 前，请查看文档 MCP 中的 live-data-details。

流式传输生命周期

连接 → 订阅 → 处理 → 重连。每项用一句话说明：

• 连接：开发环境为 wss://dev-prediction-markets-api.dflow.net/api/v1/ws（无需身份验证）。生产环境为 wss://prediction-markets-api.dflow.net/api/v1/ws，需在 WS 升级请求头中携带 x-api-key。对应的 REST 地址为 https://dev-prediction-markets-api.dflow.net 和 https://prediction-markets-api.dflow.net。
• 订阅：发送 { type: "subscribe", channel: "prices" | "trades" | "orderbook", all: true | tickers: [...] }。每个频道分别维护自己的订阅状态。
• 处理：根据 channel 解析每条消息，异步处理——不要阻塞读取循环。
• 重连：断开连接后采用指数退避，并在重连后重新发送每个订阅。服务端不会记住你的订阅。

精确的消息架构（prices、trades、orderbook）、心跳/ping 行为，以及 orderbook 频道的增量与快照语义 → 请查看文档 MCP。

应该询问用户的内容（以及不应该询问的内容）

查询内容——明确时自行推断，不明确时确认：

1. 哪个市场——ticker 或结果 mint。
2. 哪个数据集——orderbook、trades（Kalshi 或链上）、prices、candles、forecasts 或实时数据。
3. 快照／历史／流——根据表述推断，有歧义时确认。
4. 历史范围／间隔——candles 的时间范围（startTs、endTs）和 periodInterval；trades 的 limit。

基础设施——始终询问，不要推断：

5. DFlow API 密钥。 以清晰、中性的方式询问：“你有 DFlow API 密钥吗？” 不要预设密钥存放在哪里——例如 “它在环境变量里吗？” 或 “DFLOW_API_KEY 已设置吗？” 这样的问法会引导用户使用他们并未要求的环境变量默认值。不要因为用户提到已配置 dflow CLI，就假设他们有密钥。明确告知用户有此选择；不要默默回退到环境变量或开发环境。一个密钥适用于所有 DFlow 服务——同一个 x-api-key 可访问 Trade API 和 Metadata API，以及 REST 和 WebSocket。如果有 → 使用生产主机（REST：https://prediction-markets-api.dflow.net，WS：wss://prediction-markets-api.dflow.net/api/v1/ws），并在每个请求（REST 和 WS 升级请求）中携带 x-api-key。如果没有 → 使用开发主机（https://dev-prediction-markets-api.dflow.net、wss://dev-prediction-markets-api.dflow.net/api/v1/ws），该环境有速率限制；请引导用户前往 https://pond.dflow.net/get-started/api-key 获取生产密钥。生成脚本时，在启动时记录最终使用的主机和密钥是否存在，以便用户确认自己使用的是哪条接入路径。

不要询问：

• RPC、钱包、签名——此技能仅提供只读公共数据。
• Settlement mint／滑点／费用——这些属于交易端问题；如果用户转而希望根据此处看到的信息下单，请移交给 dflow-kalshi-trading。

易忽略的要点（文档 MCP 不会主动告诉你）

• 两个交易端点，范围有所重叠。 /api/v1/trades 是完整的市场交易记录（Kalshi 链下订单流 加上 DFlow 链上成交 — DFlow 成交会进入 Kalshi 的订单簿）。/api/v1/onchain-trades 是 DFlow 链上交易的子集，并附带 wallet / transactionSignature / 输入输出金额等信息。用户说“显示这个市场上的交易”时，要用 /trades；说“显示这个钱包的 DFlow 活动”时，要用 /onchain-trades?wallet=...。
• 订单簿只返回买单档位（yes_bids、no_bids）。最佳 YES 卖价 是推导得出的：1 - max(no_bids keys)（价格为 p 的 NO 买单对应价格为 1-p 的 YES 卖单）。REST 和 WS 频道同理。
• 存在两种价格刻度。 订单簿和 prices 频道使用概率字符串（"0.4200"）。/trades 和 trades 频道使用 0–10000 的整数，并附带 yes_price_dollars / no_price_dollars 字符串。计算前先统一刻度。
• 每次请求最多 5,000 根 K 线，超过时会硬性返回 400。 如果范围 × 间隔会产生超过 5,000 根 K 线，端点会返回 400，且没有部分结果 — 这是 DFlow 转发的 Kalshi 上游限制。缩小范围、增大间隔，或自行分页。
• periodInterval 的单位是分钟，不是秒。 按照 Kalshi 的惯例：1 = 1 分钟 K 线，60 = 小时 K 线，1440 = 日线。误以为单位是秒，很容易超过 5,000 根 K 线的上限。
• live_data.details 是分类专属字段，并非通用字段。 字段会因里程碑类型而异。不要硬编码跨类别的字段访问；应根据 type 分支，并从 MCP 的 live-data-details 参考资料中提取对应类别的已知字段。
• WebSocket 的 all: true 会产生海量数据。 尤其是 prices 和 orderbook。除非监控确实需要覆盖整个市场，否则请使用 ticker 列表。
• WS 订阅在重新连接后不会保留。 每次重新连接后，都要重新发送断线前的所有 subscribe 消息。
• 维护时段内数据流可能会静默 — 周四凌晨 3:00–5:00（ET），Kalshi 会离线；预期 WS 流量稀疏或缺失，REST 字段也可能过时。
• CLI 中保存的密钥不会自动传入脚本的 HTTP 客户端。 dflow setup 保存的密钥供 dflow 二进制文件自身使用。脚本直接发起的 Metadata API 调用则另算 — 必须通过环境变量、.env 或标志参数传入密钥。虽然只需一个 DFlow 密钥，但在同一代码库中混用 CLI 调用和直接 HTTP/WS 调用时，需要在两个位置配置。

遇到不确定的情况

对于上述内容未涵盖的事项 — 完整参数列表、分页令牌、精确的 WS 消息格式（订单簿的快照与差异）、心跳频率、K 线间隔枚举值、特定类别的 live_data.details 字段、预测百分位数响应格式 — 请查询文档 MCP（search_d_flow、query_docs_filesystem_d_flow）。不要猜测。

相关技能

• dflow-kalshi-market-scanner — 在整个市场范围内查找符合条件的市场（使用这些基础功能，并将其组织成命名扫描）。
• dflow-kalshi-trading — 在此处关注的市场上提交买入 / 卖出 / 赎回订单。
• dflow-kalshi-portfolio — 查看用户自己的持仓和盈亏。