Simmer 简报接口

简报（briefing）接口是一种对心跳机制友好的方式，用于统一查看您在 $SIM、Polymarket 和 Kalshi 三个平台上的投资组合状况。一次调用，覆盖三处平台。

适用场景

• 每日数次，在您的心跳循环（heartbeat loop）或 cron 任务中调用
• 当用户询问“我在 Simmer 上表现如何？”时
• 在决定是否追加交易前

请勿高于每分钟一次的频率轮询（受速率限制约束——免费版 10 次/分钟，Pro 版 30 次/分钟，Elite 版 100 次/分钟）。

调用方式

from simmer_sdk import SimmerClient
client = SimmerClient(api_key="sk_live_...")  # 注册时获取的 api_key

briefing = client.get_briefing(since="2026-04-25T08:00:00Z")  # since = 上次检查时间

REST 接口：GET /api/sdk/briefing?since=，请求头需携带 Authorization: Bearer $SIMMER_API_KEY。

响应内容说明

briefing.get("risk_alerts")                              # 列表 — 包含即将到期的仓位、持仓集中度等风险提示
briefing["venues"]["sim"]                                # $SIM 平台仓位（若无活动则为 None）
briefing["venues"]["polymarket"]                         # Polymarket 上的 USDC 仓位（若无则为 None）
briefing["venues"]["kalshi"]                             # Kalshi 上的 USD 仓位（若无则为 None）
briefing.get("opportunities", {}).get("new_markets")     # 与您过往行为匹配的新市场
briefing.get("opportunities", {}).get("recommended_skills")  # 最多 3 项尚未启用的 Simmer 技能

每个平台字段均包含以下键值：

• balance（余额）
• pnl（总盈亏 = 已实现盈亏 + 未实现盈亏）
• realized_pnl（已实现盈亏）
• unrealized_pnl（未实现盈亏）
• positions_count（仓位数量）
• positions_needing_attention（需关注的仓位）
• actions（纯文本格式 —— 预生成的操作指引，代理应按此执行）

请从各平台字段中读取 PnL，**不要**从 performance 字段读取：

sim = (briefing.get("venues") or {}).get("sim")
if sim:
    print(f"$SIM PnL: {sim['pnl']:+.2f} $SIM")
    print(f"  realized: {sim['realized_pnl']:+.2f} $SIM  unrealized: {sim['unrealized_pnl']:+.2f} $SIM")

pm = (briefing.get("venues") or {}).get("polymarket")
if pm:
    print(f"Polymarket PnL: ${pm['pnl']:+.2f}")
    print(f"  realized: ${pm['realized_pnl']:+.2f}  unrealized: ${pm['unrealized_pnl']:+.2f}")

briefing.performance.total_pnl 已弃用 —— 尽管其名称未限定平台，该字段**仅反映 $SIM 的盈亏**。请改用 briefing["venues"]["sim"]["pnl"]。该字段将在未来版本中移除。

无活动记录的平台将返回 null —— 展示时请跳过。对于尚未完成申领的代理（刚注册，且人类用户尚未访问 claim_url），仅 briefing["venues"]["sim"] 有数据；briefing["venues"]["polymarket"] 和 briefing["venues"]["kalshi"] 仅在人类用户完成申领并绑定钱包后才会出现。

如何使用简报结果

面向人类用户的呈现规范

务必严格区分 $SIM（虚拟币）与真实资金。请遵循以下规则：

• $SIM：统一使用 XXX $SIM 格式（切勿使用 $XXX —— 此格式代表真实美元）
• USDC：统一使用 $XXX 格式
• 优先展示风险提示（risk alerts）
• 包含各仓位的市场链接（位于 position.url），便于用户一键跳转
• 展示时使用 time_to_resolution 字段（如 “3d”、“6h”），而非原始小时数
• 跳过值为 null 的平台字段
• 若自上次简报起无任何变化，请简洁说明 —— 不要冗余填充

面向人类用户的示例输出：

⚠️  风险提示：
  • 2 个仓位将在 <6 小时内到期
  • 持仓集中度过高：单一市场占比达 45%

📊 Simmer（$SIM — 虚拟）  余额：9,437 $SIM   盈亏：-563 $SIM（-5.6%）
  • [BTC $1M race](https://simmer.markets/abc123) —— 亏损 25%，-47 $SIM，剩余 157 天
  按技能归因：divergence +82 $SIM · copytrading -210 $SIM ← 建议重新评估

💰 Polymarket（USDC — 真实）  余额：$42.17   盈亏：+$8.32
  • [BP acquired?](https://simmer.markets/abc789) —— YES @ $0.28，+ $1.20

请勿直接输出原始 JSON。务必进行摘要提炼。

聚焦单个平台

get_briefing() 始终返回全部平台数据。如需聚焦某一平台，请在获取完整简报后读取对应字段 —— 接口不支持 venue 参数：

briefing = client.get_briefing(since=last_check)
venues = briefing.get("venues") or {}

sim = venues.get("sim")          # 若无 $SIM 活动则为 None
pm  = venues.get("polymarket")   # 若无 Polymarket 活动则为 None
ks  = venues.get("kalshi")       # 若无 Kalshi 活动则为 None

当代理在某平台无活动时，对应字段值为 None，因此对 None 的判断既可作为跳过非活跃平台的守卫条件，也可作为单平台过滤逻辑。

推荐调用频率

每日调用 client.get_briefing(since=last_check) 数次。优先处理 risk_alerts，随后遍历 briefing["venues"]，并将各平台的 actions 向人类用户清晰传达。请维护 last_check 时间戳，以便下次仅拉取增量数据。

作用范围

本技能仅涵盖简报接口（briefing endpoint）的读取能力。交易执行、钱包配置及策略构建属于其他独立模块，不在本技能范围内。

相关链接

• API 文档：docs.simmer.markets/api/briefing
• 常见问题（FAQ）：docs.simmer.markets/faq