التداول عبر واجهة GaiaEx البرمجية: المصادقة، الأوامر، وبيانات السوق

GaiaEx بورصة لامركزية (DEX) مبنية على Hyperliquid L1، وتمنحك واجهتها البرمجية وصولًا برمجيًا إلى كل ما تقدّمه المنصة — بيانات السوق، إدارة الأوامر، تتبّع المراكز، والبث في الوقت الحقيقي. سواء كنت تبني روبوت تداول، أو لوحة تحكم لمحفظتك، أو نظام تنبيهات مخصَّصًا، فالواجهة البرمجية هي نقطة دخولك.

تنقسم الواجهة البرمجية إلى بروتوكولين متكاملين:

• REST API — نقاط طلب-استجابة لوضع الأوامر، والاستعلام عن الأرصدة، وجلب الصفقات التاريخية، وإدارة مفاتيح الواجهة البرمجية. استخدم REST عندما تحتاج فعل شيء أو طلب معلومة محدَّدة.
• WebSocket API — اتصالات بث دائمة لبيانات السوق في الوقت الحقيقي (الصفقات، تحديثات دفتر الأوامر، الملخصات السعرية) وأحداث الحساب الخاصة (تنفيذ الأوامر، تغيّرات المراكز). استخدم WebSocket عندما تحتاج أن تتفاعل مع شيء لحظة حدوثه.

خلف الكواليس، تتصل GaiaEx بدفتر الأوامر على السلسلة الخاص بـHyperliquid L1. تُطابَق أوامرك على السلسلة بتنفيذ محدَّد (deterministic)، وتُؤمَّن أموالك بمحافظ MPC (الحوسبة متعددة الأطراف) — بمعنى أن لا طرف واحد (ولا حتى GaiaEx) يحوز مفتاحك الخاص الكامل. تُبسِّط الواجهة البرمجية تعقيد سلسلة الكتل: ترسل طلب JSON لوضع أمر، وتتولى المنصة التوقيع والإرسال والتأكيد على L1.

يتبع العنوان الأساسي لـREST API الاصطلاحات المعيارية: https://api.gaiaex.com/v1/. تُنشَأ اتصالات WebSocket على wss://api.gaiaex.com/ws/v1/. تُعيد كل النقاط استجابات JSON، وكل الطوابع الزمنية بالميلي ثانية منذ epoch (بتوقيت UTC)، وكل القيم النقدية نصوص (strings) لتجنّب مشاكل دقة الأعداد العشرية.

للوصول إلى النقاط الخاصة (وضع الأوامر، الاستعلام عن أرصدتك)، تحتاج زوج مفاتيح واجهة برمجية. أنشئ واحدًا من لوحة تحكم GaiaEx تحت الإعدادات ← مفاتيح الواجهة البرمجية. ستحصل على قيمتين:

• مفتاح الواجهة البرمجية (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.

نقاط بيانات السوق علنية — لا تحتاج مصادقة. تقدّم المعلومات الأولية التي تحتاجها لاتخاذ قرارات التداول.

دفتر الأوامر — يُعيد أوامر الشراء والبيع الحالية لرمز معيّن. يتحكم مُعامل depth بعدد مستويات السعر المُعادة (الافتراضي 20، الحد الأقصى 100).

# جلب دفتر أوامر BTC-USD (أعلى 10 مستويات)
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:.2f}")

الصفقات الأخيرة — يُعيد آخر N صفقة مُنفَّذة لرمز معيّن. تتضمّن كل صفقة السعر، والكمية، والجانب (أكان الآخذ يشتري أو يبيع)، والطابع الزمني.

# جلب آخر 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"متوسط آخر 50 صفقة: ${avg_price:.2f}")

الملخّص السعري (Ticker) — ملخّص لحالة السوق الحالية: آخر سعر، أعلى/أدنى 24 ساعة، حجم 24 ساعة، أفضل عرض/طلب، ونسبة التغيّر. مثالي لبناء قوائم متابعة أو مسح التقلب.

# جلب كل الملخّصات السعرية
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:

