GaiaEx API ile İşlem: Kimlik Doğrulama, Emirler ve Piyasa Verisi

GaiaEx, Hyperliquid L1 üzerine inşa edilmiş merkeziyetsiz bir borsadır ve API'si, platformun sunduğu her şeye programatik erişim sağlar — piyasa verisi, emir yönetimi, pozisyon takibi ve gerçek zamanlı akış (streaming). Bir işlem botu, bir portföy panosu veya özel bir uyarı sistemi geliştiriyor olsan da, API senin giriş noktandır.

API, birbirini tamamlayan iki protokole ayrılır:

• REST API — Emir vermek, bakiye sorgulamak, geçmiş işlemleri getirmek ve API anahtarlarını yönetmek için istek-yanıt uç noktaları. Belirli bir şeyi yapman veya belirli bir şey istemen gerektiğinde REST kullan.
• WebSocket API — Gerçek zamanlı piyasa verisi (işlemler, emir defteri güncellemeleri, ticker'lar) ve özel hesap olayları (emir gerçekleşmeleri, pozisyon değişiklikleri) için kalıcı akış bağlantıları. Bir şey gerçekleştiği anda ona tepki vermen gerektiğinde WebSocket kullan.

Perde arkasında, GaiaEx Hyperliquid L1'in zincir üstü emir defterine bağlanır. Emirlerin belirleyici (deterministic) yürütmeyle zincir üstünde eşleştirilir ve fonların MPC (Çok Taraflı Hesaplama) cüzdanları tarafından güvence altına alınır — bu, hiçbir tek tarafın (GaiaEx dahil) senin tam özel anahtarını tutmadığı anlamına gelir. API, blok zinciri karmaşıklığını basitleştirir: bir emir vermek için bir JSON isteği gönderirsin ve platform, imzalamayı, gönderimi ve L1'de onaylamayı halleder.

REST API'nin taban URL'si standart kurallara uyar: https://api.gaiaex.com/v1/. WebSocket bağlantıları wss://api.gaiaex.com/ws/v1/ adresinde kurulur. Tüm uç noktalar JSON döndürür, tüm zaman damgaları epoch'tan itibaren milisaniyedir (UTC) ve kayan nokta hassasiyet sorunlarını önlemek için tüm parasal değerler string olarak gönderilir.

Özel uç noktalara erişmek için (emir vermek, bakiyeni sorgulamak), bir API anahtar çiftine ihtiyacın var. Bunu GaiaEx panosundan Ayarlar → API Anahtarları altından oluşturabilirsin. İki değer alacaksın:

• API Key (Anahtar) — Her istekle gönderilen genel bir tanımlayıcı. Kullanıcı adın gibi düşün.
• API Secret (Gizli Anahtar) — İstekleri imzalamak için kullanılan özel bir anahtar. Bunu asla paylaşma, versiyon kontrolüne asla göndermeyin (commit), bir istek başlığında asla göndermeyin.

GaiaEx, özel istekleri doğrulamak için HMAC-SHA256 imzalama kullanır. İşlem şöyledir: zaman damgasını, HTTP yöntemini, istek yolunu ve gövdeyi tek bir string'te birleştir, sonra gizli anahtarını kullanarak bir HMAC imzası hesapla. Sunucu aynı hesaplamayı yapar ve imzaları karşılaştırır.

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

Zaman damgası bileşeni tekrar oynatma (replay) saldırılarını önler: sunucu, zaman damgası sunucunun saatinden 30 saniyeden fazla uzak olan her isteği reddeder. Makinenin saatinin NTP üzerinden senkronize olduğundan emin ol.

Piyasa verisi uç noktaları herkese açıktır — kimlik doğrulaması gerektirmez. İşlem kararları vermen için gereken ham bilgiyi sağlarlar.

Emir defteri — Belirli bir sembol için o anki alış ve satış emirlerini döndürür. depth parametresi kaç fiyat seviyesinin döndürüleceğini kontrol eder (varsayılan 20, maksimum 100).

# BTC-USD emir defterini getir (üst 10 seviye)
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}")

Son işlemler — Bir sembol için son N gerçekleşen işlemi döndürür. Her işlem fiyatı, miktarı, tarafı (taker'ın alış mı satış mı yaptığı) ve zaman damgasını içerir.

# Son 50 ETH-USD işlemini getir
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"Son 50 işlemin ortalaması: ${avg_price:.2f}")

Ticker — O anki piyasa durumunun özeti: son fiyat, 24 saatlik en yüksek/en düşük, 24 saatlik hacim, en iyi alış/satış ve yüzdesel değişim. İzleme listeleri oluşturmak veya oynaklığı taramak için idealdir.

# Tüm ticker'ları getir
resp = requests.get(f"{BASE_URL}/tickers")
for ticker in resp.json():
    if float(ticker["change24h"]) > 5.0:
        print(f"{ticker['symbol']}: +{ticker['change24h']}%")

Gerçek zamanlı veri için, bu uç noktaları yoklamak (polling) yerine WebSocket akışlarını kullan. REST uç noktaları hız sınırlıdır (rate-limited) ve gecikme (latency) yaratır; WebSocket, Hyperliquid L1'de gerçekleştiği anda güncellemeleri iletir.

Emir verme, herhangi bir işlem sisteminde temel eylemdir. GaiaEx, POST /orders uç noktası üzerinden üç emir türünü destekler:

