Giao dịch với GaiaEx API: xác thực, lệnh và dữ liệu thị trường

GaiaEx là một sàn giao dịch phi tập trung (DEX) được xây dựng trên Hyperliquid L1, và API của nó cho phép bạn truy cập bằng chương trình vào mọi thứ nền tảng cung cấp — dữ liệu thị trường, quản lý lệnh, theo dõi vị thế, và truyền dữ liệu theo thời gian thực. Cho dù bạn đang xây dựng một bot giao dịch, một bảng điều khiển danh mục đầu tư, hay một hệ thống cảnh báo tùy chỉnh, API là điểm khởi đầu của bạn.

API được chia thành hai giao thức bổ sung cho nhau:

• REST API — Các endpoint dạng yêu cầu-phản hồi để đặt lệnh, truy vấn số dư, lấy lịch sử giao dịch, và quản lý API key. Dùng REST khi bạn cần thực hiện điều gì đó hoặc hỏi về một thông tin cụ thể.
• WebSocket API — Kết nối truyền dữ liệu liên tục cho dữ liệu thị trường theo thời gian thực (giao dịch, cập nhật sổ lệnh, ticker) và các sự kiện tài khoản riêng tư (khớp lệnh, thay đổi vị thế). Dùng WebSocket khi bạn cần phản ứng với điều gì đó ngay khi nó xảy ra.

Bên dưới, GaiaEx kết nối với sổ lệnh (order book) on-chain của Hyperliquid L1. Các lệnh của bạn được khớp on-chain với tính thực thi tất định (deterministic execution), và tiền của bạn được bảo vệ bởi ví MPC (Multi-Party Computation) — nghĩa là không một bên nào (kể cả GaiaEx) nắm giữ toàn bộ private key của bạn. API trừu tượng hóa sự phức tạp của blockchain: bạn gửi một yêu cầu JSON để đặt lệnh, và nền tảng xử lý việc ký, gửi, và xác nhận trên L1.

URL cơ sở cho REST API tuân theo quy ước chuẩn: https://api.gaiaex.com/v1/. Kết nối WebSocket được thiết lập tại wss://api.gaiaex.com/ws/v1/. Tất cả các endpoint trả về JSON, tất cả các mốc thời gian đều tính bằng milli giây kể từ epoch (UTC), và tất cả các giá trị tiền đều là chuỗi để tránh các vấn đề về độ chính xác dấu phẩy động.

Để truy cập các endpoint riêng tư (đặt lệnh, truy vấn số dư của bạn), bạn cần một cặp API key. Tạo một cặp từ dashboard của GaiaEx tại Settings → API Keys. Bạn sẽ nhận được hai giá trị:

• API Key — Một định danh công khai được gửi kèm mỗi yêu cầu. Hãy coi nó như tên đăng nhập của bạn.
• API Secret — Một key riêng tư dùng để ký các yêu cầu. Không bao giờ chia sẻ nó, không bao giờ commit nó vào version control, không bao giờ gửi nó trong header của yêu cầu.

GaiaEx sử dụng chữ ký HMAC-SHA256 để xác thực các yêu cầu riêng tư. Quy trình: nối timestamp, phương thức HTTP, đường dẫn yêu cầu, và body thành một chuỗi duy nhất, sau đó tính toán chữ ký HMAC bằng secret của bạn. Server thực hiện cùng phép tính đó và so sánh các chữ ký.

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()

Thành phần timestamp ngăn chặn replay attack (tấn công tái phát lại): server sẽ từ chối bất kỳ yêu cầu nào có timestamp lệch quá 30 giây so với đồng hồ của server. Hãy đảm bảo đồng hồ máy của bạn được đồng bộ qua NTP.

Các endpoint dữ liệu thị trường là công khai — không cần xác thực. Chúng cung cấp thông tin thô mà bạn cần để đưa ra quyết định giao dịch.

Sổ lệnh (Order book) — Trả về các mức giá mua và bán hiện tại cho một symbol nhất định. Tham số depth kiểm soát bao nhiêu mức giá được trả về (mặc định 20, tối đa 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}")

Giao dịch gần đây — Trả về N giao dịch gần nhất đã thực hiện cho một symbol. Mỗi giao dịch bao gồm giá, số lượng, bên (taker đang mua hay đang bán), và timestamp.

# 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 — Một bản tóm tắt trạng thái thị trường hiện tại: giá cuối cùng, giá cao/thấp nhất 24h, khối lượng 24h, giá mua/bán tốt nhất, và tỷ lệ thay đổi giá. Lý tưởng để xây dựng danh sách theo dõi hoặc rà soát biến động.

# 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']}%")