أمر السوق — يُنفَّذ فورًا بأفضل سعر متاح. استخدمه عندما تكون سرعة التنفيذ أهم من دقة السعر.

# شراء 0.1 BTC بسعر السوق
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"تم التنفيذ عند {order['avgPrice']}")

أمر محدد السعر (Limit) — يُنفَّذ فقط عند سعرك المحدَّد أو أفضل منه. يبقى على دفتر الأوامر حتى يُنفَّذ، أو يُلغى، أو تنتهي صلاحيته.

# بيع 2 ETH عند $3,500 أو أعلى
order = signed_request("POST", "/orders", {
    "symbol": "ETH-USD",
    "side": "sell",
    "type": "limit",
    "price": "3500.00",
    "quantity": "2.0",
    "timeInForce": "GTC",  # ساري حتى الإلغاء
})

أمر الإيقاف (Stop) — أمر مشروط يصبح فعّالًا عندما يصل السوق إلى سعر تفعيل. يُستخدَم لإيقاف الخسائر ودخول الاختراق.

# إيقاف خسارة: بيع 0.5 BTC إذا انخفض السعر إلى $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 كل المراكز المفتوحة مع سعر الدخول، والكمية، والربح والخسارة غير المحقَّق، وسعر التصفية.

تستخدم واجهة WebSocket في GaiaEx نموذج اشتراك/إلغاء اشتراك. بعد الاتصال، ترسل رسائل اشتراك تحدِّد القنوات التي تريد استلامها. تتوفّر قنوات علنية (بيانات السوق) وخاصة (أحداث الحساب) على الاتصال نفسه.

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,
        }))

        # الاشتراك في قنوات علنية + خاصة
        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"تحديث أمر: {data['status']} {data['orderId']}")
            elif ch == "trades.BTC-USD":
                print(f"صفقة: {data['price']} x {data['quantity']}")

asyncio.run(connect_gaiaex())

تدفع قناة account.orders تحديثات كل ما تعرّض أحد أوامرك للتنفيذ، أو التنفيذ الجزئي، أو الإلغاء — مما يُلغي الحاجة لاستقصاء نقطة REST. تبث قناة account.positions تحديثات الربح والخسارة والهامش في الوقت الحقيقي. مقترنًا بقنوات بيانات السوق العلنية، يوفّر اتصال 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:
        # المصادقة + الاشتراك (محذوفة للإيجاز)
        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"وُضع أمر شراء: {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"وُضع أمر بيع: {order['orderId']}")
                position_open = False

asyncio.run(trading_bot())

هذا مبسَّط عن قصد. سيُضيف روبوت إنتاجي: معالجة الأخطاء بـtry/except حول كل استدعاء واجهة برمجية وإعادة اتصال تلقائية؛ منطق إعادة المحاولة بتراجع أُسّي للفشل العابر؛ تتبّع المراكز عبر قناة WebSocket الخاصة بـaccount.positions بدلًا من علم منطقي بسيط؛ حدود مخاطر توقف التداول بعد أقصى خسارة يومية؛ وتسجيل (logging) يُسجِّل كل قرار واستجابة واجهة برمجية لتحليل ما بعد الصفقة.

تعني بنية محفظة MPC في GaiaEx أن روبوتك لا يتعامل مع المفاتيح الخاصة الخام أبدًا — يتولى التوقيع بنية المفاتيح الموزَّعة الخاصة بالمنصة. يُقلِّص هذا سطح الأمان مقارنة بالروبوتات التي تدير مفاتيح محفظتها الخاصة، حيث يمكن لاختراق واحد استنزاف كل الأموال. مقترنًا بالقائمة البيضاء لعناوين IP لمفتاح الواجهة البرمجية وطبقة مصادقة HMAC، تحصل على دفاع متعدّد الطبقات للتداول الآلي.

ابدأ صغيرًا: انشر بأصغر حجم مركز، راقب لمدة 48 ساعة، تحقّق من أن التنفيذات تطابق التوقعات، ثم توسّع تدريجيًا. أفضل روبوتات التداول تُبنى تدريجيًا، لا في جولة برمجية واحدة.