markets

市场编排

将 ESPN 实时赛程（NBA、NFL、MLB、NHL、WNBA、CFB、CBB）与 Kalshi 和 Polymarket 预测市场连接起来。编写查询前，请查阅 references/api-reference.md，了解支持的运动代码、命令参数和价格标准化格式。

快速开始

sports-skills markets get_todays_markets --sport=nba
sports-skills markets search_entity --query="Lakers" --sport=nba
sports-skills markets compare_odds --sport=nba --event_id=401234567
sports-skills markets compare_market_url --url=https://polymarket.com/event/nfl-sf-sea-2026-10-11
sports-skills markets get_sport_markets --sport=nfl
sports-skills markets get_sport_schedule --sport=nba
sports-skills markets normalize_price --price=0.65 --source=polymarket
sports-skills markets evaluate_market --sport=nba --event_id=401234567 --fee_per_contract=<verified fee>
sports-skills markets match_markets --sport=mlb --date=2026-06-06
sports-skills markets get_market_price --venue=kalshi --ticker=KXMENWORLDCUP-26-FR
sports-skills markets get_price_history --venue=kalshi --ticker=KXMENWORLDCUP-26-FR --interval=1d

Python SDK：

from sports_skills import markets

markets.get_todays_markets(sport="nba")
markets.search_entity(query="Lakers", sport="nba")
markets.compare_odds(sport="nba", event_id="401234567")
markets.compare_market_url(url="https://kalshi.com/markets/kxnflgame/sf-vs-sea/kxnflgame-26oct11sfsea")
markets.get_sport_markets(sport="nfl")
markets.get_sport_schedule(sport="nba", date="2025-02-26")
markets.normalize_price(price=0.65, source="polymarket")
markets.evaluate_market(sport="nba", event_id="401234567", fee_per_contract=fee)  # fee: verified (user-stated or documented venue fee)
markets.match_markets(sport="mlb", date="2026-06-06")
markets.get_market_price(venue="kalshi", ticker="KXMENWORLDCUP-26-FR", at_time="2026-05-01T12:00:00+00:00")
markets.get_price_history(venue="polymarket", token_id="<token_id>", interval="1h")

重要：执行任何查询前

重要：调用任何编排命令前，请确认：

• 对于需要了解运动信息的命令（get_todays_markets、compare_odds、get_sport_markets、evaluate_market），已提供 sport 代码。
• 在标准化前，已正确识别价格来源：espn = 美式赔率，polymarket/novig/gemini = 0-1 概率，kalshi = 0-100 整数。

重要说明

• 运动信息会传递下去。 --sport=nba 会自动映射到相应的 Polymarket 运动代码和 Kalshi 系列代码。
• 不同命令支持的交易平台有所不同。 在支持的情况下，get_todays_markets、search_entity 和 compare_odds 会包含 Kalshi、Polymarket、ProphetX、Novig 和 Gemini。Gemini 市场发现不接受运动代码，或接受 nba、wnba、nfl、cfb、mlb、nhl、epl、laliga、mls、ligamx、ufc、f1、golf。每日仪表板会针对受支持的 ESPN 记分牌运动项目（nba、wnba、nfl、cfb、mlb、nhl）包含 Gemini。在其他运动项目的结算等价性得到验证之前，Gemini 比较仅支持 NBA；这些运动项目不会将 Gemini 纳入 sources。不支持的运动项目在市场发现时会跳过 Gemini，不会发出请求。normalize_price 接受 gemini（0-1 概率）。get_sport_markets、match_markets 和 evaluate_market 仅使用 Kalshi 和 Polymarket；compare_market_url、get_market_price 和 get_price_history 不支持 Gemini。
• 按运动项目进行搜索。 Polymarket 使用 sport → series_id；Kalshi 会搜索该运动项目对应的所有系列（比赛胜负、让分、总分、未来赛果）。
• 价格会经过标准化。 所有价格都会转换为隐含概率，以便进行比较。
• 发现不等于验证。 原始市场列表（*_markets、get_sport_markets、search_entity）是搜索结果，并非已验证为与某场比赛合约等价。只有 compare_odds 的 side_prices（以及 evaluate_market）经过身份验证。

工作流

今日 NBA 仪表板

sports-skills markets get_todays_markets --sport=nba

返回每场比赛的 ESPN 信息、DraftKings 赔率，以及匹配的 Kalshi、Polymarket、ProphetX、Novig 和 Gemini（gemini_markets）市场。Gemini 仪表板市场发现覆盖 NBA、WNBA、NFL、CFB、MLB 和 NHL；但不会验证每条搜索结果是否与同一份合约对应。

查找特定比赛中的套利机会

