Trading dengan API GaiaEx: Autentikasi, Order, dan Data Pasar

GaiaEx adalah exchange terdesentralisasi (DEX) yang dibangun di atas Hyperliquid L1, dan API-nya memberimu akses terprogram ke semua yang ditawarkan platformnya — data pasar, manajemen order, pelacakan posisi, dan streaming real-time. Baik kamu membangun trading bot, dashboard portofolio, atau sistem alert kustom, API ini adalah titik masuknya.

API-nya terbagi menjadi dua protokol yang saling melengkapi:

• REST API — Endpoint request-response untuk menempatkan order, mengecek saldo, mengambil riwayat trading, dan mengelola API key. Gunakan REST saat kamu perlu melakukan sesuatu atau meminta sesuatu yang spesifik.
• WebSocket API — Koneksi streaming persisten untuk data pasar real-time (trading, update order book, ticker) dan event akun privat (fill order, perubahan posisi). Gunakan WebSocket saat kamu perlu bereaksi pada sesuatu tepat pada saat itu terjadi.

Di bawah permukaannya, GaiaEx terhubung ke order book on-chain Hyperliquid L1. Order-mu dicocokkan on-chain dengan eksekusi yang deterministik, dan danamu diamankan oleh dompet MPC (Multi-Party Computation) — artinya tidak ada satu pihak pun (bahkan GaiaEx sendiri) yang memegang kunci privatmu secara lengkap. API-nya mengabstraksi kompleksitas blockchain: kamu mengirim request JSON untuk menempatkan order, dan platform-nya menangani penandatanganan, pengiriman, dan konfirmasi di L1.

Base URL untuk REST API mengikuti konvensi standar: https://api.gaiaex.com/v1/. Koneksi WebSocket dibuat di wss://api.gaiaex.com/ws/v1/. Semua endpoint mengembalikan JSON, semua timestamp dalam milidetik sejak epoch (UTC), dan semua nilai moneter berupa string untuk menghindari masalah presisi floating-point.

Untuk mengakses endpoint privat (menempatkan order, mengecek saldomu), kamu butuh pasangan API key. Buat satu dari dashboard GaiaEx di bawah Settings → API Keys. Kamu akan menerima dua nilai:

• API Key — Pengenal publik yang dikirim di setiap request. Anggap saja seperti username-mu.
• API Secret — Kunci privat yang dipakai untuk menandatangani request. Jangan pernah membagikannya, jangan pernah commit ke version control, jangan pernah mengirimkannya di header request.

GaiaEx memakai penandatanganan HMAC-SHA256 untuk mengautentikasi request privat. Prosesnya: gabungkan timestamp, metode HTTP, path request, dan body menjadi satu string, lalu hitung signature HMAC memakai secret-mu. Server melakukan komputasi yang sama dan membandingkan signature-nya.

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

Komponen timestamp mencegah replay attack: server menolak request mana pun di mana timestamp-nya lebih dari 30 detik dari jam server. Pastikan jam mesinmu tersinkronisasi lewat NTP.

Endpoint data pasar bersifat publik — tidak perlu autentikasi. Endpoint-endpoint ini menyediakan informasi mentah yang kamu butuhkan untuk membuat keputusan trading.

Order book — Mengembalikan bid dan ask saat ini untuk simbol tertentu. Parameter depth mengontrol berapa banyak level harga yang dikembalikan (default 20, maksimum 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}")

Trading terkini — Mengembalikan N trading terakhir yang sudah tereksekusi untuk sebuah simbol. Setiap trading mencakup harga, kuantitas, side (apakah taker-nya membeli atau menjual), dan 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 — Ringkasan status pasar saat ini: harga terakhir, tertinggi/terendah 24 jam, volume 24 jam, bid/ask terbaik, dan persentase perubahan. Ideal untuk membangun watchlist atau memindai volatilitas.

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