Piyasa emri — Mevcut en iyi fiyatta anında gerçekleşir. Yürütme hızının fiyat kesinliğinden daha önemli olduğu durumlarda kullanılır.

# Piyasa fiyatından 0,1 BTC satın al
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"Gerçekleşme fiyatı: {order['avgPrice']}")

Limit emri — Sadece belirttiğin fiyatta veya daha iyisinde gerçekleşir. Gerçekleşene, iptal edilene veya süresi dolana kadar emir defterinde bekler.

# 2 ETH'yi $3.500 veya daha yükseğe sat
order = signed_request("POST", "/orders", {
    "symbol": "ETH-USD",
    "side": "sell",
    "type": "limit",
    "price": "3500.00",
    "quantity": "2.0",
    "timeInForce": "GTC",  # İptal Edilene Kadar Geçerli
})

Stop emri — Piyasa tetikleme fiyatına ulaştığında etkinleşen koşullu bir emir. Zarar durdurma (stop-loss) ve kırılım (breakout) girişleri için kullanılır.

# Zarar durdur: fiyat $58.000'e düşerse 0,5 BTC sat
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "sell",
    "type": "stop_market",
    "stopPrice": "58000.00",
    "quantity": "0.5",
})

Mevcut emirleri yönetmek için: açık emirleri GET /orders?status=open ile sorgula, belirli bir emri DELETE /orders/{orderId} ile iptal et, veya bir sembole ait tüm açık emirleri DELETE /orders?symbol=BTC-USD ile iptal et. Pozisyon yönetimi için, GET /positions giriş fiyatı, miktar, gerçekleşmemiş kâr/zarar ve tasfiye fiyatıyla tüm açık pozisyonları döndürür.

GaiaEx WebSocket API'si abone ol / abonelikten çık modeli kullanır. Bağlandıktan sonra, hangi kanallardan veri almak istediğini belirten abonelik mesajları gönderirsin. Aynı bağlantı üzerinde hem genel (piyasa verisi) hem de özel (hesap olayları) kanallar mevcuttur.

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:
        # Özel kanallar için kimlik doğrula
        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,
        }))

        # Genel + özel kanallara abone ol
        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"Emir güncellemesi: {data['status']} {data['orderId']}")
            elif ch == "trades.BTC-USD":
                print(f"İşlem: {data['price']} x {data['quantity']}")

asyncio.run(connect_gaiaex())

account.orders kanalı, emirlerinden biri gerçekleştiğinde, kısmen gerçekleştiğinde veya iptal edildiğinde güncelleme gönderir — bu da REST uç noktasını yoklama (polling) ihtiyacını ortadan kaldırır. account.positions kanalı gerçek zamanlı kâr/zarar ve marj güncellemelerini akıtır. Genel piyasa verisi kanallarıyla birleştiğinde, tek bir WebSocket bağlantısı bir işlem botunun çalışması için gereken her şeyi sağlar.

Her zaman bir heartbeat mekanizması uygula: GaiaEx periyodik ping çerçeveleri gönderir ve istemcin bunlara pong çerçeveleriyle yanıt vermelidir. 30 saniye içinde bir pong alınmazsa, sunucu bağlantıyı kapatır. Kendi tarafında, 30 saniye içinde hiçbir veri gelmezse, bağlantının koptuğunu düşün ve yeniden bağlan.

Her şeyi minimal ama işlevsel bir işlem botunda birleştirelim. Bot, WebSocket üzerinden BTC-USD fiyatını izler ve fiyat bir hedefin altına düştüğünde limit alım emri verir. Pozisyon açık olduğunda ve fiyat bir kâr al seviyesinin üzerine çıktığında, pozisyonu kapatır.

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:
        # Kimlik doğrulama + abonelik (kısalık için atlandı)
        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"ALIM emri verildi: {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"SATIM emri verildi: {order['orderId']}")
                position_open = False

asyncio.run(trading_bot())

Bu bilinçli olarak basittir. Üretim düzeyi bir bot şunları ekler: her API çağrısı etrafında try/except ile hata yönetimi ve otomatik yeniden bağlanma; geçici hatalar için üstel geri çekilme (exponential backoff) ile yeniden deneme mantığı; bir boolean bayrak yerine account.positions WebSocket kanalı üzerinden pozisyon takibi; maksimum günlük zarar sonrası işlemi durduran risk sınırları; ve işlem sonrası analiz için her kararı ve API yanıtını kaydeden günlükleme (logging).

GaiaEx'in MPC cüzdan mimarisi, botunun asla ham özel anahtarları işlemediği anlamına gelir — imzalama, platformun dağıtık anahtar altyapısı tarafından yönetilir. Bu, kendi cüzdan anahtarlarını yöneten botlara kıyasla güvenlik yüzeyini azaltır; o botlarda tek bir ele geçirme tüm fonları boşaltabilir. API anahtarı IP beyaz listelemesi ve HMAC kimlik doğrulama katmanıyla birleştiğinde, otomatik işlem için katmanlı savunma (defense in depth) elde edersin.

Küçük başla: minimum pozisyon büyüklüğüyle canlıya al, 48 saat izle, gerçekleşmelerin beklentilerle eşleştiğini doğrula, sonra kademeli olarak büyüt. En iyi işlem botları tek bir kodlama koşusunda değil, adım adım inşa edilir.