Liquidiction Hip 4

Liquidiction MCP Server

MCP 互換エージェント向けの、読み取り専用 HIP-4 予測市場ツールです。このサーバーは Hyperliquid の公開 API に直接接続します。API キー、ウォレット接続、署名権限は不要です。

インストール

Node.js 20 以降と npm が必要です。

git clone https://github.com/Liquidiction/liquidiction-mcp.git
cd liquidiction-mcp
npm ci
npm start

これは stdio MCP サーバーであるため、npm start を実行するとウェブサイトが開くのではなく、MCP クライアントからの接続を待ちます。デフォルトではメインネットを使用します。テストネットのデータを使用する場合に限り、HL_API_URL=https://api.hyperliquid-testnet.xyz を設定してください。

既存のインストールの場合：git pull --ff-only、npm ci の順に実行してから、MCP クライアントを再起動してください。

クライアントを接続する

依存関係をインストールした後、クライアントに絶対パスを指定して設定します。

{
  "mcpServers": {
    "liquidiction": {
      "command": "node",
      "args": [
        "/absolute/path/liquidiction-mcp/node_modules/tsx/dist/cli.mjs",
        "/absolute/path/liquidiction-mcp/mcp-server.ts"
      ],
      "env": {
        "HL_API_URL": "https://api.hyperliquid.xyz"
      }
    }
  }
}

この設定はインストール済みのランタイムを使用するため、クライアントの作業ディレクトリが別の場所にあっても動作します。Windows では、C:/Users/you/liquidiction-mcp/mcp-server.ts のようなパスと、対応する node_modules/tsx/dist/cli.mjs のパスを使用してください。設定を変更した後は、クライアントを再起動してください。

Claude Code の場合：

claude mcp add liquidiction -- node /absolute/path/liquidiction-mcp/node_modules/tsx/dist/cli.mjs /absolute/path/liquidiction-mcp/mcp-server.ts

リポジトリのディレクトリから起動するクライアントでは、npx tsx mcp-server.ts も使用できます。

ツール

ツール	入力	結果
list_markets	なし	アクティブなアウトカム、選択肢、取引所、価格
get_market_detail	outcome_id	メタデータ、取引所、選択肢、各サイドの価格
get_market_summary	なし	市場の概要と利用可能な決済メタデータ
get_orderbook	outcome_id、任意の side	最良買い気配、最良売り気配、スプレッド
get_prices	なし	現在のアウトカムの仲値
get_candles	coin、任意の interval、任意の hours	OHLCV 履歴
get_recent_trades	coin	選択したアウトカムサイドの最近の公開取引
get_user_fills	address、任意の limit	ウォレットの最近の公開 HIP-4 約定
get_open_orders	address	公開中の HIP-4 注文
get_user_positions	address	ポジション、取引所、選択肢、保有シェア、評価額

アウトカム API リクエストでは #N を使用します。明示的なコイン入力には +N、旧形式の @N、数字のみのエイリアスも使用でき、#N に正規化されます。+N として返されるウォレット残高には、元のコイン表記が保持されるほか、正規の #N 識別子も含まれます。通常の現物 @N 行は、アウトカムの保有資産や約定として分類されません。

デプロイヤーをまたぐポジション

エージェントには、次のように依頼してください。

このウォレットの HIP-4 ポジションを、取引所、チーム、総シェア数、保有シェア数とともに表示してください。同じ試合のポジションを比較し、コントラクトを統合しないでください。

get_user_positions は、address、fetchedAt、source、スナップショットに関する注記、および positions 配列を含む JSON テキストを返します。各行には次の情報が含まれます。

• coin、rawCoin、outcomeId、side、venue、デプロイヤーのアドレス。
• 利用可能な場合は、コントラクトのメタデータから解決された市場名と選択肢のラベル。
• shares、元の total 文字列、heldShares、unheldShares。
• markPrice と markedValue。有効なマークが利用できない場合は null。
• 利用可能なコントラクトのタイミング、結果のソース、カウント対象プレイのフィールド、および生の説明。

サイド 0 がすべての取引所で同じチームを意味すると考えないでください。Outcome と trade.xyz では、試合の参加者が逆の順序で掲載されていることがあります。ツールは個別のコントラクトとそのルールを保持しますが、同等性を保証したり、ポジションを自動的に統合したりすることはありません。

unheldShares は総シェア数から保有シェア数を差し引いた値であり、注文が約定する保証ではありません。読み取りはアトミックなスナップショットではありません。マークは推定値であり、実行可能な売却価格ではありません。アクティブ市場のメタデータが見つからない場合は null のままです。このサーバーは、すべての決済済みコントラクトについて過去のメタデータを提供するものではありません。

既知のウォレットアドレスを指定してください。このサーバーは、特定の市場の組み合わせを保有するウォレットをインデックスから検索しません。

開発と検証

npm ci
npm run typecheck
npm test

回帰テストスイートはオフラインで実行され、現在の残高形式、デプロイヤー間のサイド反転、保有シェア、端数残高、価格情報の欠落、入力検証、API エラーを網羅しています。

オプションの読み取り専用スモークチェックでは、実際の MCP stdio クライアントを起動し、設定済みの Hyperliquid ネットワークに対して 10 個すべてのツールを呼び出します。

npm run test:live -- 0xff16003f5bc3560daf4b9df62c191831af47387f 1866

この例は実際のウォレットを使用するため、保有状況は変わる可能性があります。ポジションがなくなった場合は、別のウォレットと有効なアウトカム ID を選択してください。このチェックでは、MCP の保有状況と個別に取得した残高を比較するため、読み取りの間にウォレットが取引を行うと失敗する場合があります。Hyperliquid の通常のレート制限が適用されます。

リンク

• Liquidiction
• MCP ドキュメント
• X

MIT ライセンスです。このサーバーは取引を送信しません。