Đối với dữ liệu thời gian thực, hãy dùng các luồng WebSocket thay vì polling các endpoint này. Các endpoint REST bị giới hạn tốc độ và tạo ra độ trễ; WebSocket cung cấp cập nhật ngay tức thì khi chúng xảy ra trên Hyperliquid L1.

Đặt lệnh là hành động cốt lõi trong bất kỳ hệ thống giao dịch nào. GaiaEx hỗ trợ ba loại lệnh thông qua endpoint POST /orders:

Lệnh thị trường (Market order) — Thực thi ngay lập tức ở mức giá tốt nhất hiện có. Dùng khi tốc độ thực thi quan trọng hơn độ chính xác về giá.

# 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']}")

Lệnh giới hạn (Limit order) — Chỉ thực thi ở mức giá bạn chỉ định hoặc tốt hơn. Nằm chờ trên sổ lệnh cho đến khi khớp, hủy, hoặc hết hạn.

# 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
})

Lệnh dừng (Stop order) — Một lệnh có điều kiện được kích hoạt khi thị trường đạt đến một mức giá kích hoạt. Dùng cho cắt lỗ (stop-loss) và vào lệnh theo breakout.

# 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",
})

Để quản lý các lệnh hiện có: truy vấn lệnh đang mở với GET /orders?status=open, hủy một lệnh cụ thể với DELETE /orders/{orderId}, hoặc hủy tất cả lệnh đang mở cho một symbol với DELETE /orders?symbol=BTC-USD. Đối với quản lý vị thế, GET /positions trả về tất cả các vị thế đang mở kèm giá vào, số lượng, lãi/lỗ chưa hiện thực hóa, và giá thanh lý.

API WebSocket của GaiaEx sử dụng mô hình đăng ký/hủy đăng ký (subscribe/unsubscribe). Sau khi kết nối, bạn gửi các thông báo đăng ký chỉ định kênh nào bạn muốn nhận. Cả kênh công khai (dữ liệu thị trường) và kênh riêng tư (sự kiện tài khoản) đều có sẵn trên cùng một kết nối.

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())

Kênh account.orders đẩy cập nhật mỗi khi một trong các lệnh của bạn được khớp, khớp một phần, hoặc bị hủy — loại bỏ nhu cầu phải polling endpoint REST. Kênh account.positions truyền dữ liệu cập nhật lãi/lỗ và ký quỹ theo thời gian thực. Kết hợp với các kênh dữ liệu thị trường công khai, một kết nối WebSocket duy nhất cung cấp mọi thứ một bot giao dịch cần để hoạt động.

Luôn triển khai một cơ chế heartbeat (nhịp tim): GaiaEx gửi các khung ping định kỳ, và client của bạn phải phản hồi bằng khung pong. Nếu không nhận được pong trong vòng 30 giây, server sẽ đóng kết nối. Ở phía bạn, nếu không có dữ liệu nào đến trong 30 giây, hãy coi kết nối đã chết và kết nối lại.

Hãy ghép mọi thứ lại thành một bot giao dịch tối giản nhưng hoạt động được. Bot theo dõi giá BTC-USD qua WebSocket, và khi giá giảm xuống dưới một mục tiêu, nó đặt một lệnh mua giới hạn. Khi vị thế đang mở và giá tăng lên trên mức chốt lời, nó đóng vị thế.

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())

Đây là bản cố ý viết đơn giản. Một bot thực chiến sẽ bổ sung thêm: xử lý lỗi bằng try/except quanh mỗi lệnh gọi API cùng với tự động kết nối lại; logic retry (thử lại) với exponential backoff cho các lỗi tạm thời; theo dõi vị thế qua kênh WebSocket account.positions thay vì một cờ boolean; hạn mức rủi ro dừng giao dịch sau khi đạt mức lỗ tối đa trong ngày; và ghi log lưu lại mỗi quyết định và phản hồi API để phân tích sau giao dịch.

Kiến trúc ví MPC của GaiaEx có nghĩa là bot của bạn không bao giờ xử lý private key thô — việc ký được xử lý bởi hạ tầng key phân tán của nền tảng. Điều này giảm bề mặt bị tấn công về mặt an ninh so với các bot tự quản lý key ví riêng của chúng, nơi một lần bị lộ duy nhất có thể rút cạn toàn bộ tiền. Kết hợp với việc whitelist IP cho API key và lớp xác thực HMAC, bạn có được khả năng phòng thủ theo nhiều tầng cho giao dịch tự động.

Bắt đầu nhỏ: triển khai với kích thước vị thế tối thiểu, theo dõi trong 48 giờ, xác minh rằng các lần khớp lệnh đúng như kỳ vọng, rồi mở rộng dần dần. Những bot giao dịch tốt nhất được xây dựng dần từng bước, không phải trong một lần code duy nhất.