稻草财经 · 开发者接入指南

适用版本：2026-10-08 上线批次（MCP+OAuth / Webhook / RSS / Open API / 机器人）。 文档中所有标注「✅ 实测」的行为均在生产环境（daocaijing.com）验证过，含验证日期。 内容仅供研究参考，不构成投资建议。

0. 通道总览

开发者总门户：https://daocaijing.com/developers（含 Webhook 管理台） MCP 控制台：https://daocaijing.com/api/mcp/setup（令牌签发/撤销 + 配置生成）

1. MCP 接入（推荐）

1.1 方式一：OAuth 浏览器授权（零配置，✅ 实测 2026-10-08）

任何支持 MCP + OAuth 2.1 的客户端，只需添加远程服务器地址：

https://daocaijing.com/api/mcp

• Claude Code（命令行）： bash claude mcp add --transport http daocaijing https://daocaijing.com/api/mcp
• Cursor / Cherry Studio：MCP 设置 → 添加远程服务器 → 粘贴上述 URL
• Claude Desktop：设置 → 连接器 → 添加自定义连接器 → 粘贴 URL

流程：客户端首次调用收到 401 → 自动打开浏览器 → 登录稻草财经（已登录则直接显示账号）→ 点「授权」→ 自动跳回客户端 → 开始使用。访问令牌 1 小时有效、自动续期，用户无感。

✅ 实测记录：真实浏览器完整走通「未登录显示登录表单 → 登录态显示授权按钮 → 点授权 → 跳回 localhost 回调携带 code+state → PKCE 换令牌 → 调工具取真数据」全流程。

1.2 方式二：个人令牌（适合服务端脚本 / 不支持 OAuth 的客户端，✅ 实测）

1. 登录官网后打开 /api/mcp/setup，创建令牌（明文仅显示一次，前缀 dfm_，默认 365 天有效，每账号最多 5 把）
2. 调用时携带 Authorization: Bearer dfm_xxx（优先，不进 URL/日志）

curl 验证（✅ 实测）：

curl -s https://daocaijing.com/api/mcp \
  -H "Authorization: Bearer dfm_xxx" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

无法配置 Header 的客户端（如 Claude Desktop 自定义连接器）可用查询参数兜底：https://daocaijing.com/api/mcp?token=dfm_xxx。该方式令牌会进服务端访问日志（已做脱敏映射 token=REDACTED），介意请用 Header 方式。

管理：控制台可随时撤销，撤销即时生效（✅ 实测：撤销后原令牌下一次请求即 401）。

1.3 工具清单（26 个）

调用示例（✅ 实测返回）：

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"ask_ai","arguments":{"question":"贵州茅台当前值得关注吗","deep":true}}}

deep 模式返回结构化投研结论：结论与期限 / 一致预期与核心矛盾 / 证据要点（33 份卖方报告、目标价区间）/ 风险 / 反证与失效条件，附 confidence。

1.4 配额与会员（✅ 实测语义）

1.5 MCP 最佳实践（全部来自实测）

1. 客户端工具超时设 ≥120 秒：ask_ai quick 模式实测 10–30s，deep 实测 ~90s；数据工具秒级。
2. 引导用户带标的/周期提问：过宽的问题（实测「现在A股哪些方向值得留意」）会触发平台的先澄清机制，AI 反问关注周期与风险偏好——这是防跑偏设计。带标的的问题（「贵州茅台当前值得关注吗」）直接走完整研究链路。
3. deep 只在该用时用：需要多轮取数的个股研判用 deep:true；「今天复盘说了什么」这类事实查询用默认 quick，秒回。
4. 令牌即账号凭证：不要写进前端代码/开源仓库；泄露立即在控制台撤销重发（即时生效）。系统侧令牌只存 SHA-256 摘要，库泄露也无法复用。
5. ** 版权边界**：MCP 只提供自有内容与元数据——投行研报原文、聚合文章全文不在此通道（合作方 API 同红线）；速判卡不带 iFinD 数据。

2. Webhook 事件推送（✅ 生产实测：投递 + HMAC 验签通过）

平台事件（当前支持 news：快讯入库）实时 POST 到你注册的回调 URL。

2.1 接入步骤（JWT 登录态，可直接在 /developers 页操作）

# 创建订阅（✅ 实测）
curl -X POST https://daocaijing.com/api/account/webhooks \
  -H "Authorization: Bearer <网站JWT>" -H 'Content-Type: application/json' \
  -d '{"url":"https://你的服务/hook","events":["news"],"description":"我的自动化"}'
# 返回 { "id":"wh_...", "secret":"whsec_...", ... }  ← 密钥仅此一次显示

事件载荷（✅ 实测格式）：

{"id":"evt_…","type":"news","created_at":"2026-10-08T…",
 "data":{"id":"…","title":"…","content":"…","topic":"快讯","symbol":null,"created_at":"…"}}

2.2 验签（必须做，✅ 实测比对通过）

