Robinhood Crypto

robinhood-mcp

通过模型上下文协议提供的 Robinhood 官方加密货币交易 API 执行工具包。

Robinhood 的加密货币 API 只提供四种订单类型：market、limit、stop_loss 和 stop_limit，除此之外别无其他。它不支持括号订单、OCO、追踪止损、TWAP、冰山订单、分批建仓梯队、定期 DCA 或投资组合再平衡。这些才是人们真正想要的订单类型，而它们都有同一个要求：请求返回后，仍须有某种机制持续运行。仅在一次工具调用期间存在的追踪止损，并不是真正的追踪止损。本软件包合成了 Robinhood 缺少的 13 种订单类型，并将它们作为持久化后台任务运行，即使 Agent 断开连接、服务重启或机器重新启动，这些任务仍会继续运行。在此基础上，还提供了约 73 个工具，分布于 8 个可选模块：报价和持仓、FIFO 成本基础与已实现损益、交易日志、带有强制执行的紧急停止开关的风险限额，以及集成诊断。

这不是 Robinhood Chain，也不是 Robinhood 股票业务。它面向 trading.robinhood.com 上的经纪业务加密货币交易 API，相关文档见 docs.robinhood.com/crypto/trading。

---

签名工作台 — nirholas.github.io/robinhood-mcp

项目网站是一个交互式 Ed25519 签名工作台。你可以组装一个真实的 Robinhood 交易请求，并在自己的浏览器中生成真实签名——运算在客户端使用 Robinhood 发布的示例密钥完成，不会向任何地方发送数据——随后还可以看到它如何证伪 Robinhood 自己的文档：他们发布的测试向量验证依据是 Python dict 表示形式，而不是每个客户端实际发送的 JSON 正文。它是 docs/ 中的一个独立自包含页面，因此可以部署到任何静态托管平台。

只需单击一次即可部署自己的副本：

