GaiaEx API کے ساتھ ٹریڈنگ: تصدیق، آرڈرز اور مارکیٹ ڈیٹا

GaiaEx Hyperliquid L1 پر بنایا گیا ایک وکندریت ایکسچینج ہے، اور اس کی API آپ کو پلیٹ فارم کی پیش کردہ ہر چیز تک پروگرام کے ذریعے رسائی دیتی ہے — مارکیٹ ڈیٹا، آرڈر مینجمنٹ، پوزیشن ٹریکنگ، اور حقیقی وقت میں اسٹریمنگ۔ چاہے آپ ایک ٹریڈنگ بوٹ، ایک پورٹ فولیو ڈیش بورڈ، یا ایک اپنی مرضی کا الرٹنگ نظام بنا رہے ہوں، API آپ کا داخلی نقطہ ہے۔

API دو تکمیلی پروٹوکولز میں تقسیم ہے:

• REST API — آرڈرز دینے، balances چیک کرنے، تاریخی ٹریڈز حاصل کرنے، اور API keys کے انتظام کے لیے request-response اینڈ پوائنٹس۔ REST استعمال کریں جب آپ کو کچھ کرنا ہو یا کوئی مخصوص چیز پوچھنی ہو۔
• WebSocket API — حقیقی وقت مارکیٹ ڈیٹا (ٹریڈز، آرڈر بک اپڈیٹس، ٹِکرز) اور نجی اکاؤنٹ ایونٹس (آرڈر fills، پوزیشن کی تبدیلیاں) کے لیے مستقل اسٹریمنگ کنکشنز۔ WebSocket استعمال کریں جب آپ کو کسی چیز کے ہونے کے فوراً بعد ردعمل دینا ہو۔

اندرونی طور پر، GaiaEx Hyperliquid L1 آن-چین آرڈر بک سے کنیکٹ ہوتا ہے۔ آپ کے آرڈرز deterministic ایگزیکیوشن کے ساتھ آن-چین match ہوتے ہیں، اور آپ کے فنڈز MPC (Multi-Party Computation) والٹس کے ذریعے محفوظ ہیں — یعنی کوئی واحد فریق (حتیٰ کہ GaiaEx بھی نہیں) آپ کی مکمل نجی کلید نہیں رکھتا۔ API بلاک چین کی پیچیدگی کو abstract کر دیتی ہے: آپ ایک آرڈر دینے کے لیے ایک JSON request بھیجتے ہیں، اور پلیٹ فارم L1 پر سائننگ، submission، اور تصدیق کو سنبھالتا ہے۔

REST API کا base URL معیاری روایات کی پیروی کرتا ہے: https://api.gaiaex.com/v1/۔ WebSocket کنکشنز wss://api.gaiaex.com/ws/v1/ پر قائم ہوتے ہیں۔ تمام اینڈ پوائنٹس JSON واپس کرتے ہیں، تمام timestamps epoch سے ملی سیکنڈز میں ہیں (UTC)، اور تمام مالیاتی قدریں strings ہیں تاکہ floating-point precision کے مسائل سے بچا جا سکے۔

نجی اینڈ پوائنٹس تک رسائی حاصل کرنے کے لیے (آرڈرز دینا، اپنی balances چیک کرنا)، آپ کو ایک API key جوڑی درکار ہے۔ GaiaEx ڈیش بورڈ سے Settings → API Keys کے تحت ایک بنائیں۔ آپ کو دو قدریں ملیں گی:

• API Key — ہر request کے ساتھ بھیجا گیا ایک عوامی شناخت کنندہ۔ اسے اپنے username کی طرح سمجھیں۔
• API Secret — requests پر دستخط کرنے کے لیے استعمال ہونے والی ایک نجی کلید۔ اسے کبھی شیئر نہ کریں، کبھی version control میں commit نہ کریں، کبھی ایک request header میں نہ بھیجیں۔

GaiaEx نجی requests کی توثیق کے لیے HMAC-SHA256 سائننگ استعمال کرتا ہے۔ عمل: timestamp، HTTP method، request path، اور body کو ایک واحد اسٹرنگ میں یکجا کریں، پھر اپنے secret کا استعمال کرتے ہوئے ایک 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()

