Arcus Agent Gateway

arcus-agent-gateway

Robinhood Chain（Arcus）在链上承载着 194 种代币化的美国股票，其公共 API 能回答大多数人不会想到的问题：究竟是谁持有 AAPL，某个钱包的股票投资组合是什么样的，以及今天巨鲸们买卖 NVDA 的动向。这个 MCP 服务将所有这些信息交给 AI Agent。它只读、无需密钥、不执行写入操作；每个工具都会向 api.robinhood.com/rhj 以及两个公共链上数据源发起 GET 请求，并通过缓存和速率限制，避免过于活跃的 Agent 不断轰击上游服务。

使用场景

询问谁持有 AAPL，即可获取主要持有者地址及其占总供应量的比例，并标明是合约还是钱包。其中一个持有者合约竟持有 35% 的 NVDA；这种集中度风险，行情页面永远不会显示。

wallet_holdings 会读取任意地址在全部 194 种股票中的持仓，并为有最新报价的持仓计算价值。transfer_history 会遍历近期的 ERC-20 转账，并支持使用 min_value 筛选；这样就能捕捉大额交易，而非零星小额交易。

这里的陷阱在于价格，因此我们提供了拆股安全的数据：每条报价都会同时包含原始值和经过乘数调整的值；对于待生效的拆股（NVDA 已排定于 2026-11 使用 4.0 倍乘数），还会附带警告和生效时间。扫描市场健康状况、停牌代币和 13 个行业的平均值，只需进行两次低成本调用。

包含真实输出的完整演示：examples/use-cases.md。

快速开始

Claude Code：

claude mcp add arcus -- uvx arcus-agent-gateway

通过 stdio 运行（本地 Agent 的默认方式）：

uvx arcus-agent-gateway

Claude Desktop / Cursor 的标准配置（claude_desktop_config.json / .cursor/mcp.json）：

{
  "mcpServers": {
    "arcus": {
      "command": "uvx",
      "args": ["arcus-agent-gateway"]
    }
  }
}

[mcp_servers.arcus]
command = "uvx"
args = ["arcus-agent-gateway"]

# 1) start the gateway (keep it running)
uvx arcus-agent-gateway --http --port 8902 &

# 2) register it (merges into ~/.zcode/cli/config.json; workspace .zcode/config.json works too)
python3 - <<'PY'
import json, os
p = os.path.expanduser("~/.zcode/cli/config.json")
os.makedirs(os.path.dirname(p), exist_ok=True)
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg.setdefault("mcp", {}).setdefault("servers", {})["arcus"] = {
    "type": "http", "url": "http://127.0.0.1:8902/mcp"}
json.dump(cfg, open(p, "w"), indent=2)
print("arcus MCP server registered:", p)
PY

# 3) copy the agent skill (tool guide + watchlist cron recipe)
git clone -q --depth 1 https://github.com/alekskram/arcus-agent-gateway /tmp/aag
cp -r /tmp/aag/.agents/skills/arcus-gateway ~/.zcode/skills/ && rm -rf /tmp/aag
echo "ZCode setup done, restart your session and call any arcus tool"

托管形式：在端口 8902 上使用可流式传输的 HTTP：

uvx arcus-agent-gateway --http               # 127.0.0.1:8902
curl http://127.0.0.1:8902/health            # -> {"ok": true, "service": "arcus-agent-gateway"}

工具

全部 13 个工具均为只读（标注为 readOnlyHint: true）。名称和参数 与 arcus_mcp/server.py 中注册的内容完全一致。

倍数逻辑（使用价格前请先阅读）

Robinhood Chain 代币带有一个倍数，即代币合约的公司行动调整系数（1.0 = 未调整）。拆分会改变它；例如，NVDA 的 2026-11 拆分会排入 pendingMultiplier: "4.0"。