1. 获取 ESPN 赛事 ID：get_sport_schedule --sport=nba
2. 比较赔率：compare_odds --sport=nba --event_id=<id>
3. 如果检测到套利，响应会包含资金分配比例和 ROI——这些数据根据参考价格（price_basis: "reference"）计算，因此交易前请在每个平台的订单簿中确认两边的价格。
4. sources 和 completeness 会说明哪些平台实际为这场比赛提供了价格；提供商错误会报告为 error，而不是“无市场”。
5. 如需直接比较价格，请读取 side_prices.home / side_prices.away：每项都列出符合本场完整比赛胜负盘条件的 quotes（包含 venue、implied_probability、price_basis: "reference"、execution_guaranteed: false），以及 lowest_reference（某一方没有报价时为 null；价格相同时保留列表中最靠前的平台）。最低参考价不是可执行报价，未扣除费用，也不构成投注建议。将比较结果标记为完整之前，请检查 warnings 和 completeness.complete。
6. 搜索的平台：Kalshi、Polymarket、ProphetX 和 Novig。只有在赛事日期匹配，且完整比赛的 MONEY 市场有双向订单簿时，Novig 才会计入。其价格为推导出的卖价（1 − 最优反向买价），取自缓存快照。仅目录中的市场、让分盘和分时段市场会显示在 novig_markets 中，但不会为任何一方提供价格。search_entity 和 get_todays_markets 也会包含一个 novig 部分，其中列出相同结果。
7. 仅在 NBA 中，Gemini 只有在以下条件全部满足时才会计入：同一联赛中恰好有一个有效的完整赛事胜负盘（moneyline/contest/full_contest），且其 startTime 与 ESPN 的开赛时刻相同；该市场恰好有两个有效、开放且非组合合约，合约双方与 ESPN 的参赛队伍一致，并且两边的买入 YES 价格都在 (0, 1) 范围内。其价格是缓存公开快照中的买入 YES 价格——这是参考价，不是可执行报价；交易量也不能说明流动性。子市场（让分盘、总分盘、特殊投注、分时段市场）、组合盘、三方市场、已关闭或已结算的合约、缺失或格式错误的价格、其他开赛时间以及重复候选项，都会被拒绝，并在 sources.gemini.detail 中说明原因；这些市场仍会显示在 gemini_markets 中。Gemini 出错时会报告为 error；部分扫描（后续页面加载失败或扫描被截断）会列在 sources.gemini.warnings 中。

比较粘贴的市场链接

compare_market_url

1. compare_market_url --url=<link>。支持的链接：https://polymarket.com/event/<event-slug>[/<market-slug>] 和 https://kalshi.com/markets/<series>/<slug>/<event-ticker>（允许使用 www.），适用于 NFL、NBA、MLB、NHL、WNBA、CFB、CBB 的单场比赛。
2. 不会获取该链接。主机名必须完全匹配。凭据、端口、片段、编码或异常路径段，以及未知查询键都会在任何调用前被拒绝（仅忽略 utm_* 和其他点击跟踪键）。
3. 平台 API 会解析出恰好一个开放的完整比赛双向胜负盘（Polymarket）或两个开放的比赛获胜合约（Kalshi）。已关闭、非胜负盘、三方或来源不明确的市场都会被拒绝；平台返回的结果若指向其他 slug/ticker，也会被拒绝。
4. 该来源日期前后各一天的 ESPN 记分牌必须恰好匹配一场比赛，且队伍和日期均通过验证。双赛或多场匹配都会被拒绝；记分牌查询失败会报告为失败，而不是“没有比赛”。
5. 返回未经修改的 compare_odds 载荷（side_prices、sources、warnings 等），并附带 source_market（平台、规范化后的 url、赛事/市场 ID、espn_event_id、in_downstream_search）。如果该来源合约不在比较所搜索的平台市场中，会给出警告，且不会臆造价格。
6. 这仅匹配同一场比赛的胜负盘。这不代表各平台的结算规则相同，也不保证能够执行交易。目前不接受 Novig、ProphetX 和 Gemini 链接，但在 compare_odds 搜索这些平台时，它们仍会出现在比较结果中。

完整下注评估

1. evaluate_market --sport=nba --event_id=<id> --outcome=0 --fee_per_contract=<dollars per $1 contract>
2. 验证该市场是所选一方在本场比赛中的全场胜负市场，然后读取订单簿中的卖价
3. 将卖价和费用传入 betting.evaluate_bet：去除水钱 → 优势 → 凯利
4. 返回公平概率、优势、预期收益、凯利比例和建议

如果未提供 fee_per_contract，则会报告卖价，但 evaluation 为 null——不会假定费用为零，也不会给出净值。若 ticker 或 token_id 指向另一支球队、另一个日期或衍生市场（上半场、让分），则会拒绝处理，而不会替换为其他市场。通过 CLI（--fee_per_contract=<dollars>）或 Python 封装器传入费用。费用必须是明确且经过验证的假设：由用户说明，或依据平台官方公布的费率表（请注明依据）。切勿默默假设费用为 0。如果无法核实费用，evaluation 将保持为 null。

同一场比赛在两个平台上的市场

