Trading gamit ang GaiaEx API: Authentication, Orders, at Market Data

Ang GaiaEx ay isang decentralized exchange na itinayo sa Hyperliquid L1, at ang API nito ay nagbibigay sa iyo ng programmatic access sa lahat ng inaalok ng platform — market data, order management, position tracking, at real-time streaming. Kung gumagawa ka man ng trading bot, isang portfolio dashboard, o isang custom alerting system, ang API ang entry point mo.

Nahahati ang API sa dalawang complementary na protocol:

• REST API — Request-response endpoints para sa paglagay ng orders, pagtanong ng balances, pagkuha ng historical trades, at pamamahala ng API keys. Gamitin ang REST kapag kailangan mong gumawa ng isang bagay o humingi ng isang partikular na bagay.
• WebSocket API — Persistent streaming connections para sa real-time market data (trades, order book updates, tickers) at private account events (order fills, position changes). Gamitin ang WebSocket kapag kailangan mong tumugon sa isang bagay sa mismong sandaling mangyari ito.

Sa ilalim ng makinarya, kumokonekta ang GaiaEx sa Hyperliquid L1 on-chain order book. Naitutugma ang mga order mo on-chain na may deterministic execution, at sinisiguro ang pondo mo ng MPC (Multi-Party Computation) wallets — na nangangahulugang walang single party (kahit ang GaiaEx) ang may hawak ng kumpleto mong private key. Ina-abstract ng API ang complexity ng blockchain: nagpapadala ka ng JSON request para maglagay ng order, at hinahandle ng platform ang signing, submission, at confirmation sa L1.

Sumusunod ang base URL para sa REST API sa standard na convention: https://api.gaiaex.com/v1/. Naitatatag ang WebSocket connections sa wss://api.gaiaex.com/ws/v1/. Lahat ng endpoints ay nagbabalik ng JSON, lahat ng timestamps ay sa milliseconds mula epoch (UTC), at lahat ng monetary values ay strings para maiwasan ang floating-point precision issues.

Para makakuha ng access sa private endpoints (paglagay ng orders, pagtanong ng balances mo), kailangan mo ng isang API key pair. Gumawa ng isa mula sa GaiaEx dashboard sa ilalim ng Settings → API Keys. Makakatanggap ka ng dalawang value:

• API Key — Isang public identifier na ipinapadala sa bawat request. Isipin itong username mo.
• API Secret — Isang private key na ginagamit para pirmahan ang mga request. Huwag itong ibahagi, huwag i-commit sa version control, huwag ipadala sa isang request header.

Gumagamit ang GaiaEx ng HMAC-SHA256 signing para authenticate-in ang mga private request. Ang proseso: pagsamahin ang timestamp, HTTP method, request path, at body sa isang string, tapos i-compute ang isang HMAC signature gamit ang secret mo. Isinasagawa ng server ang parehong computation at ikinukumpara ang mga signature.

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

Pinipigilan ng timestamp component ang replay attacks: itinatanggi ng server ang kahit anong request kung ang timestamp ay mahigit 30 segundo mula sa clock ng server. Siguraduhing synchronized ang clock ng makina mo gamit ang NTP.

Public ang mga market data endpoint — walang kailangang authentication. Nagbibigay sila ng raw na impormasyon na kailangan mo para gumawa ng mga trading decision.

Order book — Ibinabalik ang kasalukuyang bids at asks para sa isang partikular na symbol. Kontrolado ng depth parameter kung ilang price level ang ibabalik (default 20, max 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}")

Recent trades — Ibinabalik ang huling N na naisagawang trades para sa isang symbol. Kasama sa bawat trade ang presyo, quantity, side (kung ang taker ay bumili o nagbenta), at 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 — Isang buod ng kasalukuyang market state: last price, 24h high/low, 24h volume, best bid/ask, at percentage change. Ideal para sa paggawa ng watchlists o pag-scan para sa volatility.

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

