Arcus Agent Gateway

arcus-agent-gateway

Robinhood Chain（Arcus）では、194銘柄のトークン化された米国株式がオンチェーンで扱われています。その公開 API では、多くの人が思いもよらない質問にも答えられます。AAPL を実際に保有しているのは誰か、あるウォレットの株式ポートフォリオはどのようなものか、今日、クジラは NVDA をどちらに動かしたのか。この MCP サーバーを使えば、AI エージェントはそのすべてを利用できます。読み取り専用で、キーは不要、書き込みもありません。すべてのツールは api.robinhood.com/rhj と2つの公開オンチェーンソースに対する GET であり、熱心なエージェントが上流 API に過剰なリクエストを送らないよう、キャッシュとレート制限が適用されています。

ユースケース

AAPL の保有者を尋ねると、総供給量に占める割合と、コントラクトかウォレットかの区分が付いた上位保有者のアドレスが返されます。ある保有者コントラクトは NVDA の35％を保有しています。こうした集中リスクは、株価ページでは決して分かりません。

wallet_holdings は、194銘柄すべてを対象に任意のアドレスを読み取り、最新の株価を取得できたポジションの評価額を算出します。transfer_history は、min_value フィルターを使って最近の ERC-20 Transfer を追跡します。これにより、わずかな取引ではなく、大口取引を見つけられます。

ここで注意が必要なのが価格です。そのため、分割にも安全に対応できるよう、すべての株価に未調整の値と倍率調整後の値が併せて含まれます。また、予定されている株式分割（NVDA では2026-11に4.0の倍率が設定されています）には、警告と適用時刻が含まれます。市場の健全性、取引停止中のトークン、13セクターの平均を朝に確認するには、低コストの呼び出しを2回行うだけです。

実際の出力を含む詳しい手順については、examples/use-cases.md をご覧ください。

クイックスタート

Claude Code:

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

stdio で実行する場合（ローカルエージェント向けのデフォルト）：

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)。
• 未調整値と調整後の値は必ずセットで扱われます。 すべての気配値には、multiplier ブロックの隣に bid_raw／ask_raw／spread_raw と bid_adjusted／ask_adjusted／mid_adjusted の両方が含まれ、どちらか一方だけになることはありません。
• オンチェーンの数量（トークン残高、ミント／バーン量）は元々乗数適用後の単位ですが、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 は公開されており、エージェントが直接アクセスするたびに、同じ落とし穴に気づいて一から対処することになります。

API の制限とキャッシュ

• 上流はキーなしで 60 req/s まで許可しています。このクライアントは ≤ 50 req/s に自主制限しています（リクエスト間に 20 ms の間隔を設け、スレッドセーフです）。
• 一時的なエラー（429/502/503/504、ネットワークエラー）は、2s × (attempt+1) のバックオフで最大 3 回再試行します。
• レスポンスキャッシュ（プロセスごと）：/assets は 5 min、/prices/{symbol} は 15 s、/corporate-actions は 1 h です。market_status() と sector_view() はキャッシュとアセットのみから計算され、価格リクエストを 194 件にわたって送信することはありません。

オンチェーンのデータソースと制限事項

v0.2 のオンチェーンツールは、REST API と並行してキー不要の公開データソースを2つ読み取ります。どちらも無料ですが、レート制限があり、一部に制限があります。上記のすべてのツールは、空の結果を黙って返すのではなく、フィールドごとの省略と 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を受け取ります。オプションの追加パッケージがインストールされている場合、ゲートウェイは Cloudflare の403を curl_cffi の Chrome なりすましを使って1回再試行します。 pip install "arcus-agent-gateway[browser]"。これがない場合、エクスプローラーを利用する2つのツール（holder_snapshot、wallet_holdings）は、次の正確なヒントを含む cloudflare エラーを正直に返します。それ以外の機能は引き続き動作します。 トークンページ（holders_count、circulating_market_cap、total_supply）、1ページ分のホルダー情報（最大50行、ページネーションのループなし）、アドレスの token-balances はここから取得し、600秒間キャッシュされます。token-balances は通常のウォレットでは約0.5秒で応答しますが、巨大なコントラクトアドレスでは40秒以上ハングします。クライアントは15秒後に explorer-timeout の種類で正直に失敗を返します。
• オンチェーンのアクティビティ ≠ 取引。ブロックチェーンには、アドレス間の Transfer、mint、redeem イベントが記録されますが、板取引や価格については何も記録されません。価格には quote()／quotes() を、トークンの移動には transfer_history() を使用してください。

生価格に関する免責事項

価格は Robinhood から届いたとおりにそのまま（RAW）提供されます。倍率による調整は行われず、*_adjusted フィールドは上流データではなくこちらで計算した値です。すべてのデータは情報提供のみを目的としており、取引判断には使用しないでください。利用前に公式ソースで確認してください。完全性、正確性、適時性について、いかなる保証もありません。

オプションの価格履歴レコーダー

Robinhood Chain REST API には価格履歴エンドポイントがなく、取得できるのは現在の気配値のみです。194 銘柄のトークン化株式については、このレコーダーが唯一の履歴データソースです。オプトイン方式で、デフォルトでは無効になっています。明示的に有効にしない限り、何も記録されません。

**仕組み。**デフォルトでは 5 分ごとに 1 回ティックし、同じレート制限付きクライアント（上限 50 req/s、平均負荷 ≈ 0.65 req/s）を通じて、ACTIVE 状態の取引可能なトークンすべての気配値を取得します。銘柄ごとに 1 行を data/history/snapshots_YYYYMM.parquet に追記し（毎月ローテーション）、日次 OHLCV 集計ファイル data/history/daily.parquet を維持します（mid_adjusted の始値／高値／安値／終値、volume はその日の累積 daily_volume の最大値）。前日分の集計は UTC の午前 0 時以降、最初のティックで実行され、冪等です（同じ日の処理を再実行すると上書きされ、重複は発生しません）。

有効にするには：

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 分間隔で記録すると、スナップショットは 1 日あたり約 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] エクストラをインストールしてください。

セキュリティとプライバシー

• **キー不要、読み取り専用です。**API キーも認証も書き込みも不要です。すべてのツールは MCP の通信上で readOnlyHint: true ／ destructiveHint: false として注釈されています。
• **設計上、レート制限があります。**クライアントは公開 REST インターフェースへのリクエストを 50 req/s に制限します。公開 RPC リクエストにも同じ制限が適用されます。Blockscout の呼び出しには一般的なブラウザーの User-Agent が設定され、個別のタイムアウトが適用されます。
• **テレメトリーなし、プロンプトのログ記録なし。**サーバーは公開市場データをメモリにキャッシュします（オプションのレコーダーを有効にした場合に限り、Parquet ファイルにも保存します）。API からの読み取り以外で、データがマシンの外に送信されることはありません。

スイートの一部

読み取り専用の MCP ゲートウェイ 4 つで構成され、すべて同じ方針です。キー不要、キャッシュ対応、問題発生時の動作も明確です。

4 つすべてが glama.ai と PyPI で公開されており、いずれも uvx <name> でインストールできます。

ライセンス

MIT ライセンスです。詳細は LICENSE を参照してください。Robinhood Markets, Inc. とは提携していません。