timestamp کا جزو replay attacks کو روکتا ہے: سرور کوئی بھی ایسی request مسترد کر دیتا ہے جہاں timestamp سرور کے clock سے 30 سیکنڈز سے زیادہ فرق رکھتا ہو۔ یقینی بنائیں کہ آپ کی مشین کا clock NTP کے ذریعے sync ہے۔

مارکیٹ ڈیٹا اینڈ پوائنٹس عوامی ہیں — کسی توثیق کی ضرورت نہیں۔ وہ آپ کو ٹریڈنگ فیصلے کرنے کے لیے درکار خام معلومات فراہم کرتے ہیں۔

آرڈر بک — کسی مخصوص symbol کے لیے موجودہ bids اور asks واپس کرتا ہے۔ depth پیرامیٹر یہ کنٹرول کرتا ہے کہ کتنے قیمت levels واپس کیے جائیں (default 20، زیادہ سے زیادہ 100)۔

# BTC-USD آرڈر بک حاصل کریں (اوپر کے 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}")

حالیہ ٹریڈز — کسی symbol کے لیے آخری N ایگزیکیوٹ شدہ ٹریڈز واپس کرتا ہے۔ ہر ٹریڈ میں قیمت، مقدار، پہلو (آیا taker خرید رہا تھا یا بیچ رہا تھا)، اور timestamp شامل ہے۔

# آخری 50 ETH-USD ٹریڈز حاصل کریں
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 — موجودہ مارکیٹ اسٹیٹ کا خلاصہ: آخری قیمت، 24 گھنٹے کی زیادہ سے زیادہ/کم از کم، 24 گھنٹے کا والیوم، بہترین bid/ask، اور فیصد تبدیلی۔ watchlists بنانے یا اتار چڑھاؤ تلاش کرنے کے لیے مثالی۔

# تمام 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 اینڈ پوائنٹس rate-limited ہیں اور لیٹنسی متعارف کرتے ہیں؛ WebSocket اپڈیٹس اسی لمحے ڈیلیور کرتا ہے جب وہ Hyperliquid L1 پر ہوتے ہیں۔

آرڈر دینا کسی بھی ٹریڈنگ نظام میں بنیادی عمل ہے۔ GaiaEx POST /orders اینڈ پوائنٹ کے ذریعے تین آرڈر اقسام کو سپورٹ کرتا ہے:

مارکیٹ آرڈر — بہترین دستیاب قیمت پر فوری طور پر ایگزیکیوٹ کریں۔ استعمال کریں جب ایگزیکیوشن کی رفتار قیمت کی precision سے زیادہ اہمیت رکھتی ہو۔

# مارکیٹ قیمت پر 0.1 BTC خریدیں
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"Filled at {order['avgPrice']}")

لمٹ آرڈر — صرف آپ کی مقررہ قیمت پر یا اس سے بہتر پر ایگزیکیوٹ کریں۔ fill، منسوخ، یا مدت ختم ہونے تک آرڈر بک پر رہتا ہے۔

# $3,500 یا اس سے زیادہ پر 2 ETH بیچیں
order = signed_request("POST", "/orders", {
    "symbol": "ETH-USD",
    "side": "sell",
    "type": "limit",
    "price": "3500.00",
    "quantity": "2.0",
    "timeInForce": "GTC",  # Good Till Cancelled
})

اسٹاپ آرڈر — ایک مشروط آرڈر جو فعال ہو جاتا ہے جب مارکیٹ ایک trigger قیمت تک پہنچتی ہے۔ اسٹاپ-لاسز اور breakout entries کے لیے استعمال ہوتا ہے۔

# اسٹاپ-لاس: اگر قیمت $58,000 تک گر جائے تو 0.5 BTC بیچیں
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 کے ساتھ کسی symbol کے تمام کھلے آرڈرز منسوخ کریں۔ پوزیشن مینجمنٹ کے لیے، GET /positions entry قیمت، مقدار، غیر حقیقی P&L، اور لیکویڈیشن قیمت کے ساتھ تمام کھلی پوزیشنز واپس کرتا ہے۔

