GaiaEx API で取引する — 認証、注文、マーケットデータ

GaiaEx は Hyperliquid L1 上に構築された分散型取引所であり、その API を通じて、マーケットデータ、注文管理、ポジションの追跡、リアルタイムのストリーミングなど、プラットフォームが提供するすべての機能にプログラムからアクセスできます。トレーディングボットを構築する場合も、ポートフォリオのダッシュボードを作る場合も、独自のアラートシステムを作る場合も、この API がその入口になります。

この API は、互いに補完しあう 2 つのプロトコルに分かれています。

• REST API — 注文の発注、残高の照会、過去のトレードの取得、API キーの管理を行うためのリクエスト・レスポンス型のエンドポイントです。何かを実行したい、あるいは特定の情報を問い合わせたいときに REST を使います。
• WebSocket API — リアルタイムのマーケットデータ（トレード、オーダーブックの更新、ティッカー）や、プライベートなアカウントイベント（注文の約定、ポジションの変化）のための、持続的なストリーミング接続です。何かが起きたその瞬間に反応したいときに WebSocket を使います。

裏側では、GaiaEx は Hyperliquid L1 のオンチェーンオーダーブックに接続しています。あなたの注文はオンチェーンで決定論的な実行によってマッチングされ、あなたの資金はMPC（Multi-Party Computation）ウォレットによって保護されています——つまり、単一の当事者（GaiaEx 自身も含めて）が、あなたの完全な秘密鍵を保有することはありません。この API はブロックチェーンの複雑さを抽象化しており、あなたは注文のための JSON リクエストを送るだけで、プラットフォームが署名、送信、L1 上での確定処理を担ってくれます。

REST API のベース URL は標準的な慣習に従い、https://api.gaiaex.com/v1/ です。WebSocket の接続は wss://api.gaiaex.com/ws/v1/ で確立します。すべてのエンドポイントは JSON を返し、すべてのタイムスタンプはエポックからのミリ秒（UTC）で表され、すべての金額の値は浮動小数点の精度問題を避けるために文字列で返されます。

プライベートなエンドポイント（注文の発注、残高の照会）にアクセスするには、API キーのペアが必要です。GaiaEx のダッシュボードの設定 → API キーから生成してください。2 つの値を受け取ります。

• API キー — すべてのリクエストと一緒に送られる公開の識別子です。ユーザー名のようなものだと考えてください。
• API シークレット — リクエストに署名するために使われる秘密の鍵です。決して共有せず、バージョン管理にコミットせず、リクエストヘッダーで送信しないでください。

GaiaEx はプライベートなリクエストを認証するためにHMAC-SHA256 署名を使用します。その処理は次のとおりです。タイムスタンプ、HTTP メソッド、リクエストのパス、ボディを 1 つの文字列に連結し、あなたのシークレットを使って HMAC 署名を計算します。サーバー側も同じ計算を行い、署名を比較します。

import hmac, hashlib, time, requests, json

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL = "https://api.gaiaex.com/v1"

def signed_request(method, path, body=None):
    timestamp = str(int(time.time() * 1000))
    body_str = json.dumps(body) if body else ""
    message = timestamp + method.upper() + path + body_str
    signature = hmac.new(
        API_SECRET.encode(), message.encode(), hashlib.sha256
    ).hexdigest()

    headers = {
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
        "Content-Type": "application/json",
    }

    resp = requests.request(method, BASE_URL + path, headers=headers,
                            data=body_str if body else None)
    return resp.json()

タイムスタンプの要素はリプレイ攻撃を防ぐためのものです。サーバーは、タイムスタンプがサーバーの時刻から 30 秒以上ずれているリクエストをすべて拒否します。あなたのマシンの時刻が NTP で同期されていることを確認してください。

マーケットデータのエンドポイントは公開されており、認証を必要としません。トレードの判断に必要な生の情報を提供してくれます。

オーダーブック — 指定したシンボルの現在のビッドとアスクを返します。depth パラメータで、返される価格レベルの数を制御できます（デフォルト 20、最大 100）。

# Fetch the BTC-USD order book (top 10 levels)
resp = requests.get(f"{BASE_URL}/orderbook/BTC-USD?depth=10")
book = resp.json()