Untuk data real-time, gunakan feed WebSocket alih-alih melakukan polling ke endpoint-endpoint ini. Endpoint REST dibatasi rate-nya dan menambahkan latensi; WebSocket mengirimkan update pada saat itu juga terjadi di Hyperliquid L1.

Penempatan order adalah aksi inti di sistem trading mana pun. GaiaEx mendukung tiga jenis order lewat endpoint POST /orders:

Market order — Tereksekusi seketika pada harga terbaik yang tersedia. Gunakan saat kecepatan eksekusi lebih penting daripada presisi harga.

# 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 — Tereksekusi hanya pada harga yang kamu tentukan atau lebih baik. Menunggu di order book sampai terisi (fill), dibatalkan, atau kedaluwarsa.

# 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 — Order kondisional yang menjadi aktif saat pasar mencapai harga trigger. Dipakai untuk stop-loss dan entry 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",
})

Untuk mengelola order yang sudah ada: cek order yang masih terbuka dengan GET /orders?status=open, batalkan order tertentu dengan DELETE /orders/{orderId}, atau batalkan semua order terbuka untuk sebuah simbol dengan DELETE /orders?symbol=BTC-USD. Untuk manajemen posisi, GET /positions mengembalikan semua posisi terbuka dengan harga entry, kuantitas, PnL belum terealisasi, dan harga likuidasi.

API WebSocket GaiaEx memakai model subscribe/unsubscribe. Setelah terhubung, kamu mengirim pesan subscription yang menentukan channel mana yang ingin kamu terima. Channel publik (data pasar) dan privat (event akun) sama-sama tersedia di koneksi yang sama.

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

Channel account.orders mengirimkan update kapan pun salah satu order-mu terisi (fill), terisi sebagian, atau dibatalkan — menghilangkan kebutuhan untuk melakukan polling ke endpoint REST. Channel account.positions men-streaming PnL real-time dan update margin. Digabungkan dengan channel data pasar publik, satu koneksi WebSocket menyediakan semua yang dibutuhkan trading bot untuk beroperasi.

Selalu implementasikan mekanisme heartbeat: GaiaEx mengirim frame ping secara periodik, dan klien-mu harus merespons dengan frame pong. Kalau tidak ada pong yang diterima dalam 30 detik, server menutup koneksinya. Di sisimu, kalau tidak ada data yang datang selama 30 detik, anggap koneksinya sudah mati dan sambungkan kembali.

Mari kita rangkai semuanya menjadi trading bot yang minimal tapi fungsional. Bot ini memonitor harga BTC-USD lewat WebSocket, dan ketika harganya turun di bawah target, ia menempatkan limit buy order. Ketika posisinya terbuka dan harganya naik di atas level take-profit, ia menutup posisinya.

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

Ini sengaja dibuat sederhana. Bot produksi akan menambahkan: error handling dengan try/except di sekitar setiap panggilan API dan reconnection otomatis; logika retry dengan exponential backoff untuk kegagalan sementara; pelacakan posisi lewat channel WebSocket account.positions alih-alih flag boolean; batas risiko yang menghentikan trading setelah mencapai kerugian harian maksimum; dan logging yang mencatat setiap keputusan dan respons API untuk analisis pasca-trading.

Arsitektur dompet MPC GaiaEx berarti bot-mu tidak pernah menangani kunci privat mentah — penandatanganannya ditangani oleh infrastruktur kunci terdistribusi milik platform. Ini mengurangi luas permukaan keamanan dibandingkan bot yang mengelola kunci dompet mereka sendiri, di mana satu kebocoran saja bisa mengosongkan semua dana. Digabungkan dengan IP whitelisting pada API key dan lapisan autentikasi HMAC, kamu mendapatkan pertahanan berlapis (defense in depth) untuk trading otomatis.

Mulai dari kecil: deploy dengan ukuran posisi minimum, monitor selama 48 jam, verifikasi bahwa fill-nya sesuai ekspektasi, lalu tingkatkan secara bertahap. Trading bot terbaik dibangun secara bertahap, bukan dalam satu sprint coding.