كيفية استخدام Kraken API: دليل شامل للتداول

تخيل أن يكون لديك وصول إلى واحدة من أكثر بورصات العملات المشفرة سيولة في العالم عبر واجهة برمجة تطبيقات (API) مجربة وموثوقة تدير عقود العقود الآجلة والتداول الفوري. يوفر كراكن (Kraken) ذلك تمامًا، حيث يقدم واجهات WebSocket و REST لبورصة تأسست في عام 2011 وتخدم أكثر من 10 ملايين مستخدم في 190 دولة بسيولة واسعة في أكثر من 200 زوج تداول.

تنقسم واجهات برمجة تطبيقات تداول العملات المشفرة إلى فئتين: تلك المصممة لراحة المتداولين الأفراد وتلك المصممة للموثوقية المؤسسية. تعطي العديد من البورصات الأولوية لتطبيقات الجوال على استقرار واجهة برمجة التطبيقات، مما يؤدي إلى حدود معدل تضييق الخناق على الاستراتيجيات الخوارزمية وتوثيق يتأخر عن إصدارات الميزات. يزيل كراكن هذه النقاط الاحتكاكية من خلال تقديم وصول متعدد المستويات لواجهة برمجة التطبيقات بناءً على حجم التداول، وبيئات اختبار (sandbox) شاملة، ونقاط نهاية مخصصة للمتداولين ذوي التردد العالي. يمكنك بناء استراتيجيات آلية تتوسع من نصوص هواة إلى أنظمة على مستوى المؤسسات.

جدول المحتويات:

• فهم بنية واجهة برمجة تطبيقات كراكن (Kraken API Architecture)
• المصادقة وإعداد مفتاح واجهة برمجة التطبيقات (API Key)
• التداول الفوري باستخدام واجهة برمجة تطبيقات REST
• البيانات في الوقت الفعلي باستخدام WebSocket
• تداول العقود الآجلة والميزات المتقدمة
• الخلاصة

فهم بنية واجهة برمجة تطبيقات كراكن (Kraken API Architecture)

تدير كراكن (Kraken) ثلاثة أنظمة بيئية مميزة لواجهة برمجة التطبيقات: Spot REST، و Futures REST، و WebSocket. يساعدك فهم هذه البنى على اختيار مسار التكامل الصحيح.

واجهة برمجة تطبيقات Spot REST

توفر واجهة برمجة تطبيقات Spot REST الوصول إلى وظائف التبادل الأساسية لكراكن. وهي منظمة في نقاط نهاية عامة (بيانات السوق، معلومات المؤشر، عمق دفتر الأوامر) ونقاط نهاية خاصة (رصيد الحساب، إدارة الأوامر، التمويل). تستخدم جميع الطلبات بروتوكول HTTPS مع TLS 1.2 أو أعلى.

عنوان URL الأساسي: https://api.kraken.com/0

لا تتطلب نقاط النهاية العامة المصادقة. تستخدم نقاط النهاية الخاصة توقيع طلب HMAC-SHA512 باستخدام مفاتيح API. تختلف تنسيقات الاستجابة - فبعض نقاط النهاية ترجع مصفوفات يكون العنصر الأول فيها عبارة عن سلسلة خطأ (تصميم قديم)، بينما تستخدم نقاط النهاية الأحدث كائنات JSON قياسية.

واجهة برمجة تطبيقات Futures REST

تعمل عقود كراكن الآجلة (Kraken Futures) بشكل منفصل عن التداول الفوري ببنيتها التحتية الخاصة بواجهة برمجة التطبيقات. وهي تدعم العقود الآجلة الدائمة والعقود الآجلة ذات الأجل الثابت على العملات المشفرة برافعة مالية تصل إلى 50x.

عناوين URL الأساسية:

• الإنتاج: https://futures.kraken.com/api/v3
• بيئة الاختبار (Sandbox): https://demo-futures.kraken.com/api/v3

تستخدم واجهة برمجة تطبيقات العقود الآجلة آليات مصادقة وهياكل نقاط نهاية مختلفة مقارنةً بالتداول الفوري. تحتاج إلى مفاتيح API منفصلة يتم إنشاؤها على futures.kraken.com، وتكون مميزة عن بيانات اعتماد التداول الفوري الخاصة بك.

واجهة برمجة تطبيقات WebSocket

توفر كراكن تدفقات بيانات في الوقت الفعلي من خلال خادمي WebSocket:

• عام (Public): wss://ws.kraken.com — بيانات السوق، دفاتر الأوامر، التداولات
• خاص (Private): wss://ws-auth.kraken.com — تحديثات الحساب، حالة الأوامر، تغييرات الرصيد

على عكس استقصاء REST، تدفع اتصالات WebSocket البيانات فور توفرها، مما يقلل زمن الوصول من مئات المللي ثانية إلى عشرات المللي ثانية. لا يتطلب الخادم العام مصادقة؛ بينما يتطلب الخادم الخاص رمز WebSocket يتم الحصول عليه عبر واجهة برمجة تطبيقات REST.

حدود المعدل (Rate Limiting)

تطبق كراكن حدود معدل تعتمد على المستويات:

• المبتدئ (Starter): 60 طلبًا في الدقيقة (عام)، 30 طلبًا في الدقيقة (خاص)
• المتوسط (Intermediate): 125 طلبًا في الدقيقة (عام)، 60 طلبًا في الدقيقة (خاص)
• المحترف (Pro): أكثر من 250 طلبًا في الدقيقة بناءً على حجم التداول لمدة 30 يومًا

تؤدي تجاوز هذه الحدود إلى أخطاء HTTP 429 مع رؤوس Retry-After التي تشير إلى متى يمكنك استئناف الطلبات.

المصادقة وإعداد مفتاح واجهة برمجة التطبيقات (API Key)

تستخدم كراكن مصادقة HMAC-SHA512 مع حماية ضد إعادة الهجوم (replay protection) تعتمد على النونس (nonce). يتطلب هذا تنفيذًا دقيقًا لتجنب أخطاء "nonce غير صالح" الشائعة في التطبيقات متعددة الخيوط.

إنشاء مفاتيح واجهة برمجة التطبيقات (API Keys)

انتقل إلى الحساب (Account) ← الأمان (Security) ← واجهة برمجة التطبيقات (API) في لوحة تحكم كراكن الخاصة بك:

1. انقر على "إنشاء مفتاح جديد" (Generate New Key)
2. حدد الأذونات:

• استعلام (Query): قراءة رصيد الحساب، الأوامر المفتوحة، سجل التداول
• تداول (Trade): وضع وإلغاء الأوامر
• سحب (Withdraw): تحويل الأموال (استخدم بحذر)
• إيداع (Deposit): عرض عناوين وطرق الإيداع

3.  حدد قائمة عناوين IP المسموح بها (IP whitelisting) (موصى به للإنتاج)

4.  قم بتخزين مفتاح API والمفتاح الخاص (Private Key) بشكل آمن - لن تعرض كراكن المفتاح الخاص مرة أخرى أبدًا

لتداول العقود الآجلة، كرر هذه العملية على futures.kraken.com/settings/api. تستخدم بيئة الاختبار (sandbox) على demo-futures.kraken.com بيانات اعتماد منفصلة.

توقيع HMAC-SHA512 (تنفيذ يدوي)

إذا لم تكن تستخدم SDK، فقم بتطبيق المصادقة على النحو التالي:

import requests
import hmac
import hashlib
import base64
import time
import json

class KrakenAuth:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = base64.b64decode(api_secret)
        self.base_url = "https://api.kraken.com"
    
    def generate_signature(self, urlpath, data):
        # Nonce must be higher than any previous nonce used
        nonce = str(int(time.time() * 1000))
        data['nonce'] = nonce
        
        # Create message: nonce + POST data
        message = nonce + json.dumps(data, separators=(',', ':'))
        
        # Create HMAC-SHA512 signature
        signature = hmac.new(
            self.api_secret,
            urlpath.encode() + hashlib.sha256(message.encode()).digest(),
            hashlib.sha512
        ).hexdigest()
        
        return {
            'API-Key': self.api_key,
            'API-Sign': signature,
            'Content-Type': 'application/x-www-form-urlencoded'
        }, data
    
    def private_request(self, method, params=None):
        urlpath = f'/0/private/{method}'
        data = params or {}
        
        headers, signed_data = self.generate_signature(urlpath, data)
        
        response = requests.post(
            f"{self.base_url}{urlpath}",
            headers=headers,
            data=signed_data
        )
        
        return response.json()

# Usage
kraken = KrakenAuth(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_BASE64_ENCODED_PRIVATE_KEY"
)

# Get account balance
balance = kraken.private_request('Balance')
print(balance)

هام: إدارة النونس (Nonce)