• REST API 返回原始价格。 /prices/{symbol} 中的 bid/ask 以代币合约单位计价，未按倍数调整。
• 调整后的值由此服务计算，绝不取自上游：price_adjusted = round(price_raw × currentMultiplier, 6)。
• 原始值和调整后值始终同时提供。 每个报价都包含 bid_raw/ask_raw/spread_raw 以及 bid_adjusted/ask_adjusted/mid_adjusted，与 multiplier 块并列，绝不会只提供其中一组。
• 链上数量（代币余额、铸造/销毁量）原生以调整后（已乘倍数）的单位计量；REST 价格则不是。如果要比较两者，请使用 *_adjusted 字段。

示例（实时测试样例，2026-09-03）：

AAPL   currentMultiplier = 1.000566080061092436
       bid_raw   = 327.77   →  bid_adjusted = round(327.77 × 1.000566…, 6) = 327.955544
       ask_raw   = 327.78   →  ask_adjusted = 327.965550
       mid                      mid_adjusted = 327.960547

待处理拆分警告。 当 pendingMultiplier 已排入队列（非空）且与当前值不同时，token_detail() 会添加类似 pending split: 1→4.0 on 2026-11-06T00:00:00Z 的警告，而 quote() 的倍数块会公开 pending + effective_time。拆分生效后，原始价格会按比例跳变，而 *_adjusted 字段仍具有可比性；这也是始终要在倍数旁查看调整后值的另一个原因。

为什么需要网关，而不是直接使用原始 API？

api.robinhood.com/rhj + 公共 RPC 均开放，但每个直接访问它们的 Agent 都会重新遇到相同的陷阱：

API 限制与缓存

• 上游在不使用密钥时允许 60 req/s；此客户端会自行限制为**≤50 req/s**（请求间隔 20 ms，线程安全）。
• 暂时性故障（429/502/503/504、网络错误）最多重试 3 次，退避时间为 2s × (attempt+1)。
• 响应缓存（每个进程）：/assets 5 min、/prices/{symbol} 15 s、/corporate-actions 1 h。market_status() 和 sector_view() 仅根据缓存和资产计算；它们绝不会并行请求 194 个价格。

链上数据源与限制

v0.2 链上工具会从 REST API 之外读取两个无需密钥的公共数据源。两者均免费、受速率限制且部分功能受限。上述每个工具都会如实降级（按字段省略数据，并通过 warnings[] / error 字典报告），绝不会静默返回空结果。

• 公共 JSON-RPC（默认值为 robinhood-rpc.publicnode.com，可通过 ARCUS_RPC_URL 覆盖）：eth_call（例如 totalSupply()）可正常工作。 eth_getLogs 只能查询最新区块之后约 45–60 个区块的浮动窗口；更宽或更早的范围会返回 HTTP 403“Archive requests require a personal token”（后端为 Alchemy）。该窗口会逐分钟变化，因此 transfer_history() 会按窗口回溯，初始宽度为 48 个区块，每遇到一次 403 就依次缩小为 48→32→16→8 个区块，getLogs 请求最多约 14 次。eth_getLogs 日志对象会直接携带 blockTimestamp，因此无需逐块查询。
• 备用 RPC（robinhood.drpc.org，ARCUS_RPC_FALLBACK_URL）：不支持 eth_getLogs 和 eth_call（JSON-RPC 返回“method not available”）； 仅用于 eth_chainId / eth_blockNumber。
• Blockscout v2 浏览器（robinhoodchain.blockscout.com/api/v2， ARCUS_EXPLORER_URL）：每个请求都必须包含浏览器 User-Agent；自 2026 年 9 月起，还必须通过 Cloudflare 的TLS 指纹机器人管理检测，因此即使带有浏览器请求头，普通客户端也会收到 403。安装可选扩展后，网关会通过 curl_cffi Chrome 模拟，对每个 Cloudflare 403 重试一次： pip install "arcus-agent-gateway[browser]"。如果未安装该扩展，两个依赖浏览器的工具（holder_snapshot、wallet_holdings）会返回包含以下确切提示的 cloudflare 错误；其他功能仍可正常工作。 代币页面（holders_count、circulating_market_cap、total_supply）、一个持有者页面（最多 50 行，不会循环翻页）以及地址的 token-balances 均来自此处，缓存时间为 600 s。在普通钱包上，token-balances 的响应时间约为 0.5 s，但在大型合约地址上可能会卡住 40 s 以上；客户端会在 15 s 后以 explorer-timeout 类型如实报错。
• 链上活动 ≠ 交易。 区块链会记录地址之间的 Transfer、铸造和赎回事件；它不包含任何订单簿交易或价格信息。价格请使用 quote()/quotes() 查询，代币转移记录请使用 transfer_history() 查询。

