開發者程式設計12 min read

用 GaiaEx API 交易：身份認證、訂單與市場資料

以程式設計方式連線 GaiaEx，下出你的第一筆自動化交易

分享文章

GaiaEx API 概覽：構建在 Hyperliquid L1 上的 REST + WebSocket

GaiaEx 是一家構建在 Hyperliquid L1 上的去中心化交易所（DEX），它的 API 讓你能以程式設計方式訪問平臺提供的一切——市場資料、訂單管理、倉位跟蹤以及實時推流。無論你是在搭建交易機器人、投資組合面板，還是自定義的告警系統，API 都是你的入口。

該 API 由兩套互補的協議組成：

REST API —— 請求-響應式的端點，用於下單、查詢餘額、拉取歷史成交、管理 API 金鑰。當你需要做某件事或查詢某個具體資訊時，用 REST。
WebSocket API —— 持久的推流連線，用於實時市場資料（成交、訂單簿更新、行情）以及私有帳戶事件（訂單成交、倉位變化）。當你需要在事情發生的那一刻做出反應時，用 WebSocket。

在底層，GaiaEx 接入了 Hyperliquid L1 的鏈上訂單簿。你的訂單在鏈上以確定性執行撮合，你的資金由 MPC 錢包（多方計算）保護——也就是說沒有任何單一方（連 GaiaEx 也不例外）持有你完整的私鑰。API 遮蔽了區塊鏈的複雜性：你傳送一個 JSON 請求去下單，平臺便負責在 L1 上完成簽名、提交與確認。

REST API 的基礎 URL 遵循標準約定：https://api.gaiaex.com/v1/。WebSocket 連線在 wss://api.gaiaex.com/ws/v1/ 建立。所有端點都返回 JSON，所有時間戳都是自紀元起算的毫秒數（UTC），所有金額都用字串表示，以避免浮點精度問題。

需要持續的市場狀態時用推流；需要離散的指令或快照時用 REST。

API 金鑰管理與 HMAC 身份認證

要訪問私有端點（下單、查詢你的餘額），你需要一對 API 金鑰。在 GaiaEx 控制檯的 Settings → API Keys 中生成一對。你會拿到兩個值：

API Key —— 一個隨每個請求一起傳送的公開識別符號。可以把它當作你的使用者名稱。
API Secret —— 用於給請求籤名的私密金鑰。絕不分享、絕不提交到版本控制、絕不放進請求頭裡傳送。

GaiaEx 使用 HMAC-SHA256 簽名來認證私有請求。流程是：把時間戳、HTTP 方法、請求路徑和請求體拼接成一個字串，再用你的 secret 計算出一個 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()

把你的 API secret 存進環境變數或金鑰管理器——絕不要硬編碼。在控制檯為你的 API 金鑰設定 IP 白名單，把使用範圍限制在你伺服器的 IP 地址上。如果金鑰洩露，立刻從控制檯撤銷它並重新生成一個新的。

時間戳這一部分用於防範重放攻擊：只要請求中的時間戳與伺服器時鐘相差超過 30 秒，伺服器就會拒絕該請求。請確保你機器的時鐘透過 NTP 完成了同步。

伺服器會重新計算摘要；一旦不匹配就拒絕該呼叫，且不會暴露你的 secret。

拉取市場資料：訂單簿、成交與行情

市場資料端點是公開的——無需身份認證。它們提供你做交易決策所需的原始資訊。

訂單簿 —— 返回某個交易對當前的買價與賣價。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}")

行情（Ticker） —— 當前市場狀態的摘要：最新價、24h 最高/最低、24h 成交量、最優買價/賣價以及漲跌幅。非常適合用來搭建自選列表或掃描波動率。

# 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 端點支援三種訂單型別：

市價單 —— 立刻以當前可成交的最優價格執行。當執行速度比價格精度更重要時使用。

# 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 會返回所有持倉，附帶開倉價、數量、未實現盈虧和強平價格。

透過 WebSocket 推送實時資料

GaiaEx WebSocket API 採用訂閱/退訂模型。連線之後，你傳送訂閱訊息，指定希望接收哪些頻道。公有（市場資料）和私有（帳戶事件）兩類頻道都可以在同一條連線上使用。

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 頻道則實時推送盈虧和保證金更新。再配上公有的市場資料頻道，一條 WebSocket 連線就能提供交易機器人執行所需的一切。

務必實現一套心跳機制：GaiaEx 會定期傳送 ping 幀，而你的客戶端必須用 pong 幀回應。如果 30 秒內沒有收到 pong，伺服器就會關閉連線。在你這一側，如果 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 頻道而非一個布林標誌來做倉位跟蹤；在日內虧損達到上限後停止交易的風險限額；以及記錄每個決策和 API 響應、供事後覆盤分析的日誌。

GaiaEx 的 MPC 錢包架構意味著你的機器人從不經手原始私鑰——簽名由平臺分散式的金鑰基礎設施完成。相比那些自行管理錢包金鑰的機器人（一次洩露就能被掏空全部資金），這縮小了安全暴露面。再配合 API 金鑰的 IP 白名單和 HMAC 認證這一層，你就為自動化交易獲得了縱深防禦。

從小處起步：用最小倉位規模上線，觀察 48 小時，確認成交符合預期，再逐步放大。最好的交易機器人都是一點點搭出來的，而不是一次性寫完的。