GaiaEx API से ट्रेडिंग: ऑथेंटिकेशन, ऑर्डर, और मार्केट डेटा

GaiaEx Hyperliquid L1 पर बना एक डिसेंट्रलाइज़्ड एक्सचेंज (DEX) है, और इसका API आपको प्लेटफॉर्म की हर सुविधा तक प्रोग्रामेटिक पहुंच देता है — मार्केट डेटा, ऑर्डर मैनेजमेंट, पोज़िशन ट्रैकिंग और रीयल-टाइम स्ट्रीमिंग। चाहे आप एक ट्रेडिंग बॉट बना रहे हों, एक पोर्टफोलियो डैशबोर्ड, या कोई कस्टम अलर्टिंग सिस्टम — API ही आपका प्रवेश द्वार है।

API को दो पूरक प्रोटोकॉल में बांटा गया है:

• REST API — ऑर्डर लगाने, बैलेंस पूछने, पुराने ट्रेड निकालने, और API key मैनेज करने के लिए रिक्वेस्ट-रिस्पॉन्स एंडपॉइंट्स। जब आपको कुछ करना हो या कोई खास चीज़ मांगनी हो, तो REST का इस्तेमाल करें।
• WebSocket API — रीयल-टाइम मार्केट डेटा (ट्रेड, ऑर्डर बुक अपडेट, टिकर) और प्राइवेट अकाउंट इवेंट्स (ऑर्डर फिल, पोज़िशन बदलाव) के लिए स्थायी स्ट्रीमिंग कनेक्शन। जब आपको किसी घटना पर तुरंत रिएक्ट करना हो, तो WebSocket का इस्तेमाल करें।

अंदरखाने, GaiaEx Hyperliquid L1 के ऑन-चेन ऑर्डर बुक से जुड़ता है। आपके ऑर्डर डिटर्मिनिस्टिक एग्ज़ीक्यूशन के साथ ऑन-चेन मैच होते हैं, और आपके फंड्स MPC (मल्टी-पार्टी कम्प्यूटेशन) वॉलेट से सुरक्षित रहते हैं — यानी कोई एक पक्ष (GaiaEx भी नहीं) आपकी पूरी प्राइवेट की नहीं रखता। API ब्लॉकचेन की जटिलता को अमूर्त कर देता है: आप ऑर्डर लगाने के लिए एक JSON रिक्वेस्ट भेजते हैं, और प्लेटफॉर्म साइनिंग, सबमिशन, और L1 पर कन्फर्मेशन खुद संभाल लेता है।

REST API का बेस URL सामान्य कन्वेंशन का पालन करता है: https://api.gaiaex.com/v1/। WebSocket कनेक्शन wss://api.gaiaex.com/ws/v1/ पर स्थापित होते हैं। सभी एंडपॉइंट JSON रिटर्न करते हैं, सभी टाइमस्टैम्प epoch (UTC) से मिलीसेकंड में होते हैं, और सभी मौद्रिक मान फ्लोटिंग-पॉइंट प्रेसिज़न की गड़बड़ी से बचने के लिए स्ट्रिंग होते हैं।

प्राइवेट एंडपॉइंट्स (ऑर्डर लगाना, आपका बैलेंस पूछना) तक पहुंचने के लिए आपको एक API key जोड़ी चाहिए। इसे GaiaEx डैशबोर्ड में Settings → API Keys से जेनरेट करें। आपको दो वैल्यू मिलेंगी:

• API Key — हर रिक्वेस्ट के साथ भेजा जाने वाला एक पब्लिक आइडेंटिफायर। इसे अपने यूज़रनेम की तरह सोचें।
• API Secret — रिक्वेस्ट साइन करने के लिए इस्तेमाल होने वाली एक प्राइवेट की। इसे कभी शेयर न करें, वर्ज़न कंट्रोल में कभी कमिट न करें, किसी रिक्वेस्ट हेडर में कभी न भेजें।

GaiaEx प्राइवेट रिक्वेस्ट को ऑथेंटिकेट करने के लिए HMAC-SHA256 साइनिंग इस्तेमाल करता है। प्रोसेस: टाइमस्टैम्प, HTTP मेथड, रिक्वेस्ट पथ, और बॉडी को एक ही स्ट्रिंग में जोड़ें, फिर अपनी 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()

टाइमस्टैम्प वाला हिस्सा 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: ${spread:.2f}")

Recent trades — किसी सिम्बल के आखिरी 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"Average of last 50 trades: ${avg_price:.2f}")

Ticker — मौजूदा मार्केट स्टेट का सारांश: लास्ट प्राइस, 24h high/low, 24h वॉल्यूम, बेस्ट बिड/आस्क, और पर्सेंटेज बदलाव। वॉचलिस्ट बनाने या वोलैटिलिटी स्कैन करने के लिए आदर्श।