يتطلب كراكن نونسًا متزايدًا بشكل صارم لكل مفتاح واجهة برمجة تطبيقات. إذا كان لديك عدة خيوط أو عمليات تستخدم نفس المفتاح، فسوف تتضارب وتولد أخطاء "EAPI:Invalid nonce". الحلول:

1. استخدم مفاتيح واجهة برمجة تطبيقات مختلفة لكل خوارزمية تداول أو خدمة
2. نفّذ مزامنة النونس عبر Redis أو قاعدة بيانات إذا كان مشاركة المفاتيح أمرًا لا مفر منه
3. استخدم طوابع زمنية بدقة الميكروثانية (اضرب وقت يونكس في 1000) لتقليل احتمالية التضارب

حزم تطوير البرامج الرسمية (SDKs)

توفر كراكن حزم تطوير برامج (SDKs) رسمية لبايثون و Node.js، بالإضافة إلى حزم تطوير برامج من المجتمع لـ Go و Rust و Julia ولغات أخرى:

# Python
pip install python-kraken-sdk

# Node.js
npm install @kraken-api/sdk

تتعامل حزم تطوير البرامج الرسمية مع المصادقة وإدارة النونس وتحليل الأخطاء تلقائيًا. استخدمها ما لم تكن لديك متطلبات محددة للتعامل المخصص مع بروتوكول HTTP.

التداول الفوري باستخدام واجهة برمجة تطبيقات REST

توفر واجهة برمجة تطبيقات Spot REST وظائف تداول شاملة من خلال نقاط نهاية موثقة جيدًا.

بيانات السوق (عامة)

استرجاع أزواج التداول المتاحة:

curl "https://api.kraken.com/0/public/AssetPairs"

الحصول على معلومات المؤشر (ticker):

curl "https://api.kraken.com/0/public/Ticker?pair=XBTUSD"

تستخدم كراكن رموز أزواج غير قياسية - XBT بدلاً من BTC للبيتكوين، XXBT في بعض نقاط النهاية القديمة، ZUSD بدلاً من USD. تحقق دائمًا من رموز الأصول باستخدام نقطة نهاية AssetPairs قبل التداول.

جلب عمق دفتر الأوامر:

curl "https://api.kraken.com/0/public/Depth?pair=XBTUSD&count=10"

رصيد الحساب (خاص)

balance = kraken.private_request('Balance')
print(balance)

يستخدم تنسيق الاستجابة رموز الأصول كمفاتيح (ZUSD للدولار الأمريكي، XXBT للبيتكوين):

{
  "error": [],
  "result": {
    "ZUSD": "1000.50",
    "XXBT": "0.2500"
  }
}

وضع الأوامر

وضع أمر شراء محدد السعر (limit buy order):

order = kraken.private_request('AddOrder', {
    'pair': 'XBTUSD',
    'type': 'buy',
    'ordertype': 'limit',
    'price': '65000.00',
    'volume': '0.01',
    'oflags': 'post'  # Post-only flag
})

print(order)

تشمل أنواع الأوامر:

• market (سوق): يتم التنفيذ فوراً بأفضل سعر متاح
• limit (محدد السعر): يتم التنفيذ بسعر محدد أو أفضل
• stop-loss (وقف الخسارة): يتم تشغيل أمر سوق عندما يعبر السعر عتبة معينة
• take-profit (جني الأرباح): عكس أمر وقف الخسارة
• trailing-stop (وقف متحرك): وقف ديناميكي يتبع تحركات الأسعار

إدارة الأوامر

عرض الأوامر المفتوحة:

open_orders = kraken.private_request('OpenOrders')
print(open_orders)

إلغاء أمر:

kraken.private_request('CancelOrder', {
    'txid': 'XXXXXX-XXXXXX-XXXXXX'
})

إلغاء جميع الأوامر (إيقاف طارئ):

kraken.private_request('CancelAll')

سجل التداول

الاستعلام عن الصفقات المنفذة:

trades = kraken.private_request('TradesHistory', {
    'start': '1704067200',  # Unix timestamp
    'end': '1706659200'
})

نصيحة احترافيةApidog

البيانات في الوقت الفعلي باستخدام WebSocket

يسبب استقصاء REST زمن وصول غير مقبول للتداول الخوارزمي. تقوم واجهة برمجة تطبيقات WebSocket من كراكن بتدفق تحديثات دفتر الأوامر والصفقات وأحداث الحساب في الوقت الفعلي.

الاتصال بـ WebSocket العام

const WebSocket = require('ws');

const ws = new WebSocket('wss://ws.kraken.com');

