Hyperliquid Agent Gateway

hyperliquid-agent-gateway

Hyperliquidでは、約233の無期限先物、326のスポット取引ペア、EVMチェーン全体の情報を、すべてパブリックエンドポイントから読み取れます。このMCP サーバーは、エージェントに代わってその情報を読み取ります。市場やファンディングのデータ、アカウントごとのリスク、トレーダーの活動、HyperEVM（チェーン999）のトークン送金に対応しています。キーも署名も書き込みも不要です。すべてのリクエストはapi.hyperliquid.xyz/infoとrpc.hyperliquid.xyz/evm経由で処理され、キャッシュとレート制限により、意欲的なエージェントが上流に過剰なリクエストを送るのを防ぎます。

ユースケース

清算ツールは、利用者が最も求める機能です。任意のアドレスを渡すと、証拠金の概要、ポジションごとのレバレッジ、清算までの距離が得られます。取引所がliquidationPxを公開している場合は、実際の数値をその旨とともに返します。公開していない場合は、推定値であることを明記した推定値を返します。崖っぷちまで17.6％の距離にあった、想定元本2億900万ドル、レバレッジ25倍のショートポジションでテストしました。

ファンディング：funding_carry_screenerは単一の呼び出しですべての233の無期限先物をランク付けし、その後、上位の数件についてのみ168時間分の履歴を取得します。これは、APIのウェイト予算（毎分1200）が無計画な利用に厳しいためです。レートが一時的な急騰なのか、継続的な傾向なのかを確認できます。

HyperEVMの送金情報により、オンチェーンの資金の流れを無期限先物市場に結び付けられます。quoteは、常に[bid, ask]の範囲内に収まる、板情報に基づくミッド価格を返します。trader_activityは、任意のアドレスについて、約定、手数料、勝率、ファンディングによる損失、オープンポジションを分析します。

詳しい手順：examples/use-cases.md。

クイックスタート

Claude Code:

claude mcp add hyperliquid -- uvx hyperliquid-agent-gateway

stdio（デフォルト。ローカルエージェント向け）：

uvx hyperliquid-agent-gateway

またはチェックアウトから：

git clone https://github.com/alekskram/hyperliquid-agent-gateway
cd hyperliquid-agent-gateway
uv sync
uv run hyperliquid-agent-gateway

Claude Desktop / Cursorの設定：

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

ホスト型の構成。ポート8903でストリーミング可能なHTTPを使用：

uvx hyperliquid-agent-gateway --http             # 127.0.0.1:8903
curl http://127.0.0.1:8903/health   # -> {"ok": true, "service": "hyperliquid-agent-gateway", ...}

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

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

# 2) register it (merges into ~/.zcode/cli/config.json)
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", {})["hyperliquid"] = {
    "type": "http", "url": "http://127.0.0.1:8903/mcp"}
json.dump(cfg, open(p, "w"), indent=2)
print("hyperliquid-agent-gateway registered:", p)
PY

12 個のツールはすべて読み取り専用です（readOnlyHint: true, destructiveHint: false, openWorldHint: true の注釈付き）。

生の API ではなくゲートウェイを使う理由

api.hyperliquid.xyz/info は公開されており、POST を 1 回送るだけで利用できます。しかし、その先には落とし穴があります。

レート制限

上流サービスを保護するため、独立した2つの予算をローカルで適用しています。

/info - ローリング60秒あたり1200ウェイト（Hyperliquidが公開しているウェイト料金）。リクエストの種類ごとに追跡されます。

次のリクエストで予算を超える場合、クライアントはウィンドウが更新されるまで1回だけ（最大5秒）待機し、制限を明示したエラーを発生させます。無期限にスリープしてブロックすることはありません。

HyperEVM RPC - ローリング60秒あたり100リクエスト（各リクエスト一律1）。/infoとは別に適用されます。予算超過の呼び出しは直ちにエラー（rpc-limit）を発生させます。ツールは適切なエラーディクショナリを返し、wallet_balanceは上限に達した時点でERC-20のスキャンを停止します。

TTLキャッシュでは、データの種類ごとに繰り返しの呼び出しも重複排除します。allMidsは15秒、recentTradesは15秒、l2Bookは5秒、metaAndAssetCtxsは60秒、spotMetaは3600秒、spotMetaAndAssetCtxsは60秒、candleSnapshotは300秒、fundingHistoryは300秒、アドレスごとのアカウント情報は60秒です。

データに関する注意事項

• APIからの数値はすべて、上流ではSTRINGです。ゲートウェイは例外を発生させないヘルパーで解析します。nullは常に「利用不可」を意味し、ゼロを意味することはありません。
• 上流でのエラーはすべて、トレースバックではなく、エラーディクショナリ {"error": ..., "source": ..., "reason": ...} を返します。部分的なデータはフィールドごとに劣化し、warnings[]に記録されます。
• liquidation_riskは清算価格を捏造しません。取引所が清算価格を公開していない場合、liq_pxはnullのままで、距離は推定値であることを明示します（計算式はツールの注記を参照）。Mark価格も捏造しません。ライブポジションにはmarkPxが含まれないため、metaAndAssetCtxs（フォールバックはallMids）から取得し、行のmark_px_sourceに取得元を記録します。取得元がない場合はnullです。
• funding_drag / funding_net：取引所のuserFundingが返すのはゼロ以外の資金調達イベントのみです。そのため、新しいアドレスや取引の少ないアドレスでライブデータがnull／空になるのは想定された動作であり、バグではありません。
• ERC-20の金額には、HyperEVMの標準トークン用の固定小数点マップを使用します（USDC／USDT系は6、PURR／HYPEは18）。不明なトークンは18を仮定し、すべての行にdecimals_source: "assumed_18"と記載します。マッピングされていないトークンについて、6桁の小数精度を信頼しないでください。
• キャッシュされたレスポンスには、鮮度を示すage_seconds / fetched_atフィールドが含まれます。

スイートの一部

読み取り専用の兄弟MCPゲートウェイが4つあります。いずれも同じ設計方針で、キー不要、キャッシュ対応、データの劣化を正直に示します。

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

ライセンス

MIT。