Para sa real-time data, gamitin ang WebSocket feeds sa halip na polling ang mga endpoint na ito. Rate-limited ang mga REST endpoint at nagdadala ng latency; naghahatid ang WebSocket ng updates sa mismong sandaling mangyari ito sa Hyperliquid L1.

Ang order placement ang core action sa kahit anong trading system. Sinusuportahan ng GaiaEx ang tatlong order type sa pamamagitan ng POST /orders endpoint:

Market order — Isasagawa kaagad sa pinakamagandang available na presyo. Gamitin kapag mas mahalaga ang bilis ng execution kaysa sa precision ng presyo.

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

Limit order — Isasagawa lamang sa presyo mong tinukoy o mas maganda pa. Nananatili sa order book hanggang mapunan, makansela, o mag-expire.

# 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 order — Isang conditional order na nagiging active kapag naabot ng market ang trigger price. Ginagamit para sa stop-losses at breakout entries.

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

Para pamahalaan ang mga existing order: tanungin ang open orders gamit ang GET /orders?status=open, kanselahin ang isang partikular na order gamit ang DELETE /orders/{orderId}, o kanselahin lahat ng open orders para sa isang symbol gamit ang DELETE /orders?symbol=BTC-USD. Para sa position management, ibinabalik ng GET /positions lahat ng open positions kasama ang entry price, quantity, unrealized P&L, at liquidation price.

Gumagamit ang GaiaEx WebSocket API ng subscribe/unsubscribe na model. Matapos kumonekta, magpapadala ka ng subscription messages na tinukoy kung anong mga channel ang gustong matanggap mo. Available ang pareho — public (market data) at private (account events) channels — sa parehong connection.

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

Nagpush ng updates ang account.orders channel kailanman napunan, partially napunan, o nakansela ang isa sa mga order mo — na inaalis ang pangangailangan na polling ang REST endpoint. Nagstream ang account.positions channel ng real-time P&L at margin updates. Kasama ang mga public market data channel, isang WebSocket connection ang nagbibigay ng lahat ng kailangan ng isang trading bot para tumakbo.

Palaging isagawa ang isang heartbeat mechanism: nagpapadala ang GaiaEx ng periodic ping frames, at dapat tumugon ang client mo ng pong frames. Kung walang natanggap na pong sa loob ng 30 segundo, isasara ng server ang connection. Sa panig mo, kung walang dumarating na data sa loob ng 30 segundo, ipagpalagay na patay na ang connection at mag-reconnect.

Pagsamahin natin ang lahat sa isang minimal pero functional na trading bot. Sinusubaybayan ng bot ang presyo ng BTC-USD via WebSocket, at kapag bumagsak ang presyo sa ibaba ng target, naglalagay ito ng limit buy order. Kapag bukas ang position at tumaas ang presyo sa itaas ng take-profit level, isasara nito ang position.

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

Sadyang simple ito. Ang isang production bot ay magdadagdag ng: error handling na may try/except sa palibot ng bawat API call at automatic reconnection; retry logic na may exponential backoff para sa mga transient failure; position tracking via ang account.positions WebSocket channel sa halip na isang boolean flag; risk limits na huhinto sa trading matapos ang maximum daily loss; at logging na nirerekord ang bawat desisyon at API response para sa post-trade analysis.

Ang MPC wallet architecture ng GaiaEx ay nangangahulugang hindi kailanman hinahandle ng bot mo ang raw private keys — ang signing ay hinahandle ng distributed key infrastructure ng platform. Binabawasan nito ang security surface area kumpara sa mga bot na namamahala ng sariling wallet keys, kung saan ang isang compromise lang ay kayang mag-drain ng lahat ng pondo. Kasama ang API key IP whitelisting at ang HMAC authentication layer, nakukuha mo ang defense in depth para sa automated trading.

Magsimula nang maliit: mag-deploy gamit ang minimum position size, subaybayan sa loob ng 48 oras, i-verify na tumugma ang fills sa expectations, tapos unti-unting lakihan. Ang mga pinakamagandang trading bot ay itinatayo nang paunti-unti, hindi sa isang solong coding sprint.