目标	方式
GitHub Pages	进入 Settings → Pages → Source：main / /docs。访问地址为 nirholas.github.io/robinhood-mcp/。无需构建步骤。
Cloudflare Pages	点击上方按钮，或运行 wrangler pages deploy docs。配置见 wrangler.toml。
Google Cloud	运行 gcloud storage cp -r docs/* gs://<bucket>/，并置于 HTTPS 负载均衡器之后；也可使用以 docs/ 为根目录的任意静态服务，在 Cloud Run 上部署。
Netlify / Vercel	点击上方按钮。发布目录为 docs/（netlify.toml、vercel.json）。

---

安全性

Robinhood 未提供沙盒。 没有模拟账户、没有测试环境，也没有试运行主机。此软件包可以下达的每笔订单都涉及真实经纪账户中的真实资金，而且无法预先演练。在设置 ROBINHOOD_CRYPTO_ENABLE_TRADING=1 之前，请先阅读本节。

以下每项防护都在代码中强制执行，由所有订单都会经过的单一 Executor 负责，绝不会只写在工具说明中。提示词中的指令只是建议；抛出的错误则不是。

防护措施	作用
独立二进制文件	robinhood-mcp 数据服务不会注册任何可进行交易的工具。将它连接到通用助手不会导致下单。
明确选择加入	除非设置了 ROBINHOOD_CRYPTO_ENABLE_TRADING=1，否则交易服务和守护进程都会拒绝启动。不会意外启动。
每笔订单的美元上限	每笔订单在提交前都会定价，超过 ROBINHOOD_CRYPTO_MAX_ORDER_USD（默认值为 $100）就会被拒绝。此机制会默认拒绝：如果无法预先确定美元价值，就会拒绝订单，而不是假定其价格低廉。
累计美元上限	达到 ROBINHOOD_CRYPTO_MAX_DAILY_USD 设定的进程累计金额后，将拒绝后续订单。
交易对允许列表	设置 ROBINHOOD_CRYPTO_SYMBOL_ALLOWLIST 后，只能交易其中列出的交易对。其他交易对一律拒绝。
仅买入	ROBINHOOD_CRYPTO_BUY_ONLY=1 会拒绝所有卖出订单。
受控模式与自主模式	默认的 guarded 模式下，订单工具会返回其将要发送的确切请求以及价格估算，但在第二次调用携带 confirm: true 之前不会下单。ROBINHOOD_CRYPTO_AUTONOMOUS=1 会跳过此关卡，以运行无人值守策略。
紧急停止开关	risk_kill_switch_engage 会停止所有执行并暂停每个正在运行的作业。状态会持久化到磁盘，在每笔订单执行时读取且不会缓存，并在 Executor 内检查。

有两点值得明确说明，因为人们常常会误解。

自主模式移除的是人工，而不是上限。 每笔订单上限、累计上限、允许列表和仅买入标志在自主模式下仍然有效。无人值守的 Agent 恰恰最容易出现失控订单，也最不容易被发现。

紧急停止开关也约束守护进程。 它位于 Executor 旁，而非风险工具模块中，因为 robinhood-mcp-daemon 会构建自己的 Executor，且完全不加载工具模块。若停止机制由某个模块提供，系统中唯一的无人值守进程仍会继续下单。由于每笔订单都会从磁盘读取状态而非使用缓存，通过 MCP 会话触发开关，也能停止在开关出现之前就已运行的守护进程。此机制会默认拒绝：无法解析的记录会被视为已启用停止状态，因为在记录损坏时恢复交易，正是紧急停止开关要防止的故障。

有两项限制需要如实说明其局限。累计上限是按进程计算并保存在内存中的计数器，重启后会重置：它用于遏制失控循环，而非充当记账系统或硬性预算。并且，持久化作业的总支出完全没有上限。每笔订单的上限适用于作业下达的每笔订单，但每笔订单上限为 $100、包含 50 个切片的 TWAP 可以累计支出 $5,000。请谨慎设定作业规模，并在启动任何无人值守任务前检查 risk_status。

最后，请限制 API 密钥本身的权限。Robinhood 允许按凭证选择权限：如果只需要读取权限，就不要授予下单权限，这样无论什么软件持有该密钥，都无法交易。还可以使用 IP 允许列表，值得启用。

---

安装

需要 Node.js 22.5 或更高版本（持久化作业存储使用 node:sqlite）。

无需预先安装任何内容：MCP 客户端会使用 npx 启动服务。

1. 创建凭证

npx robinhood-keygen

此命令会在标准输出中以 JSON 格式打印一对新的 Ed25519 密钥，并在标准错误中输出说明。然后：

1. 在 robinhood.com/account/crypto 注册公钥。此页面仅适用于经典网页版，不适用于移动应用和新版网页界面。
2. Robinhood 会返回一个 API 密钥，即 ROBINHOOD_CRYPTO_API_KEY。
3. 将私钥保存为 ROBINHOOD_CRYPTO_PRIVATE_KEY。它是一个 base64 编码的 32 字节 Ed25519 种子，不是 64 字节的扩展密钥对，也不是 PKCS#8。某些 Ed25519 库会导出 seed‖publicKey；粘贴这种密钥会得到 64 字节，导致每个请求都失败。请像对待密码一样保管私钥：它可以授权交易，而此软件包不会在本地计算签名之外的任何地方存储或传输它。

如果你已在其他地方生成密钥对，可以使用 dev 模块中的 verify_keypair 检查私钥是否与注册的公钥匹配；此操作不会向任何地方发送任何内容。

2. 将服务添加到 MCP 客户端

此软件包提供两个二进制程序，特意将它们分开。

服务	二进制程序	功能
数据	robinhood-mcp	报价、持仓、账户、订单历史、成本基础、盈亏。无法下单。
交易	robinhood-mcp-trading	包含以上所有功能，另外还支持真实订单、合成订单类型和风险控制。

只读。 建议从这个服务开始，并将其连接到通用助手。将以下内容粘贴到 claude_desktop_config.json（Claude Desktop）、.mcp.json（Claude Code）或客户端对应的配置文件中：

{
  "mcpServers": {
    "robinhood-crypto": {
      "command": "npx",
      "args": ["-y", "robinhood-mcp"],
      "env": {
        "ROBINHOOD_CRYPTO_API_KEY": "rh-api-...",
        "ROBINHOOD_CRYPTO_PRIVATE_KEY": "your-base64-seed"
      }
    }
  }
}

向助手提问：“我的 Robinhood 加密货币购买力是多少？BTC 当前的交易价格是多少？”

交易。 这是单独的配置项，因为它可以下真实订单：

{
  "mcpServers": {
    "robinhood-crypto-trading": {
      "command": "npx",
      "args": ["-y", "robinhood-mcp-trading"],
      "env": {
        "ROBINHOOD_CRYPTO_API_KEY": "rh-api-...",
        "ROBINHOOD_CRYPTO_PRIVATE_KEY": "your-base64-seed",
        "ROBINHOOD_CRYPTO_ENABLE_TRADING": "1",
        "ROBINHOOD_CRYPTO_MAX_ORDER_USD": "50",
        "ROBINHOOD_CRYPTO_MAX_DAILY_USD": "500",
        "ROBINHOOD_CRYPTO_SYMBOL_ALLOWLIST": "BTC-USD,ETH-USD"
      }
    }
  }
}

将限额设置为你能接受损失的数值。它们是防止误解指令造成真实成交的唯一屏障。

你可以同时运行两个配置项。数据服务可以永久连接；只有在准备交易时，才添加交易服务。

如果你尚未设置凭证

数据服务仍会启动。它不会直接退出（大多数 MCP 客户端只会显示一个含糊的“服务启动失败”），而是启动后仅提供一个 get_setup_status 工具，用于报告缺少哪些内容以及如何解决。如果你只看到这一个工具，说明尚未配置凭证：设置 ROBINHOOD_CRYPTO_API_KEY 和 ROBINHOOD_CRYPTO_PRIVATE_KEY，然后重启服务，即可使用完整的工具集。

交易服务的启动限制更严格：没有 ROBINHOOD_CRYPTO_ENABLE_TRADING=1 时，它会拒绝启动，因此绝不会被意外启动。

---

模块

这个工具包规模庞大，任何一个 Agent 都不应该一次性接触所有内容。每个工具都会占用上下文，并增加一个容易选错的选项，从而明显降低工具选择的准确性，因此各项能力以由操作者启用的模块形式提供，通过 ROBINHOOD_MCP_MODULES 配置。只有选中的模块会被注册。

模块	功能	默认启用	是否下单
market	报价、持仓、账户详情、交易对、订单历史。	是	否
orders	四种原生订单类型分别作为独立工具提供，另有通用的 place_order 和 cancel_order。	是	是
algo	十三种合成订单类型，以持久化后台任务运行。	是	是
portfolio	FIFO 成本基础、已实现盈亏和税务批次、资产配置、滑点、波动率、基于风险的仓位规模。	是	否
risk	风险敞口、集中度、回撤、交易前检查，以及强制执行的紧急停止开关。	是	是
journal	成交记录、完整往返交易、胜率和利润因子、每日摘要、过期未成交订单、CSV 导出、对账。	否	否
ops	健康检查、时钟偏差、密钥验证、速率限制状态、API 版本、监管器和未结算意图状态。	否	否
dev	连接诊断、签名说明、密钥对生成和验证、客户端代码生成、环境检查。	否	否

risk 被归类为下单模块，因为启用紧急停止开关会暂停正在运行的任务。它本身不能提交订单。

选择方式：

• 未设置时，加载默认模块集（market、orders、algo、portfolio、risk），并排除服务器无法托管的模块。交易服务器上有 52 个工具，数据服务器上有 16 个工具。
• 逗号分隔的列表会精确加载列出的模块：ROBINHOOD_MCP_MODULES=market,orders,risk。
• **all**会加载所有模块：交易服务器上有 73 个工具。

未知模块名称会导致启动失败，而不是被静默忽略，因为拼写错误导致工具悄然消失，比服务器拒绝启动更糟。

加载所有模块会降低工具选择的准确性。 对于探索功能的开发者，all 很有用；但对于生产环境中的 Agent，这不是个好选择。请选择任务实际需要的模块。如果 Agent 声称某项功能无法实现，请让它调用 list_modules：该工具会列出启用缺失功能所需的确切 ROBINHOOD_MCP_MODULES 值，因此不会把已禁用的模块误认为工具包缺少该能力。

数据服务器拒绝加载具有变更能力的模块（orders、algo、risk）；如果收到此类请求，它会在启动时失败，因此操作者绝不会误以为自己已启用交易执行。

全部 73 个工具的完整参数参考：docs/tools.md。

---

十三种合成订单类型

这些订单类型都基于 Robinhood 的四种基本订单构建，由监管器持续推进其运行。每种订单类型都通过独立工具启动，并采用类型化模式，因此缺失或名称错误的参数会在模式校验阶段失败，而不是在任务内部才失败。

订单类型	工具	功能	关键参数
TWAP	algo_twap_start	在一段时间内将一笔大额订单拆分为间隔均匀的小单，使入场均价分布在整个时间窗口内，而不是一次性支付单笔价差。	total_quantity、slices、duration_minutes、可选的 limit_price 保护价
追踪止损	algo_trailing_stop_start	跟随市场设置止损价；止损价只会朝有利方向移动，不会回撤。当价格回撤超过追踪幅度时，退出全部仓位。	quantity、trail_percent / trail_amount 二选一、可选的 activation_price
括号单	algo_bracket_start	建立仓位并附加止盈单和止损单，两者会相互取消，避免交易只剩一个退出单。	entry_type、entry_price、take_profit_price、stop_loss_price
OCO	algo_oco_start	为现有仓位挂出止盈单和止损单，并取消未成交的那一单。	quantity、take_profit_price、stop_price、可选的 stop_limit_price
定投	algo_dca_start	按固定时间间隔，在指定次数内定额买入或卖出。	interval_hours、occurrences、quote_amount_per_buy / asset_quantity_per_buy 二选一、可选的 max_price
阶梯单	algo_ladder_start	在一定价格区间内挂出一系列限价单，以便随价格变动逐步建立或退出仓位。	total_quantity、levels、start_price、end_price、distribution
冰山单	algo_iceberg_start	以一小部分可见数量执行大额订单，每笔成交后补充下一笔，从而避免订单簿显示全部数量。	total_quantity、visible_quantity、max_duration_minutes、可选的 limit_price
追价单	algo_chase_start	挂出限价单，并在订单簿价格远离时重新挂单，以避免跨越价差成交。	quantity、max_chases、offset_bps、可选的 limit_price 上限
网格	algo_grid_start	在价格区间内于下方挂买单、上方挂卖单；每笔成交后，在相邻一档挂出方向相反的订单，从而在每次完整往返中赚取档位间距。	lower_price、upper_price、grid_levels、quantity_per_grid、可选的 max_cycles / max_duration_minutes / stop_price
动量	algo_momentum_start	当价格以设定幅度突破近期区间时入场；当价格回撤至已达到涨跌幅的设定比例时退出。	side、quantity、lookback_ticks、breakout_pct、exit_pct、max_duration_minutes
均值回归	algo_mean_reversion_start	当价格偏离近期均值达到设定的标准差数时进行反向交易，并在价格回归该均值时平仓。	quantity、lookback_ticks、entry_z、exit_z、side_mode、max_duration_minutes
逢低累积	algo_accumulate_start	仅在价格走弱时逐步买入，朝目标数量累积；当价格低于近期均价达到设定百分比且低于硬性上限时，买入一笔。	target_quantity、slice_quantity、max_price、buy_below_pct、lookback_ticks、max_duration_minutes
再平衡	algo_rebalance_start	调整持仓，使其达到目标权重：卖出超配资产、买入低配资产，并先卖后买。	targets、tolerance_bps、max_legs_per_tick、dry_run

每个工具的描述都会说明其自身的失败模式；不同策略的失败模式并不相同。带有 limit_price 的 TWAP 可能无法完成全部数量。OCO 在一条腿成交而另一条腿取消期间不可避免地存在风险敞口；如果两条腿都成交，则会报告为 failed，而非成功。冰山单达到 max_duration_minutes 后会取消正在执行的可见单，并以未足量完成状态结束。实际运行前，请先阅读工具描述；使用 algo_rebalance_start 时，可通过 dry_run 查看各笔订单，再决定是否发送。 **此 API 仅支持现货交易，因此以下四种算法受到限制。**无法借币，也无法开立空头仓位，因此这里的操作都不会做空：

• algo_mean_reversion_start 的 side_mode 设为 short_only 或 both 时，不会开立空头仓位。它会在价格极高时卖出现有持仓，并在价格回归时买回。除非账户已持有足以覆盖 quantity 的资产，否则启动时会拒绝这两种模式；每次建立空头仓位前，都会重新检查余额再提交订单。
• algo_momentum_start 的 side: "sell" 也是如此：它是卖出账户现有币种的动量退出操作，而不是做空。如果账户没有该持仓，init 会拒绝此任务。
• algo_grid_start 不会卖出尚未由自身买入操作买入的币种。max_cycles 和 max_duration_minutes 始终有值（默认值：100 个周期、7 天），因为网格策略若两者皆无，就永远不会终止。只有通过 stop_price 才会清算：它会取消未成交订单，并以市价卖出网格库存。
• algo_accumulate_start 会等待价格回落，而不像 algo_dca_start 那样按固定时间买入，因此如果在 max_duration_minutes 到期前没有出现符合条件的回落，可能无法达到目标。未达目标便结束的运行会报告为未达目标。

---

持久化任务

启动工具不会在调用过程中执行算法，而是写入一个持久化任务并返回；此后由监督进程负责执行。

   algo_twap_start ("TWAP 0.5 BTC over 2 hours")
        |
        v
    JobStore (SQLite)  <-->  Supervisor  -->  Strategy.advance()  -->  Executor
                              (tick loop)

这正是关键所在：**任务的生命周期长于对话。**即使 Agent 断开连接、MCP 服务重启或机器重启，任务也会继续存在。聊天窗口关闭后，它也会继续花费资金，因此每个启动工具都会对此作出说明，并且提供了 algo_cancel_job。

任务保存在 ~/.robinhood-mcp/jobs.db 的 SQLite 数据库中，可通过 ROBINHOOD_MCP_DB 覆盖。数据库位于主目录而非工作目录中，这样任务即使从其他文件夹启动也能继续存在，并且不会意外提交到代码仓库。紧急停止开关的状态也保存在同一文件中，因此开关与其停止的任务始终不会对哪个数据库具有权威性产生分歧。

无人值守执行

MCP 服务只有在客户端保持连接时才会运行，因此通过 MCP 启动的任务只会在对话存续期间推进。如需无人值守执行，请运行守护进程，它使用同一个任务数据库：

ROBINHOOD_CRYPTO_ENABLE_TRADING=1 \
ROBINHOOD_CRYPTO_MAX_ORDER_USD=50 \
npx robinhood-mcp-daemon

使用能够自动重启它的工具来运行：systemd、launchd、pm2 或容器。重启在设计上是安全的。凭据保留在本机；守护进程只与 Robinhood 通信。

如果有任务且状态看起来正常，但却没有任何进展，说明监督进程没有运行。ops_supervisor_status 可用于检查此故障，此类故障不会产生任何错误。没有运行的 TWAP 不是运行缓慢，而是已经停止。

崩溃安全

如果处理不当，就可能用真钱将真实订单重复成交。

朴素的设计是先提交订单，再记录订单。如果进程在这两步之间退出，Robinhood 上已经有了订单，但任务对此毫无记录；重启后，策略会再次执行该笔订单，导致用户成交两次。

因此，每个订单都要经过三阶段写入：

1. 预留。 生成 client_order_id，并在进行任何网络调用之前持久化意图记录。
2. 提交。 使用该确切 ID 发送 POST 请求，并禁用重试，因为重试结果不明确的写入可能导致重复成交。
3. 结算。 记录响应。

启动时，supervisor 会根据 client_order_id 对每条仍待处理的意图与 Robinhood 进行核对。找到表示订单在崩溃前已下单，因此会接管该订单，绝不会重新提交。确认未找到表示 Robinhood 从未收到该订单。如果查询本身未完成，意图就会保持待处理状态并再次尝试，因为绝不能把不确定的结果当作“未找到”：Robinhood 不提供 client_order_id 查询筛选条件，因此只能在订单历史中进行有界遍历；如果放弃一个实际订单仍有效的意图，就会用新 ID 重新下单，重复执行该笔订单。

任何崩溃后，ops_jobs_pending_intents 都会列出尚未结算的内容，而 journal_reconcile 会将完整的本地记录与 Robinhood 进行比较。不要手动重新提交这些订单：如果订单已存在，核对流程会接管该订单；而使用新 ID 手动重新提交，正是让原本预期的一次成交变成两次真实成交的原因。

---

配置

变量	必填	默认值	用途
ROBINHOOD_CRYPTO_API_KEY	是	无	注册公钥时由 Robinhood 签发的 API 密钥。
ROBINHOOD_CRYPTO_PRIVATE_KEY	是	无	Base64 编码的 32 字节 Ed25519 种子。不能是 64 字节扩展密钥，也不能是 PKCS#8。
ROBINHOOD_CRYPTO_API_VERSION	否	v1	v1 或 v2。v2 会添加费用等级数据。其他值会导致启动失败。
ROBINHOOD_CRYPTO_BASE_URL	否	https://trading.robinhood.com	覆盖 API 主机。没有可用于此配置的沙盒主机。
ROBINHOOD_MCP_MODULES	否	默认集合	以逗号分隔的模块名称，或 all。未知名称会导致启动失败。
ROBINHOOD_MCP_DB	否	~/.robinhood-mcp/jobs.db	持久化任务和熔断开关状态的存储位置。
ROBINHOOD_MCP_TICK_MS	否	5000	守护进程 supervisor 的轮询间隔，单位为毫秒。
ROBINHOOD_CRYPTO_ENABLE_TRADING	交易服务和守护进程	0	两者启动时都必须设置为 1。除此之外，没有其他设置可以启用交易。
ROBINHOOD_CRYPTO_AUTONOMOUS	否	0	设置为 1 时立即执行并忽略 confirm。支出上限仍然有效。
ROBINHOOD_CRYPTO_MAX_ORDER_USD	否	100	单笔订单的硬性上限。适用于所有模式。必须为正数。
ROBINHOOD_CRYPTO_MAX_DAILY_USD	否	未设置（无限额）	单进程累计上限。仅保存在内存中；重启后重置。
ROBINHOOD_CRYPTO_SYMBOL_ALLOWLIST	否	未设置（允许所有交易对）	以逗号分隔的交易对，例如 BTC-USD,ETH-USD。设置后，只能交易这些交易对。
ROBINHOOD_CRYPTO_BUY_ONLY	否	0	设置为 1 时拒绝所有卖单。

请参阅 .env.example，获取可直接复制粘贴的起始配置。check_environment（位于 dev 模块）会报告这些变量的设置情况及其当前作用，但不会打印任何密钥。risk_limits_export（位于 risk 模块）会导出所有已强制执行的限制及其对应的变量。

v1 与 v2

v2 增加了费率等级数据，但不能直接替换 v1。它的 holdings、orders 和下单端点需要 account_number 查询参数（此处会自动解析）；estimated_price 从 /marketdata/ 移至 /trading/；此外，v2 将订单状态报告为 pending，而 v1 报告为 partially_filled。基于一个版本编写的代码，可能会因上述任一差异而无法在另一个版本中运行。默认值为 v1；如果需要费率数据，请设置为 v2。ops_api_version 会在运行时说明这些差异。

---

示例

为交易定价，然后下单

在防护模式下，下单工具会先预览。一次典型的交易流程如下：

1. 使用 symbols: ["BTC-USD"] 调用 get_best_bid_ask，查看实时市场。
2. 使用 symbols: ["BTC-USD"] 调用 get_trading_pairs，确认数量增量，因为小数位过多的数量会被拒绝。
3. 调用 risk_check_order，在不下单的情况下，检查订单是否符合每项控制要求。它会返回简单的 true 或 false，并指出会导致订单被拒绝的控制项。
4. 使用 symbol: "BTC-USD"、limit_price: "60000.00"、quote_amount: "25.00" 调用 buy_limit。如果不设置 confirm，它会返回将要发送的确切请求和定价估算，但不会下单。
5. 使用相同参数并添加 confirm: true，再次调用 buy_limit。这时才会发送请求。
6. 使用返回的订单 ID 调用 get_order，确认成交情况。

第 3 步对于多订单计划最为重要：它会在模拟检查中失败，而不是等到实际花掉资金后才中途失败。

在两小时内逐步建仓，然后保护仓位

将建仓拆分开来，使其在整个时间窗口内以平均价格成交，而不是一次性承担一个点差：

• 使用 symbol: "BTC-USD"、side: "buy"、total_quantity: "0.05"、slices: 12、duration_minutes: 120 调用 algo_twap_start。

它会返回任务 ID 并立即结束。使用 algo_list_jobs 跟踪任务，或使用 algo_get_job 查看完整事件历史及其下达的每一笔订单。使用 algo_cancel_job 提前停止任务时，请记住，这只会停止后续订单，不会取消已挂出的订单：algo_get_job 会列出这些订单的 ID，以便调用 cancel_order。

成交后，使用 OCO 退出订单对保护仓位：

• 使用 symbol: "BTC-USD"、side: "sell"、quantity: "0.05"、take_profit_price: "72000.00"、stop_price: "58000.00" 调用 algo_oco_start。

这两个任务都会在对话结束后继续运行，因此如果希望在关闭聊天后它们仍继续执行，请运行 robinhood-mcp-daemon。

停止一切

如果发现异常，并且宁愿停止操作也不想查明原因：

• 使用 reason 调用 risk_kill_switch_engage。该调用一返回，所有订单都会被拒绝，所有正在运行的任务都会暂停；即使服务和守护进程都重启，暂停状态也会保留。
• 对于 Robinhood 上任何已挂出的订单，调用 cancel_order。紧急停止开关不会取消这些订单。
• 调用 risk_status 查看完整情况；问题不再存在时，使用 confirm: true 调用 risk_kill_switch_release。

---

库的使用

签名客户端无需 MCP 即可运行：

import { RobinhoodCryptoClient, loadCredentials } from 'robinhood-mcp';

const client = new RobinhoodCryptoClient(loadCredentials());
const quote = await client.get('/api/v1/crypto/marketdata/best_bid_ask/', {
  query: { symbol: ['BTC-USD'] },
});
console.log(quote);

响应会按 Robinhood 返回的原样提供。字段名不会重新映射：已发布的架构与社区客户端在某些方面并不一致，错误的映射会悄无声息地损坏数据，而透传方式即使在上游结构发生变化时也能保持正确。

---

身份验证，以及两件容易踩坑的事

每个请求都会携带 x-api-key、x-timestamp 和 x-signature，其中签名是对以下内容进行 Ed25519 分离式签名所得：

message = api_key + timestamp + path + method + body

各部分直接拼接，中间不加分隔符。以下三点很重要：

• 私钥是一个 32 字节的种子，不是 64 字节的扩展密钥对，也不是 PKCS#8。若干 Ed25519 库会导出 seed‖publicKey；粘贴后会得到 64 字节，导致请求失败。此包会根据名称检测这种情况。
• 时间戳使用 Unix 秒，且 30 秒后过期。Date.now() 返回的是毫秒；直接使用会导致每个请求都失败。请保持系统时钟同步；当 401 看起来像是密钥错误、但也可能是时钟偏差时，请使用 ops_clock_skew。
• **路径包含查询字符串和末尾的斜杠。**两者都会参与签名。只序列化一次请求正文，对这些确切字节签名，并发送这些确切字节：重新序列化会改变键的顺序或空白，从而生成格式正确但签名无效的请求。

签名被拒绝时，dev 模块中的 explain_signature 会显示参与签名的确切字节，以便与其他实现逐字节比较；diagnose_connection 则会运行所有检查，以区分导致 401 的常见原因。

Robinhood 发布的符合性测试向量有误

文档发布了一个演示示例，并邀请你用它来校验签名。**该测试向量与真实客户端发送的 JSON 正文并不对应。**它是通过对 Python dict 表示形式签名生成的：使用单引号、冒号后有空格，而且键的顺序与附带表格显示的不同：

{'client_order_id': '...', 'side': 'buy', 'symbol': 'BTC-USD', 'type': 'market', ...}

对实际的 JSON 正文签名——也就是所有正常工作的客户端和 Robinhood 自己的示例代码在运行时所做的事——不会复现文档中发布的签名。任何把该测试向量用作符合性检查的人，都会把正确的实现“修复”成有缺陷的实现。

这两点都已固定在 tests/signer.test.ts 中，确保这一特例有据可查。签名器采用可靠的方式进行验证：Robinhood 发布了示例密钥对的公钥和私钥，而此实现会根据其私钥派生出完全一致的公钥，再通过独立验证完成签名往返验证。

---

本项目不做什么

• **不支持股票或期权。**这是加密货币 API。Robinhood 在 agent.robinhood.com/mcp/trading 提供的 Agent 交易产品是独立的、仅支持股票的接口，采用自己的 OAuth 流程，本项目不对其进行封装。也没有添加股票或期权支持的计划。
• **不抓取私有 API。**一些社区服务会通过浏览器会话或未经身份验证的内部 API 操作 Robinhood。本包仅使用有文档说明、经过签名且受支持的 API。
• **没有沙盒，因为根本不存在沙盒。**没有可切换到的模拟交易模式，也无法从 Robinhood 之外添加这种模式。ROBINHOOD_CRYPTO_BASE_URL 可以覆盖主机，但没有可供指向的测试主机。上文的防护措施是替代方案，也是唯一可用的方案。
• **没有历史 K 线数据，也没有订单簿深度数据。**Robinhood 两者都不提供。因此，get_volatility 接受你提供的价格序列，而不是自行获取；estimate_slippage 仅对报价价差建模，这只是实际成本的下限，并非模拟结果。
• **没有跨平台视图。**所有衍生数值（成本基础、已实现盈亏、回撤、交易日志表现）都只根据 Robinhood 订单历史重新计算。存款、取款、从其他平台转入的资产、质押奖励和空投均不可见，受影响的工具会在各自的说明中注明这一点。
• 不内置 OpenAPI 规范。scripts/fetch-spec.mjs 会实时拉取规范，因为内置副本会在无人察觉的情况下过时。

---

开发

npm install
npm test          # unit and integration tests, no credentials or network
npm run typecheck
npm run build
npm run smoke     # launch both built servers over real stdio and list their tools
npm run test:live # hits the real API; requires credentials; read-only

npm test 不会访问网络：策略计算、策略执行和协调均使用内存中的真实 SQLite 存储进行测试，只有网络边界会被替换。npm run smoke 会执行真实 MCP 客户端进行的握手，从而发现单元测试无法捕获的问题：过期的 dist/、错误的二进制文件 shebang，或在注册时抛出异常的模块。实时测试套件需选择启用，且仅执行只读操作，不会下单。

设计原理、分层方式以及代码扩展位置：docs/architecture.md。

许可证

Apache-2.0。请参阅 LICENSE。

Star 历史

支持此项目

如果 robinhood-mcp 为你节省了时间，请在 GitHub 上为它点 Star。Star 能让其他开发者和 AI Agent 发现值得信赖的代码仓库，而且只需点击一下。

认识可能会用到它的人吗？发布到 X · 分享到 Bluesky · 分享到 LinkedIn · 提交到 Hacker News · 分享到 Reddit

也为 AI Agent 而构建

编码 Agent 和大模型工具可以直接读取此代码仓库：AGENTS.md、llms.txt、llms-full.txt。将 https://github.com/nirholas/robinhood-mcp 提供给 Agent，它就能获取所需的上下文。

同一作者的更多项目

• nirholas 的所有代码仓库：完整目录，按主题分类
• three.ws：面向拥有 Solana 钱包、技能市场和 x402 支付功能的 3D AI Agent 的平台
• 有问题或想法：提交 issue或发起讨论

贡献者