# सभी टिकर फेच करें
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 फीड इस्तेमाल करें। REST एंडपॉइंट रेट-लिमिटेड हैं और लेटेंसी बढ़ाते हैं; WebSocket Hyperliquid L1 पर जिस पल घटना होती है, उसी पल अपडेट डिलीवर करता है।

किसी भी ट्रेडिंग सिस्टम में ऑर्डर प्लेसमेंट मूल एक्शन है। GaiaEx POST /orders एंडपॉइंट के ज़रिए तीन ऑर्डर टाइप सपोर्ट करता है:

Market order — तुरंत उपलब्ध सबसे अच्छे प्राइस पर एग्ज़ीक्यूट करें। इसका उपयोग तब करें जब प्राइस प्रेसिज़न से ज़्यादा एग्ज़ीक्यूशन की स्पीड मायने रखे।

# मार्केट प्राइस पर 0.1 BTC खरीदें
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"Filled at {order['avgPrice']}")

Limit order — केवल आपके तय किए प्राइस या उससे बेहतर पर एग्ज़ीक्यूट करें। फिल होने, कैंसल होने, या एक्सपायर होने तक ऑर्डर बुक पर रहता है।

# $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
})

Stop order — एक कंडीशनल ऑर्डर जो मार्केट के ट्रिगर प्राइस तक पहुंचने पर एक्टिव हो जाता है। स्टॉप-लॉस और ब्रेकआउट एंट्री के लिए इस्तेमाल होता है।

# स्टॉप-लॉस: प्राइस $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 से कैंसल करें। पोज़िशन मैनेजमेंट के लिए, GET /positions एंट्री प्राइस, क्वांटिटी, अनरियलाइज़्ड 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,
        }))

        # पब्लिक + प्राइवेट चैनल सब्सक्राइब करें
        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 फ्रेम से जवाब देना चाहिए। अगर 30 सेकंड के भीतर कोई pong नहीं मिलता, तो सर्वर कनेक्शन बंद कर देता है। आपकी ओर से, अगर 30 सेकंड तक कोई डेटा न आए, तो मान लें कि कनेक्शन बंद हो गया है और फिर से कनेक्ट करें।

चलिए सब कुछ जोड़कर एक न्यूनतम पर काम करने वाला ट्रेडिंग बॉट बनाते हैं। यह बॉट WebSocket के ज़रिए BTC-USD प्राइस मॉनिटर करता है, और जब प्राइस किसी टार्गेट से नीचे गिरता है, तो एक लिमिट बाय ऑर्डर लगाता है। जब पोज़िशन ओपन हो और प्राइस टेक-प्रॉफिट लेवल से ऊपर उठे, तो यह पोज़िशन बंद कर देता है।

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"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 और ऑटोमेटिक रीकनेक्शन के साथ एरर हैंडलिंग; अस्थायी विफलताओं के लिए एक्सपोनेंशियल बैकऑफ के साथ रीट्राई लॉजिक; एक बूलियन फ्लैग के बजाय account.positions WebSocket चैनल के ज़रिए पोज़िशन ट्रैकिंग; अधिकतम दैनिक नुकसान के बाद ट्रेडिंग रोकने वाली रिस्क लिमिट; और पोस्ट-ट्रेड विश्लेषण के लिए हर फैसले और API रिस्पॉन्स को रिकॉर्ड करने वाला लॉगिंग।

GaiaEx के MPC वॉलेट आर्किटेक्चर का मतलब है कि आपका बॉट कभी रॉ प्राइवेट की नहीं संभालता — साइनिंग प्लेटफॉर्म के डिस्ट्रिब्यूटेड की इंफ्रास्ट्रक्चर से होती है। इससे उन बॉट्स की तुलना में सुरक्षा सतह घटती है जो अपनी वॉलेट की खुद मैनेज करते हैं, जहां एक ही कॉम्प्रोमाइज़ सारे फंड निकाल सकता है। API key IP whitelisting और HMAC ऑथेंटिकेशन लेयर के साथ मिलकर, आपको ऑटोमेटेड ट्रेडिंग के लिए गहराई से सुरक्षा मिलती है।

छोटे से शुरुआत करें: न्यूनतम पोज़िशन साइज़ के साथ डिप्लॉय करें, 48 घंटे मॉनिटर करें, वेरिफाई करें कि फिल आपकी उम्मीदों से मेल खाते हैं, फिर धीरे-धीरे स्केल करें। बेहतरीन ट्रेडिंग बॉट धीरे-धीरे बनाए जाते हैं, एक ही कोडिंग स्प्रिंट में नहीं।