best_bid = book["bids"][0]  # [price, quantity]
best_ask = book["asks"][0]
spread = float(best_ask[0]) - float(best_bid[0])
print(f"Spread: ${spread:.2f}")

直近の取引 — あるシンボルの直近 N 件の約定を返します。各取引には、価格、数量、サイド（テイカーが買いか売りか）、タイムスタンプが含まれます。

# Fetch the last 50 ETH-USD trades
resp = requests.get(f"{BASE_URL}/trades/ETH-USD?limit=50")
trades = resp.json()["trades"]
avg_price = sum(float(t["price"]) for t in trades) / len(trades)
print(f"Average of last 50 trades: ${avg_price:.2f}")

ティッカー — 現在の市場状態の要約です。直近価格、24 時間の高値・安値、24 時間の出来高、最良ビッド・アスク、変化率が含まれます。ウォッチリストの構築や、ボラティリティの高い銘柄のスキャンに最適です。

# Fetch all tickers
resp = requests.get(f"{BASE_URL}/tickers")
for ticker in resp.json():
    if float(ticker["change24h"]) > 5.0:
        print(f"{ticker['symbol']}: +{ticker['change24h']}%")

リアルタイムのデータが必要な場合は、これらのエンドポイントをポーリングする代わりに WebSocket のフィードを使ってください。REST のエンドポイントはレート制限があり、レイテンシが発生します。WebSocket は Hyperliquid L1 上で発生した瞬間に更新を配信します。

注文の発注は、どのトレーディングシステムにおいても中心的な動作です。GaiaEx は POST /orders エンドポイントを通じて 3 つの注文タイプをサポートしています。

マーケット注文 — 現在利用可能な最良の価格で即座に実行されます。価格の精度よりも実行スピードが重要なときに使います。

# Buy 0.1 BTC at market price
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"Filled at {order['avgPrice']}")

リミット注文 — 指定した価格かそれより良い価格でのみ実行されます。約定するか、キャンセルされるか、期限切れになるまで、オーダーブックに残り続けます。

# Sell 2 ETH at $3,500 or higher
order = signed_request("POST", "/orders", {
    "symbol": "ETH-USD",
    "side": "sell",
    "type": "limit",
    "price": "3500.00",
    "quantity": "2.0",
    "timeInForce": "GTC",  # Good Till Cancelled
})

ストップ注文 — 市場がトリガー価格に達したときに発効する条件付き注文です。ストップロスやブレイクアウトでのエントリーに使われます。

# Stop-loss: sell 0.5 BTC if price drops to $58,000
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "sell",
    "type": "stop_market",
    "stopPrice": "58000.00",
    "quantity": "0.5",
})

既存の注文を管理するには、GET /orders?status=open で未決済の注文を照会し、DELETE /orders/{orderId} で特定の注文をキャンセルし、DELETE /orders?symbol=BTC-USD でシンボルごとに未決済の注文をすべてキャンセルできます。ポジション管理には、GET /positions がエントリー価格、数量、未実現損益、清算価格を含むすべての未決済ポジションを返します。

GaiaEx の WebSocket API は subscribe／unsubscribe（購読／購読解除）のモデルを採用しています。接続後、どのチャンネルを受け取りたいかを指定した購読メッセージを送信します。公開のマーケットデータのチャンネルと、プライベートなアカウントイベントのチャンネルの両方が、同じ接続上で利用できます。

import asyncio, json, hmac, hashlib, time
import websockets

async def connect_gaiaex():
    uri = "wss://api.gaiaex.com/ws/v1"
    async with websockets.connect(uri) as ws:
        # Authenticate for private channels
        ts = str(int(time.time() * 1000))
        sig = hmac.new(API_SECRET.encode(),
                       (ts + "websocket_auth").encode(),
                       hashlib.sha256).hexdigest()
        await ws.send(json.dumps({
            "method": "auth",
            "apiKey": API_KEY,
            "timestamp": ts,
            "signature": sig,
        }))

        # Subscribe to public + private channels
        await ws.send(json.dumps({
            "method": "subscribe",
            "channels": [
                "trades.BTC-USD",
                "orderbook.BTC-USD",
                "account.orders",
                "account.positions",
            ]
        }))

        async for msg in ws:
            data = json.loads(msg)
            ch = data.get("channel", "")
            if ch == "account.orders":
                print(f"Order update: {data['status']} {data['orderId']}")
            elif ch == "trades.BTC-USD":
                print(f"Trade: {data['price']} x {data['quantity']}")