import hmac, hashlib
# header: X-DaoCaijing-Signature: t=1696745123,v1=ab3f…
sig = dict(kv.split("=", 1) for kv in header.split(","))
expect = hmac.new(whsec.encode(), f"{sig['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expect, sig["v1"])   # 不符 = 非稻草财经发出或被篡改

2.3 最佳实践

1. 接收端 8 秒内返回 2xx：投递超时 8s，超时/非 2xx 记为失败；先落库再异步处理。
2. 无自动重试（当前版本）：失败只累计不重发——接收端做幂等 + 用 /test 端点对账。
3. 连续失败 20 次自动停用：防打挂；恢复=删除重建。成功一次即清零失败计数。
4. 回调 URL 不能指向内网/环回（SSRF 防护，✅ 实测 http://10.0.0.1/ 被拒 400）。
5. 每账号最多 10 个订阅；测试用 POST /api/account/webhooks/{id}/test 发测试事件（✅ 实测）。

3. RSS 订阅（✅ 实测 200）

最佳实践：拉取间隔 ≥30 分钟；某源偶尔返回空 <channel/> 多为上游行情源临时降级（非鉴权问题），下个周期自然恢复。

4. Open API /api/v1（合作方）

• 鉴权：Header X-API-Key: dfk_…（联系稻草财经签发）；完整文档 /api/v1/docs
• 端点：复盘（今日/指定/历史）、个股速判卡、资讯流、研报流、定时聚合摘要（/api/v1/openclaw/digest）
• 限流配额只按成功（HTTP 200）计：失败/限流不耗次数
• 扣子(Coze) / Dify / GPTs 插件：直接导入 https://daocaijing.com/api/v1/openapi.json（✅ 实测 200，7 端点，ApiKey 安全方案）

5. 机器人（飞书/钉钉定时播报）

1. 机器人平台建自定义 Webhook 机器人
2. 签发一把 X-API-Key
3. cron 定时拉摘要 → 自己组织文案 → 推群：

curl -s "https://daocaijing.com/api/v1/openclaw/digest?hours=8" -H "X-API-Key: dfk_xxx"

（接口已就绪，与 /api/v1 同鉴权；推送脚本模板本会话未实测，按各机器人平台文档接入即可。要在群里 @问答，用 1.1 的 MCP 地址接进支持 MCP 的机器人框架。）

6. 排错速查（均为实测语义）

7. 最佳实践（✅ 工作流套路全部实测）

7.1 提问怎么问，答案质量差很多

• 带上标的和周期：「贵州茅台当前值得关注吗」直接触发完整研究链路（✅ 实测 deep 91s 出结构化结论）；而「现在A股哪些方向值得留意」会先反问你的周期与风险偏好（防跑偏设计，✅ 实测）——不是故障，补一句「短线，能承受 15% 回撤」即可继续。
• 事实查询用 quick，深度研判才用 deep：get_review_today 这类事实秒回；ask_ai quick 实测 28s、deep 实测 91s。deep 的价值是多轮取数+交叉验证，别拿它查「今天几号」。
• 让 AI 自己编排工具：ask_ai 内部会自动调行情/复盘/财报工具取真数再回答（实测回答内含当日成交量/涨跌幅硬数据）——不确定用哪个数据工具时，直接问 AI。

7.2 数据工具组合套路（推荐工作流，每步实测）

研究一个标的的标准动作：

1. universal_search q=公司名        → 定位标的代码/相关资讯/术语
2. get_stock_verdict symbol=代码    → 确定性证据面（信号灯+可信度，非 LLM 叙述）
3. search_stock_reports symbol=代码 → 近两年券商观点（评级分布：茅台实测 24买入/6增持/3持有）
4. search_minutes keyword=公司名    → 机构调研纪要原文（一线反馈）
5. get_kline symbol=代码            → 走势结构（日线/分时）
6. ask_ai question=综合以上 deep=true → 交叉验证后的结构化研判

盘面巡检的标准动作：

get_review_today（昨天到今天发生了什么）
→ get_limit_up_ladder + get_dragon_tiger（资金在炒什么：实测当日 69 只涨停/72 条龙虎榜）
→ get_theme_boards + get_market_calendar（题材主线 + 未来事件）
→ get_risk_radar（高位股风险预警）

7.3 配额规划：省着用贵的

• 数据工具便宜（60 次/分、体验期 300 次/天），把 ask_ai 留给真正需要综合判断的问题——非会员每天只有 10 次 AI 问答，数据工具查到的事实足够 AI 客户端自己总结。
• 客户端把工具超时设 ≥120s（deep 实测 91s，留余量）。

7.4 Webhook 可靠性三件事

1. 收到事件先落库再处理，8 秒内返回 2xx（超时=失败）；
2. 处理逻辑做幂等（按 evt.id 去重）——当前版本失败不自动重发；
3. 每天扫一眼 /developers 列表的 last_status / 失败计数；连续失败 20 次订阅会被自动熔断（✅ 实测语义），恢复=删除重建。

7.5 安全红线

• 令牌（dfm_）与网站密码同权：不进前端代码、不进开源仓库、不发给群聊；泄露立即控制台撤销（✅ 实测即时生效）。
• 优先 Header 方式带令牌；?token= 方式仅供无法配置 Header 的客户端（日志已脱敏但仍不建议长期用）。
• Webhook 验签必须做（指南 2.2 节代码），不验签 = 任何人可伪造事件喂给你的自动化系统。

8. 验证记录（2026-10-08，生产环境）