GaiaEx WebSocket API ایک subscribe/unsubscribe ماڈل استعمال کرتی ہے۔ کنیکٹ ہونے کے بعد، آپ subscription پیغامات بھیجتے ہیں جو یہ متعین کرتے ہیں کہ آپ کون سے چینلز وصول کرنا چاہتے ہیں۔ عوامی (مارکیٹ ڈیٹا) اور نجی (اکاؤنٹ ایونٹس) دونوں چینلز ایک ہی کنکشن پر دستیاب ہیں۔

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:
        # نجی چینلز کے لیے توثیق کریں
        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 کریں
        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 چینل جب بھی آپ کا کوئی آرڈر fill، جزوی طور پر fill، یا منسوخ ہوتا ہے، اپڈیٹس push کرتا ہے — REST اینڈ پوائنٹ کو polling کرنے کی ضرورت ختم کرتا ہے۔ account.positions چینل حقیقی وقت P&L اور مارجن اپڈیٹس اسٹریم کرتا ہے۔ عوامی مارکیٹ ڈیٹا چینلز کے ساتھ ملا کر، ایک واحد WebSocket کنکشن وہ سب کچھ فراہم کرتا ہے جو ایک ٹریڈنگ بوٹ کو چلانے کے لیے درکار ہے۔

ہمیشہ ایک heartbeat میکانزم نافذ کریں: GaiaEx وقتی طور پر ping frames بھیجتا ہے، اور آپ کے کلائنٹ کو pong frames کے ساتھ جواب دینا ضروری ہے۔ اگر 30 سیکنڈز کے اندر کوئی pong موصول نہ ہو، سرور کنکشن بند کر دیتا ہے۔ اپنی طرف سے، اگر 30 سیکنڈز تک کوئی ڈیٹا نہ آئے، فرض کریں کنکشن ختم ہو گیا ہے اور دوبارہ کنیکٹ کریں۔

آئیے سب کچھ ملا کر ایک کم سے کم مگر فعال ٹریڈنگ بوٹ بنائیں۔ بوٹ WebSocket کے ذریعے BTC-USD قیمت کی نگرانی کرتا ہے، اور جب قیمت ایک target سے نیچے گرتی ہے، یہ ایک لمٹ خرید آرڈر دیتا ہے۔ جب پوزیشن کھلی ہو اور قیمت ایک take-profit سطح سے اوپر بڑھ جائے، یہ پوزیشن بند کر دیتا ہے۔

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:
        # توثیق + subscribe (مختصر کے لیے چھوڑ دیا گیا)
        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 کال کے گرد try/except کے ساتھ error handling اور خودکار reconnection؛ عارضی ناکامیوں کے لیے exponential backoff کے ساتھ retry logic؛ ایک boolean flag کے بجائے account.positions WebSocket چینل کے ذریعے پوزیشن ٹریکنگ؛ رسک کی حدیں جو زیادہ سے زیادہ روزانہ نقصان کے بعد ٹریڈنگ روک دیتی ہیں؛ اور لاگنگ جو ہر فیصلے اور API جواب کو post-trade تجزیے کے لیے ریکارڈ کرتی ہے۔

GaiaEx کا MPC والٹ آرکیٹیکچر یعنی آپ کا بوٹ کبھی خام نجی کلیدیں نہیں سنبھالتا — سائننگ پلیٹ فارم کی distributed key انفراسٹرکچر کے ذریعے سنبھالی جاتی ہے۔ یہ ان بوٹس کے مقابلے میں سیکیورٹی کے خطرے کے علاقے کو کم کرتا ہے جو اپنی خود کی والٹ کلیدیں منظم کرتے ہیں، جہاں ایک ہی compromise تمام فنڈز خالی کر سکتا ہے۔ API key IP whitelisting اور HMAC توثیقی layer کے ساتھ ملا کر، آپ کو خودکار ٹریڈنگ کے لیے دفاع کی گہرائی ملتی ہے۔

چھوٹے سے شروع کریں: کم از کم پوزیشن سائز کے ساتھ تعینات کریں، 48 گھنٹوں کے لیے نگرانی کریں، تصدیق کریں کہ fills توقعات سے میل کھاتے ہیں، پھر بتدریج بڑھائیں۔ بہترین ٹریڈنگ بوٹس تدریجی طور پر بنائے جاتے ہیں، ایک ہی coding sprint میں نہیں۔