1. match_markets --sport=mlb --date=2026-06-06
2. 每组匹配项都包含同一场比赛在 Kalshi 上的事件（含市场 ticker）和在 Polymarket 上的事件（含 moneyline token ID）——确定性地根据日期和球队代码关联，标题模糊匹配作为后备方式。
3. 将 kalshi.market_tickers[i] 和 polymarket.markets[i].token_ids[j] 直接传入 get_market_price，即可比较价格。

一段时间内的价格变动

1. get_market_price --venue=kalshi --ticker=<ticker> --at_time=2026-05-01，获取单个时间点的价格（yes/no 两方均为 0-1）。
2. get_price_history --venue=kalshi --ticker=<ticker> --interval=1d，获取完整序列——两个平台返回的结构均为 {timestamp, price}。

示例

示例 1：今日比赛及预测市场赔率 用户说：“今天有哪些 NBA 比赛？预测市场赔率是多少？” 操作：

1. 调用 get_todays_markets(sport="nba") 结果：统一仪表板，展示每场比赛的 ESPN 信息以及 Kalshi/Polymarket/ProphetX/Novig/Gemini 市场

示例 2：跨平台搜索球队 用户说：“帮我在 Kalshi 和 Polymarket 上找 Lakers 市场” 操作：

1. 调用 search_entity(query="Lakers", sport="nba") 结果：来自 Kalshi、Polymarket、ProphetX、Novig 和 Gemini 的 Lakers 搜索结果（仅用于发现，未经验证是否为同一合约）

示例 3：比较特定比赛的赔率 用户说：“比较这场 Celtics 比赛在 ESPN 和 Polymarket 上的赔率” 操作：

1. 从 get_sport_schedule(sport="nba") 获取 event_id
2. 调用 compare_odds(sport="nba", event_id="<id>") 结果：每一方的 side_prices（纳入的参考报价和 lowest_reference），以及基于参考价格进行的套利检查

示例 4：完整市场评估 用户说：“Chiefs 这场比赛有优势吗？” 操作：

1. 从 get_sport_schedule(sport="nfl") 获取 event_id
2. 确认已验证的费用（由用户提供或场所记录的费用），然后调用 evaluate_market(sport="nfl", event_id="<id>", fee_per_contract=<verified fee>) 结果：公平概率、优势百分比、EV、Kelly 比例和投注建议。若没有已验证的费用，则会报告可执行的卖价，并将 evaluation 设为 null。

示例 5：浏览某项运动的所有市场 用户说：“显示所有 NFL 预测市场” 操作：

1. 调用 get_sport_markets(sport="nfl") 结果：Kalshi 和 Polymarket 上所有开放的 NFL 市场

示例 6：价格换算 用户说：“把 65 美分的 Polymarket 价格换算成美式赔率” 操作：

1. 调用 normalize_price(price=0.65, source="polymarket") 结果：通用结构，包含隐含概率（0.65）、美式赔率（-185.7）和十进制赔率（1.54）

示例 7：跨平台配对比赛 用户说：“帮我找到 Kalshi 和 Polymarket 上的 Mets 比赛” 操作：

1. 调用 match_markets(sport="mlb", date="<game date>") 结果：已在不同平台配对的比赛——并列显示 Kalshi 市场代码和 Polymarket 独赢代币 ID

示例 8：历史价格 用户说：“一个月前 France 的世界杯价格是多少？” 操作：

1. 调用 get_market_price(venue="kalshi", ticker="KXMENWORLDCUP-26-FR", at_time="2026-05-03T12:00:00+00:00") 结果：该时刻的“是/否”价格（0-1）；使用 get_price_history 查看完整曲线

不存在的命令——绝不要调用

• get_odds — 不存在。使用 compare_odds 查看不同来源的赔率。
• search_markets — markets 模块中不存在。请改用 search_entity。
• get_schedule — 不存在。请改用 get_sport_schedule。

如果某个命令未列在 references/api-reference.md 或本文件的工作流中（例如 compare_market_url），则该命令不存在。

故障排除

错误：未返回某项运动的市场 原因：运动代码可能缺失或不正确 解决方案：查看 references/api-reference.md，确认有效的运动代码。请使用准确代码（例如 nba、epl、laliga）

错误：compare_odds 未返回某场比赛的数据 原因：event_id 不正确，或该比赛尚未编入索引 解决方案：先调用 get_sport_schedule(sport=...) 获取正确的 event_id

错误：响应中某个来源显示警告 原因：Kalshi 或 Polymarket 暂时不可用 解决方案：该模块会返回部分结果——请使用可用数据。可直接使用 kalshi 或 polymarket skill，单独重试不可用的来源

错误：normalize_price 返回了意外的美式赔率值 原因：source 参数错误——Kalshi 使用 0-100 的整数，Polymarket 使用 0-1 的小数 解决方案：核对来源。Kalshi 价格 65 需要设置 source="kalshi"；Polymarket 价格 0.65 需要设置 source="polymarket"