Торгівля через API GaiaEx: автентифікація, ордери та ринкові дані

GaiaEx — це децентралізована біржа, побудована на Hyperliquid L1, а її API надає програмний доступ до всього, що пропонує платформа — ринкові дані, керування ордерами, відстеження позицій та потокову передачу даних у реальному часі. Незалежно від того, чи будуєте ви торгового бота, дашборд портфеля, чи власну систему сповіщень, API — ваша точка входу.

API розділений на два взаємодоповнюючих протоколи:

• REST API — ендпоінти запит-відповідь для розміщення ордерів, запиту балансів, отримання історії угод та керування API-ключами. Використовуйте REST, коли потрібно щось зробити чи запитати конкретну інформацію.
• WebSocket API — постійні потокові з’єднання для ринкових даних у реальному часі (угоди, оновлення книги ордерів, тікери) та приватних подій рахунку (виконання ордерів, зміни позицій). Використовуйте WebSocket, коли потрібно реагувати на щось у момент, коли це відбувається.

Під капотом GaiaEx з’єднується з он-чейн книгою ордерів Hyperliquid L1. Ваші ордери зіставляються он-чейн з детерміністичним виконанням, а ваші кошти захищені MPC-гаманцями (багатостороннє обчислення) — тобто жодна окрема сторона (навіть GaiaEx) не тримає ваш повний приватний ключ. API абстрагує складність блокчейну: ви надсилаєте JSON-запит, щоб розмістити ордер, а платформа обробляє підпис, надсилання та підтвердження на L1.

Базовий URL для REST API відповідає стандартним конвенціям: https://api.gaiaex.com/v1/. З’єднання WebSocket встановлюються за адресою wss://api.gaiaex.com/ws/v1/. Усі ендпоінти повертають JSON, усі мітки часу — у мілісекундах з епохи (UTC), а всі грошові значення — рядки, щоб уникнути проблем з точністю чисел з рухомою комою.

Для доступу до приватних ендпоінтів (розміщення ордерів, запит балансів) вам потрібна пара API-ключів. Створіть її на дашборді GaiaEx у розділі Settings → API Keys. Ви отримаєте два значення:

• API Key — публічний ідентифікатор, що надсилається з кожним запитом. Уявіть його як ваше ім’я користувача.
• API Secret — приватний ключ, що використовується для підпису запитів. Ніколи не діліться ним, ніколи не додавайте його в систему контролю версій, ніколи не надсилайте його в заголовку запиту.

GaiaEx використовує підпис HMAC-SHA256 для автентифікації приватних запитів. Процес: об’єднайте мітку часу, HTTP-метод, шлях запиту та тіло в один рядок, потім обчисліть 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()

Компонент мітки часу запобігає атакам повторного відтворення (replay attacks): сервер відхиляє будь-який запит, у якого мітка часу відрізняється від годинника сервера більш ніж на 30 секунд. Переконайтесь, що годинник вашої машини синхронізований через NTP.

Ендпоінти ринкових даних публічні — автентифікація не потрібна. Вони надають необроблену інформацію, потрібну вам для прийняття торгових рішень.

Книга ордерів (order book) — повертає поточні заявки на купівлю (bids) та продаж (asks) для заданого символу. Параметр 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}")

Тікер — підсумок поточного стану ринку: остання ціна, максимум/мінімум за 24 години, обсяг за 24 години, найкращі bid/ask та відсоткова зміна. Ідеально для побудови списків спостереження чи пошуку волатильності.

# 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-потоки замість опитування (polling) цих ендпоінтів. 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 повертає всі відкриті позиції з ціною входу, кількістю, нереалізованим P&L та ціною ліквідації.

API WebSocket GaiaEx використовує модель підписки/відписки (subscribe/unsubscribe). Після підключення ви надсилаєте повідомлення підписки, вказуючи, які канали ви хочете отримувати. Публічні (ринкові дані) та приватні (події рахунку) канали доступні в одному з’єднанні.

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 транслює оновлення P&L та маржі у реальному часі. У поєднанні з публічними каналами ринкових даних одне WebSocket-з’єднання надає все, що потрібно торговому боту для роботи.

Завжди реалізуйте механізм heartbeat: GaiaEx надсилає періодичні ping-кадри, і ваш клієнт повинен відповідати pong-кадрами. Якщо pong не отримано протягом 30 секунд, сервер закриває з’єднання. З вашого боку, якщо дані не надходять протягом 30 секунд, вважайте з’єднання мертвим і перепідключіться.

Об’єднаймо все у мінімального, але функціонального торгового бота. Бот стежить за ціною BTC-USD через WebSocket, і коли ціна опускається нижче цільового рівня, він розміщує лімітний ордер на купівлю. Коли позиція відкрита і ціна піднімається вище рівня тейк-профіту, він закриває позицію.

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

Це навмисно просто. Продакшн-бот додасть: обробку помилок з try/except навколо кожного API-виклику та автоматичне перепідключення; логіку повторних спроб з експоненційною відстрочкою для тимчасових збоїв; відстеження позицій через WebSocket-канал account.positions замість булевого флагу; ризик-ліміти, що зупиняють торгівлю після максимального денного збитку; та логування, що фіксує кожне рішення та відповідь API для пост-трейд аналізу.

Архітектура MPC-гаманця GaiaEx означає, що ваш бот ніколи не обробляє необроблені приватні ключі — підпис обробляється розподіленою інфраструктурою ключів платформи. Це зменшує поверхню безпеки порівняно з ботами, що керують власними ключами гаманця, де одна компрометація може виснажити всі кошти. У поєднанні з білим списком IP-адрес API-ключа та рівнем автентифікації HMAC ви отримуєте глибокий захист для автоматизованої торгівлі.

Починайте з малого: розгортайте з мінімальним розміром позиції, моніторте протягом 48 годин, перевірте, що виконання відповідає очікуванням, потім масштабуйте поступово. Найкращі торгові боти будуються поступово, а не за один спринт кодування.