GaiaEx AcademyGaiaEx Academy
用 GaiaEx API 交易：身份认证、订单与市场数据
开发者编程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 与 WebSocket：各自何时使用 REST（请求 / 响应） 下单 / 撤单 余额、历史、REST 行情 最适合执行动作与快照 WebSocket（推流） 成交、订单簿、账户事件 推送更新，延迟更低 最适合实时策略 机器人通常二者并用：WS 收信号，REST 负责执行与对账。
需要持续的市场状态时用推流；需要离散的指令或快照时用 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 完成了同步。

HMAC 请求签名（概念示意） 客户端 sign(ts + method + path + body) 用 API secret 做 HMAC-SHA256 GaiaEx 校验 Secret 从不在网络上传输——传的只有签名 + 密钥 id + 时间戳。 时钟偏差窗口拦截过期重放
服务器会重新计算摘要；一旦不匹配就拒绝该调用，且不会暴露你的 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 小时，确认成交符合预期，再逐步放大。最好的交易机器人都是一点点搭出来的，而不是一次性写完的。