ws.on('open', () => {
  console.log('Connected to Kraken public WebSocket');
  
  // Subscribe to ticker for BTC/USD
  ws.send(JSON.stringify({
    event: 'subscribe',
    pair: ['XBT/USD'],
    subscription: {
      name: 'ticker'
    }
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  
  // Ticker format: [channelID, tickerData, pair, channelName]
  if (Array.isArray(message) && message[2] === 'XBT/USD') {
    const [channelID, ticker, pair, channelName] = message;
    console.log(`BTC Price: Bid ${ticker.b[0]}, Ask ${ticker.a[0]}`);
  }
});

// Heartbeat every 30 seconds
setInterval(() => {
  ws.send(JSON.stringify({ event: 'ping' }));
}, 30000);

ترجع اشتراكات WebSocket البيانات بتنسيق مصفوفة مع معرفات قنوات رقمية. قم بربط هذه المعرفات باشتراكاتك لتوجيه البيانات بشكل صحيح.

تدفق دفتر الأوامر

اشترك في بيانات دفتر الأوامر من المستوى 2:

ws.send(JSON.stringify({
  event: 'subscribe',
  pair: ['XBT/USD'],
  subscription: {
    name: 'book',
    depth: 25  // 25, 100, 500, or 1000 levels
  }
}));

يرسل تغذية دفتر الأوامر لقطات متبوعة بتحديثات تزايدية. حافظ على حالة دفتر الأوامر المحلي عن طريق تطبيق الفروقات (deltas):

let orderBook = { asks: {}, bids: {} };

ws.on('message', (data) => {
  const message = JSON.parse(data);
  
  if (message[1] === 'as' || message[1] === 'bs') {
    // Snapshot: initialize order book
    const [channelID, type, asks, bids] = message;
    orderBook.asks = Object.fromEntries(asks.map(([price, volume]) => [price, volume]));
    orderBook.bids = Object.fromEntries(bids.map(([price, volume]) => [price, volume]));
  } else if (message[1] === 'a' || message[1] === 'b') {
    // Update: apply delta
    const [channelID, type, delta] = message;
    const side = type === 'a' ? 'asks' : 'bids';
    
    delta.forEach(([price, volume]) => {
      if (volume === '0.00000000') {
        delete orderBook[side][price];
      } else {
        orderBook[side][price] = volume;
      }
    });
  }
});

مصادقة WebSocket الخاص

احصل على رمز WebSocket المميز عبر REST:

token_response = kraken.private_request('GetWebSocketsToken')
token = token_response['result']['token']

الاتصال بـ WebSocket الخاص:

const privateWs = new WebSocket('wss://ws-auth.kraken.com');

privateWs.on('open', () => {
  // Authenticate
  privateWs.send(JSON.stringify({
    event: 'subscribe',
    subscription: {
      name: 'ownTrades',
      token: 'YOUR_WEBSOCKET_TOKEN'
    }
  }));
});

privateWs.on('message', (data) => {
  const message = JSON.parse(data);
  
  if (message[1] === 'ownTrades') {
    console.log('Your trade executed:', message[0]);
  }
});

تنتهي صلاحية رموز WebSocket الخاصة بعد 15 دقيقة. نفّذ منطق تحديث الرمز وإعادة الاتصال تلقائيًا لأنظمة الإنتاج.

تداول العقود الآجلة والميزات المتقدمة

توفر عقود كراكن الآجلة (Kraken Futures) بنية تحتية منفصلة لتداول المشتقات بأنواع أوامر متقدمة ومرجحة المحفظة.

مصادقة العقود الآجلة

تستخدم العقود الآجلة مصادقة رمز Bearer المميز عن Spot HMAC:

import requests
import hmac
import hashlib
import base64
import json

class KrakenFuturesAuth:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = "https://futures.kraken.com/api/v3"
    
    def generate_signature(self, endpoint, method, body=None):
        nonce = str(int(time.time() * 1000))
        message = endpoint + method + nonce
        
        if body:
            message += json.dumps(body, separators=(',', ':'))
        
        signature = base64.b64encode(
            hmac.new(
                base64.b64decode(self.api_secret),
                message.encode(),
                hashlib.sha256
            ).digest()
        ).decode()
        
        return {
            'APIKey': self.api_key,
            'Nonce': nonce,
            'Authent': signature,
            'Content-Type': 'application/json'
        }
    
    def request(self, endpoint, method='GET', body=None):
        url = f"{self.base_url}{endpoint}"
        headers = self.generate_signature(endpoint, method, body)
        
        if method == 'GET':
            response = requests.get(url, headers=headers)
        else:
            response = requests.post(url, headers=headers, json=body)
        
        return response.json()

# Usage
futures = KrakenFuturesAuth('FUTURES_API_KEY', 'FUTURES_SECRET')

وضع أوامر العقود الآجلة

وضع أمر محدد السعر على عقود بيتكوين الدائمة:

order = futures.request('/sendorder', 'POST', {
    'orderType': 'lmt',
    'side': 'buy',
    'size': 1,
    'limitPrice': 65000,
    'symbol': 'PI_XBTUSD'  # Perpetual Inverse BTC/USD
})

تستخدم رموز العقود الآجلة اتفاقيات مختلفة:

• PI_XBTUSD: بيتكوين/دولار أمريكي عكسي دائم (Perpetual Inverse Bitcoin/USD)
• PF_ETHUSD: إيثيريوم/دولار أمريكي خطي دائم (Perpetual Linear Ethereum/USD)
• FI_XBTUSD_250228: عقود آجلة ثابتة الأجل تنتهي صلاحيتها في 28 فبراير 2025

عمليات الدفعة (Batch Operations)

تدعم واجهة برمجة تطبيقات العقود الآجلة تقديم أوامر مجمعة:

batch = futures.request('/batchorder', 'POST', {
    'batchOrder': [
        {
            'order': 'send',
            'order_tag': '1',
            'orderType': 'lmt',
            'symbol': 'PI_XBTUSD',
            'side': 'buy',
            'size': 1,
            'limitPrice': 64000
        },
        {
            'order': 'send',
            'order_tag': '2',
            'orderType': 'lmt',
            'symbol': 'PI_XBTUSD',
            'side': 'sell',
            'size': 1,
            'limitPrice': 66000
        }
    ]
})

ميزات الأوامر المتقدمة

• وقف الخسارة المتحرك (Trailing Stops): سعر الوقف يتكيف مع حركة السوق
• جني الأرباح / وقف الخسارة (Take Profit / Stop Loss): أوامر مجمعة لإدارة المخاطر
• للإضافة فقط (Post-Only): تضمن إضافة الأوامر للسيولة (رسوم صانع السوق)
• للتخفيض فقط (Reduce-Only): يمنع زيادة المركز

مفتاح الرجل الميت (Dead Man's Switch)

إلغاء جميع الأوامر في حالة فقدان الاتصال:

# Set 60-second timeout
kraken.private_request('CancelAllOrdersAfter', {
    'timeout': 60
})

يقوم هذا بإنشاء مؤقت من جانب الخادم - إذا لم ترسل إشارة "نبض قلب" (heartbeat) في غضون 60 ثانية، فإن كراكن تلغي جميع الأوامر المفتوحة تلقائيًا.

الخلاصة

توفر واجهة برمجة تطبيقات كراكن وصولًا على مستوى المؤسسات إلى أسواق العملات المشفرة من خلال واجهات REST و WebSocket والعقود الآجلة المخصصة. يمكنك المصادقة باستخدام توقيعات HMAC-SHA512، وإدارة تسلسلات النونس بعناية، والتوسع من التداول الفوري إلى العقود الآجلة ذات الرافعة المالية. تتسع حدود المعدل المتدرجة لاستراتيجيات تتراوح من إعادة توازن المحفظة العرضية إلى صناعة السوق عالية التردد.

ابدأ ببيئة الاختبار (sandbox) لاختبار المصادقة ووضع الأوامر. استخدم مفاتيح واجهة برمجة تطبيقات منفصلة لكل استراتيجية تداول لتجنب تعارضات النونس. نفّذ اتصالات WebSocket للبيانات في الوقت الفعلي ومفاتيح "الرجل الميت" لإدارة المخاطر. راقب رؤوس حدود المعدل ونفّذ التراجع الأسي (exponential backoff) لأخطاء 429.

عند بناء تطبيقات تداول العملات المشفرة - سواء كنت تختبر نقاط نهاية كراكن، أو تصحح أخطاء توقيعات المصادقة، أو تدير عمليات تكامل متعددة لواجهات برمجة التطبيقات - قم بتبسيط سير عمل التطوير الخاص بك باستخدام Apidog. فهو يتعامل مع اختبار واجهة برمجة التطبيقات المرئي، وإنشاء التوثيق التلقائي، والتعاون الجماعي حتى تتمكن من التركيز على منطق التداول بدلاً من المعاناة مع توقيعات HMAC.