asyncio.run(connect_gaiaex())

account.orders チャンネルは、あなたの注文が約定、部分約定、キャンセルされるたびに更新をプッシュしてくれるため、REST のエンドポイントをポーリングする必要がなくなります。account.positions チャンネルは、リアルタイムの損益とマージンの更新をストリーミングします。公開のマーケットデータのチャンネルと組み合わせれば、1 つの WebSocket 接続だけで、トレーディングボットに必要なすべてが手に入ります。

必ずハートビートの仕組みを実装してください。GaiaEx は定期的にピングフレームを送信し、あなたのクライアントはポングフレームで応答する必要があります。30 秒以内にポングが受信されない場合、サーバーは接続を閉じます。あなたの側でも、30 秒間データが届かない場合は接続が切れたとみなし、再接続してください。

ここまでの内容を組み合わせて、最小限ながら実際に機能するトレーディングボットを作ってみましょう。このボットは WebSocket を通じて BTC-USD の価格を監視し、価格が目標を下回るとリミットの買い注文を出します。ポジションが開いていて、価格がテイクプロフィットのレベルを上回ったら、ポジションを決済します。

import asyncio, json
import websockets

TARGET_BUY = 60000.0
TAKE_PROFIT = 63000.0
QUANTITY = "0.05"
position_open = False

async def trading_bot():
    global position_open
    uri = "wss://api.gaiaex.com/ws/v1"

    async with websockets.connect(uri) as ws:
        # Auth + subscribe (omitted for brevity)
        await ws.send(json.dumps({
            "method": "subscribe",
            "channels": ["trades.BTC-USD"]
        }))

        async for msg in ws:
            data = json.loads(msg)
            if data.get("channel") != "trades.BTC-USD":
                continue

            price = float(data["price"])

            if not position_open and price <= TARGET_BUY:
                order = signed_request("POST", "/orders", {
                    "symbol": "BTC-USD", "side": "buy",
                    "type": "limit", "price": str(TARGET_BUY),
                    "quantity": QUANTITY,
                })
                print(f"BUY order placed: {order['orderId']}")
                position_open = True

            elif position_open and price >= TAKE_PROFIT:
                order = signed_request("POST", "/orders", {
                    "symbol": "BTC-USD", "side": "sell",
                    "type": "market", "quantity": QUANTITY,
                })
                print(f"SELL order placed: {order['orderId']}")
                position_open = False

asyncio.run(trading_bot())

これは意図的にシンプルなものにしています。本番用のボットには次を追加すべきです。すべての API 呼び出しに対する try/except によるエラー処理と自動再接続、一時的な失敗に対する指数バックオフを伴うリトライロジック、真偽値のフラグではなく account.positions の WebSocket チャンネルを通じたポジションの追跡、1 日の最大損失を超えたら取引を停止するリスクリミット、そしてトレード後の分析のために、すべての判断と API レスポンスを記録するロギングです。

GaiaEx の MPC ウォレットのアーキテクチャにより、あなたのボットが生の秘密鍵を扱うことは一切ありません——署名はプラットフォームの分散型鍵基盤によって処理されます。これにより、自分自身でウォレットの鍵を管理するボット——一度の漏洩ですべての資金が抜き取られてしまう可能性があるもの——と比較して、セキュリティ上の攻撃対象範囲が縮小されます。API キーの IP ホワイトリストと HMAC 認証のレイヤーを組み合わせることで、自動化されたトレーディングに対する多層防御が実現します。

小さく始めましょう。最小のポジションサイズでデプロイし、48 時間監視し、約定が期待どおりであることを確認してから、徐々にスケールしてください。最良のトレーディングボットは、一度のコーディングの集中作業ではなく、段階的に構築されるものです。