原始价格免责声明

价格完全按照 Robinhood 返回的数据提供（RAW）；不会应用乘数进行调整，*_adjusted 字段是我们计算得出的数据，并非上游数据。所有数据仅供参考，不得用于交易决策；采取行动前，应先向官方来源核实。我们不保证数据的完整性、准确性或时效性。

可选的价格历史记录器

Robinhood Chain REST API 没有价格历史端点，只有当前报价。对于这 194 种代币化股票，这个记录器是唯一的历史数据来源。它是可选启用，默认禁用；除非你明确启用，否则不会记录任何数据。

工作方式。 默认每 5 分钟采集一次：通过同一个限速客户端获取每种 ACTIVE 可交易代币的报价（上限为 50 req/s；平均负载约为 0.65 req/s），为每个交易代码追加一行到 data/history/snapshots_YYYYMM.parquet（按月轮换），并维护每日 OHLCV 汇总文件 data/history/daily.parquet（以 mid_adjusted 计算开盘价／最高价／最低价／收盘价，volume = 当日累计 daily_volume 的最大值）。汇总任务会在 UTC 午夜后的首次采集中运行，处理前一天的数据，并且具备幂等性（重新处理某一天会覆盖原有数据，不会产生重复项）。

启用方法：

pip install "arcus-agent-gateway[recorder]"   # adds pyarrow (optional extra)
# systemd (recommended): units ship DISABLED - enabling is your decision
sudo cp deploy/arcus-recorder.* /etc/systemd/system/
sudo systemctl enable --now arcus-recorder.timer   # OnCalendar=*:0/5, Persistent
# or run one tick / a debug loop manually:
python -m arcus_mcp.recorder --once
python -m arcus_mcp.recorder --limit 5            # debug: first 5 symbols only
ARCUS_INTERVAL_SEC=60 python -m arcus_mcp.recorder  # custom interval loop
# (from a git checkout, `python scripts/recorder.py ...` still works -
#  it is a thin shim that delegates to arcus_mcp.recorder)

数据占用与轮换。 全部 194 种代币每 5 分钟采集一次，快照约占每天 2–3 MB，每日汇总约占 10 KB。快照按月轮换（snapshots_YYYYMM.parquet）；不再需要原始粒度数据时，可删除旧月份的数据。daily.parquet 是紧凑的长期存储文件。数据写入 ~/.local/state/arcus-agent-gateway/history/（可通过 ARCUS_GATEWAY_DATA 覆盖）。

读取数据： price_history 工具会从同一目录提供 daily 日线数据和 raw 快照。若缺少 pyarrow 或数据，该工具会返回可执行的错误提示，指引你安装 [recorder] extra，而不会静默返回空结果。

安全与隐私

• 无需密钥，只读。 不需要 API 密钥或身份验证，也不会写入数据。每个工具在 MCP 协议中都标注为 readOnlyHint: true / destructiveHint: false。
• 从设计上进行限速。 客户端针对公开 REST 接口限制为 50 req/s；公开 RPC 请求也使用同一限速器；Blockscout 调用会携带标准浏览器 User-Agent，并设置各自的超时时间。
• 不收集遥测数据，不记录你的提示词。 服务会在内存中缓存公开市场数据（只有启用可选记录器时才会写入 parquet 文件）；除了 API 读取请求本身，不会有任何数据离开你的设备。

套件中的项目

四个同系列的只读 MCP 网关，风格一致：无需密钥、带缓存、如实处理降级。

这四个项目都已发布在 glama.ai 和 PyPI 上；使用 uvx <name> 即可安装其中任意项目。

许可证

MIT，详见 LICENSE。与 Robinhood Markets, Inc. 无关联。