GaiaEx API арқылы трейдинг: аутентификация, тапсырыстар және нарық деректері

GaiaEx — Hyperliquid L1 негізінде құрылған орталықсыздандырылған биржа (DEX), ал оның API-і сізге платформа ұсынатын барлық нәрсеге бағдарламалық қолжетімділік береді — нарық деректері, тапсырыс басқару, позицияларды бақылау және нақты уақыттағы ағын. Сауда боты, портфолио дэшборды немесе арнайы дабылдағыш жүйе құрсаңыз да, API — сіздің кіру нүктеңіз.

API екі толықтырушы хаттамаға бөлінеді:

• REST API — тапсырыс қою, баланс сұрау, тарихи мәмілелерді алу және API кілттерін басқару үшін сұрау-жауап түйінбасалары (endpoints). REST-ті бір нәрсе істеу немесе нақты бір нәрсе сұрау қажет болғанда қолданыңыз.
• WebSocket API — нақты уақыттағы нарық деректері (мәмілелер, тапсырыс кітабы жаңартулары, тикерлер) және жеке есептік жазба оқиғалары (тапсырыс орындалуы, позиция өзгерістері) үшін тұрақты ағын байланысы. WebSocket-ті бір нәрсе болған сәтте оған реакция жасау қажет болғанда қолданыңыз.

Астыңғы қабатта GaiaEx Hyperliquid L1 тізбекішілік тапсырыс кітабына қосылады. Тапсырыстарыңыз тізбекте детерминистік орындаумен сәйкестендіріледі, ал қаражатыңыз MPC (Multi-Party Computation, көп тарапты есептеу) әмиянмен қорғалады — яғни ешбір жеке тарап (GaiaEx-тің өзі де) сіздің толық жеке кілтіңізді ұстамайды. API блокчейн күрделілігін абстрактілендіреді: сіз тапсырыс қою үшін JSON сұрауын жібересіз, ал платформа L1-де қолтаңба қою, жіберу және растауды өз мойнына алады.

REST API үшін негізгі URL стандартты конвенцияларды ұстанады: https://api.gaiaex.com/v1/. WebSocket байланысы wss://api.gaiaex.com/ws/v1/ мекенжайында орнатылады. Барлық түйінбасалар JSON қайтарады, барлық уақыт белгілері epoch-тен бергі миллисекундпен (UTC) берілген, ал барлық ақша мәндері «қалқыма нүкте» дәлдігінің мәселелерінен қашу үшін жол (string) түрінде.

Жеке түйінбасаларға (тапсырыс қою, балансты сұрау) қол жеткізу үшін API кілт жұбы қажет. Оны GaiaEx дэшбордынан Параметрлер → API кілттері бөлімінде жасаңыз. Сізге екі мән беріледі:

• API кілт — әр сұраумен бірге жіберілетін ашық идентификатор. Оны пайдаланушы атыңыз деп есептеңіз.
• API құпия кілт — сұрауларға қолтаңба қою үшін қолданылатын жеке кілт. Оны ешқашан ортаққа салмаңыз, версия бақылауына енгізбеңіз, сұрау тақырыбында (header) жібермеңіз.

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 attack) қорғайды: сервер уақыт белгісі серверлің сағатынан 30 секундтан көп ерекшеленетін кез келген сұрауды қабылдамайды. Құрылғыңыздың сағаты NTP арқылы синхрондалғанына көз жеткізіңіз.

Нарық деректерінің түйінбасалары ашық — аутентификация талап етілмейді. Олар сауда шешімдерін қабылдау үшін қажет шикі ақпаратты береді.

Тапсырыс кітабы — берілген символ үшін ағымдағы бидтер мен асктарды қайтарады. 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 сағаттық көлем, ең жақсы бид/аск және пайыздық өзгеріс. Бақылау тізімдерін құру немесе тұрақсыздықты іздеу үшін тамаша.

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

Нақты уақыттағы деректер үшін бұл түйінбасаларды сұрап отырудың (polling) орнына 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
})

Стоп тапсырыс — нарық трек бағасына жеткенде белсенді болатын шартты тапсырыс. Стоп-лосс пен 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",
})

Бар тапсырыстарды басқару үшін: ашық тапсырыстарды GET /orders?status=open арқылы сұраныз, нақты тапсырысты DELETE /orders/{orderId} арқылы күшін жойыңыз, немесе символ бойынша барлық ашық тапсырыстарды DELETE /orders?symbol=BTC-USD арқылы күшін жойыңыз. Позицияларды басқару үшін GET /positions кіру бағасы, мөлшері, іске асырылмаған PnL және ликвидация бағасы бар барлық ашық позицияларды қайтарады.

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 каналы нақты уақыттағы PnL мен маржа жаңартуларын ағытады. Ашық нарық деректері каналдарымен бірге, бір ғана WebSocket байланысы сауда ботына қажет барлық нәрсені береді.

Әрдайым heartbeat (жүрек соғысы) механизмін іске асырыңыз: GaiaEx мезгіл-мезгіл ping фреймдерін жібереді, ал клиентіңіз pong фреймдерімен жауап беруі керек. 30 секунд ішінде pong алынбаса, сервер байланысты жабады. Өз жағыңыздан, 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())

Бұл әдейі қарапайым. Продукциондық бот мыналарды қосар еді: әр API шақыруын қоршайтын, автоматты қайта қосылумен қателерді өңдеу; уақытша ақаулар үшін экспоненциалды кідіріспен қайталау логикасы; логикалық жалаушаның орнына account.positions WebSocket каналы арқылы позицияны бақылау; максималды күндік шығыннан кейін саудаты тоқтататын тәуекел шектері; және әр шешім мен API жауабын кейінгі мәміле талдауы үшін жазатын логтау.

GaiaEx-тің MPC әмиян архитектурасы ботыңыз шикі жеке кілттермен ешқашан жұмыс істемейтінін білдіреді — қолтаңба қоюды платформаның бөлінген кілт инфрақұрылымы орындайды. Бұл өз әмиян кілттерін басқаратын, бір бұзылу барлық қаражатты құрту тудыратын боттарға қарағанда қауіпсіздік аймағын азайтады. API кілтінің IP ақ тізіміне қосуымен және HMAC аутентификация қабатымен бірге, автоматтандырылған сауда үшін терең қорғаныс аласыз.

Кішкентайдан бастаңыз: минималды позиция мөлшерімен орналастырыңыз, 48 сағат бақылаңыз, орындалулардың күтуге сай екенін тексеріңіз, содан кейін біртіндеп масштабтаңыз. Ең жақсы сауда боттары бір кодтау серпінінде емес, біртіндеп жасалады.