تتميز منصة Hyperliquid بكونها بورصة لا مركزية عالية الأداء للعقود الآجلة الدائمة، وتقدم تداولاً بزمن استجابة منخفض وميزات متقدمة للمطورين. يلجأ المطورون بشكل متكرر إلى واجهة برمجة تطبيقات Hyperliquid لأتمتة التداولات ومراقبة الأسواق وبناء تطبيقات مخصصة.
زر
تبدأ بفهم المكونات الأساسية لواجهة برمجة تطبيقات Hyperliquid. تنقسم واجهة برمجة التطبيقات إلى فئات رئيسية: واجهة برمجة تطبيقات المعلومات (Info API) للاستعلام عن بيانات السوق، وواجهة برمجة تطبيقات التداول (Exchange API) لإجراءات التداول، و WebSocket للتحديثات في الوقت الفعلي. علاوة على ذلك، تعمل حزم تطوير البرامج (SDKs) بلغات مثل Python و Node.js على تبسيط التفاعلات. كلما تقدمت، سترى كيف تؤدي التعديلات الصغيرة في معلمات الطلب إلى تحسينات كبيرة في كفاءة التنفيذ.
ما هي واجهة برمجة تطبيقات Hyperliquid؟
تتيح واجهة برمجة تطبيقات Hyperliquid الوصول البرمجي إلى بورصة العقود الدائمة اللامركزية Hyperliquid. وهي تدعم العمليات في بيئات الشبكة الرئيسية (mainnet) والشبكة التجريبية (testnet). تتصل بالشبكة الرئيسية و الشبكة التجريبية z. تستخدم واجهة برمجة التطبيقات JSON للطلبات والاستجابات، وتعتمد على HTTP POST لمعظم الإجراءات و WebSocket للاشتراكات.
يمكنك المصادقة باستخدام المفاتيح الخاصة بدلاً من مفاتيح API التقليدية في بعض الحالات، ولكن Hyperliquid توفر أيضًا محافظ API للتفويض الآمن. تعمل هذه المحافظ نيابة عن حسابك الرئيسي دون أذونات سحب، مما يعزز الأمان للتداول الآلي. على سبيل المثال، يمكنك إنشاء محفظة API من خلال تطبيق Hyperliquid، وتفويضها، واستخدام مفتاحها الخاص في نصوصك البرمجية.
بعد ذلك، ضع في اعتبارك أنواع البيانات. تستخدم واجهة برمجة التطبيقات هياكل وتعدادات محددة. يتم تحديد الأصول بواسطة فهارس من قائمة الكون (universe list)، وتستخدم جوانب الطلب قيمًا منطقية (صحيح للشراء، خطأ للبيع)، وتتضمن خيارات وقت سريان الطلب (time-in-force) "Gtc" لـ "Good 'til canceled". يمكنك استرداد هذه التفاصيل من نقاط نهاية البيانات الوصفية لضمان الدقة في طلباتك.
باستخدام هذا الأساس، تنتقل إلى إعداد بيئة التطوير الخاصة بك. يمنع التكوين الصحيح الأخطاء الشائعة ويسرع عملية التكرار.
إعداد بيئتك لواجهة برمجة تطبيقات Hyperliquid
تبدأ الإعداد باختيار لغة البرمجة الخاصة بك وتثبيت حزمة تطوير البرامج (SDK) ذات الصلة. لمستخدمي Python، توفر حزمة hyperliquid-python-sdk نقطة انطلاق قوية. قم بتثبيتها عبر pip باستخدام الأمر pip install hyperliquid-python-sdk. تتعامل هذه الحزمة مع الاتصالات والمصادقة والعمليات الشائعة.
بعد ذلك، تقوم بتكوين بيانات الاعتماد الخاصة بك. أنشئ ملف config.json يحتوي على عنوان حسابك (المفتاح العام) ومفتاحك السري (المفتاح الخاص). لأسباب أمنية، يمكنك إنشاء محفظة API مخصصة. انتقل إلى تطبيق Hyperliquid، حدد "المزيد > API"، أدخل اسمًا للمفتاح، الصق عنوان محفظتك، ثم انقر على "إنشاء". قم بتفويض محفظة API، وانسخ مفتاحها الخاص إلى ملف التكوين الخاص بك.
تستورد حزمة تطوير البرامج (SDK) الثوابت لعناوين URL، مثل constants.TESTNET_API_URL للاختبار. يمكنك تهيئة العملاء كالتالي:
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.TESTNET_API_URL, skip_ws=True)
يتخطى هذا الإعداد WebSocket مبدئيًا، ويركز على HTTP. يمكنك اختبار الاتصال عن طريق الاستعلام عن حالة المستخدم:
user_state = info.user_state("your_account_address")
print(user_state)
إذا أظهرت الاستجابة تفاصيل حسابك، فإن بيئتك تعمل بشكل صحيح. ومع ذلك، إذا واجهت أخطاء، فتحقق من مفتاحك الخاص واختيار الشبكة.
بالنسبة لـ Node.js، يمكنك استخدام حزمة @nktkas/hyperliquid. قم بتثبيتها باستخدام npm، ثم قم بإعداد وسائل النقل والعملاء باستخدام ethers لإدارة المحفظة. يمكنك تحديد isTestnet: true لتجنب استخدام الأموال الحقيقية أثناء التطوير.
أدوات مثل Apidog تكمل هذا الإعداد. يمكنك استيراد مواصفات واجهة برمجة تطبيقات Hyperliquid إلى Apidog، والمصادقة باستخدام مفاتيحك، ومحاكاة الطلبات. يكشف هذا النهج عن هياكل الاستجابة بسرعة، مما يوفر الوقت في الترميز اليدوي.
بمجرد التكوين، تنتقل إلى طرق المصادقة. تضمن المصادقة الصحيحة تنفيذ إجراءاتك بأمان.
المصادقة باستخدام واجهة برمجة تطبيقات Hyperliquid
تتم المصادقة بشكل أساسي من خلال توقيع المفتاح الخاص، حيث تعمل Hyperliquid على نظام قائم على البلوكتشين. تتعامل حزم تطوير البرامج (SDKs) مع التوقيع تلقائيًا عند توفير مثيل محفظة.
بالنسبة لاستدعاءات API المباشرة بدون حزم تطوير البرامج (SDKs)، تقوم بتوقيع الحمولات باستخدام مفتاحك الخاص. يتضمن نص الطلب قيمة عشوائية (nonce) للحماية من إعادة التشغيل، وتقوم بالنشر إلى نقاط نهاية /exchange أو /info.
تضيف محافظ API المرونة. يمكنك إنشاء واحدة بتسميتها، وربطها بعنوان محفظتك الرئيسية، وتوليد المفتاح، وتفويضها. تقوم هذه المحفظة بإجراء التداولات ولكن لا يمكنها سحب الأموال، مما يقلل المخاطر للروبوتات. في الكود، تستخدم المفتاح الخاص لمحفظة API مع تحديد عنوان الحساب الرئيسي.
يمكنك اختبار المصادقة عن طريق إرسال طلب معلومات بسيط. إذا لم تكن مصرحًا لك، فستُرجع واجهة برمجة التطبيقات خطأ مثل "المستخدم أو محفظة API غير موجودة". لإصلاح ذلك، تأكد من أن محفظتك تحتوي على حد أدنى من الضمان، مثل USDC للعقود الدائمة.
يظل الأمان أمرًا بالغ الأهمية. قم بتخزين المفاتيح في متغيرات البيئة أو الخزائن الآمنة، وقم بتدويرها بشكل دوري، وراقب أي نشاط غير عادي. مع وجود المصادقة في مكانها، يمكنك استكشاف نقاط نهاية Info API.
استكشاف نقاط نهاية Info API
توفر Info API وصولاً للقراءة فقط إلى بيانات السوق والحساب. يمكنك استخدامها لجلب البيانات الوصفية والأسعار والطلبات والمزيد، دون الحاجة إلى مصادقة للبيانات العامة.
تبدأ بنقطة نهاية meta، التي تُرجع كون الأصول والسياقات. في Node.js:
const [meta] = await infoClient.metaAndAssetCtxs();
ينتج عن هذا مصفوفة من الأصول بأسماء وفهارس ومواصفات مثل الحد الأقصى للرافعة المالية. تستخدم فهرس الأصل في طلبات التداول.
بعد ذلك، تستعلم عن الأسعار المتوسطة باستخدام allMids، التي تُرجع نقاط المنتصف الحالية لجميع الأزواج. تأتي الطلبات المفتوحة من openOrders، وتتطلب عنوانك.
تشمل نقاط النهاية الأخرى:
- userState: يسترد المراكز والهوامش والأرصدة.
- fundingHistory: يعرض معدلات التمويل بمرور الوقت.
- l2Book: يوفر دفتر أوامر المستوى 2 لعملة معينة.
ترسل طلبات POST مع نصوص JSON مثل {"type": "meta"} إلى /info. تستخدم الاستجابات هياكل متسقة، مع "data" التي تحتوي على النتائج.
يساعد Apidog هنا—يمكنك إعداد مجموعة لـ Info API، وإضافة طلبات لكل نوع، وتحديد معلمات للعملات أو العناوين. يساعد هذا التصور في فهم تدفق البيانات.
أثناء جمع البيانات، تنتقل إلى Exchange API لتنفيذ التداولات.
استخدام نقاط نهاية Exchange API للتداول
تتعامل Exchange API مع إجراءات مثل تقديم الطلبات وإلغائها وتعديلها. تقوم بمصادقة جميع الطلبات بحمولات موقعة.
تضع الطلبات بتحديد المعلمات: فهرس الأصل، الجانب، السعر، الحجم، علامة تقليل فقط (reduce-only)، والنوع (حد أو سوق). لبيع بحد:
في Elixir (من وثائق SDK):
Hyperliquid.Api.Exchange.place_order(order)
حيث يكون الطلب عبارة عن خريطة تحتوي على: a: الأصل، b: خطأ (بيع)، p: "100"، s: "0.1"، r: خطأ، t: {limit: {tif: "Gtc"}}.
تتضمن الاستجابة الحالة ومعرف الطلب في حال النجاح.
يمكنك إلغاء الطلبات باستخدام الأصل ومعرف الطلب (oid):
Hyperliquid.Api.Exchange.cancel_order(asset, oid)
للدفعات، تستخدم cancel_orders مع قائمة.
تتبع التعديلات بشكل مشابه: حدد oid والمعلمات الجديدة.
تشمل الإجراءات الأخرى تحديث الرافعة المالية:
Hyperliquid.Api.Exchange.update_leverage(asset, is_cross, leverage)
والتحويلات، مثل spot_perp_transfer لنقل الأموال بين الحسابات.
تتعامل مع الأخطاء عن طريق التحقق من حالة الاستجابة— "ok" للنجاح، وإلا تفاصيل مثل الهامش غير الكافي.
توضح الأمثلة الاستخدام العملي. على سبيل المثال، يمكنك بناء روبوت يضع أمر شراء عندما ينخفض السعر دون عتبة معينة، باستخدام معلومات للتحقق من السعر وواجهة التداول لوضع الأمر.
علاوة على ذلك، يمكنك دمج WebSocket للحصول على تحديثات في الوقت الفعلي لتعزيز الاستجابة.
دمج WebSocket لبيانات الوقت الفعلي
تتصل بـ WebSocket للحصول على تدفقات حية. استخدم wss://api.hyperliquid.xyz/ws للشبكة الرئيسية (mainnet) أو ما يعادلها في الشبكة التجريبية (testnet).
يمكنك الاشتراك عن طريق إرسال JSON: {"method": "subscribe", "subscription": {"type": "trades", "coin": "SOL"}}.
يستجيب الخادم بالتأكيد، ثم يدفع التحديثات مثل الصفقات الجديدة.
تتعامل مع مواضيع مثل دفتر الأوامر، أحداث المستخدم، والإشعارات. في حزمة Python SDK، اضبط skip_ws=False للتمكين.
تتيح لك هذه القدرة في الوقت الفعلي التفاعل فورًا مع تغيرات السوق، مثل تعديل الطلبات عند التنفيذ.
بعد تغطية نقاط النهاية، تفحص حزمة Python SDK بعمق.
الاستفادة من حزمة Python SDK الخاصة بـ Hyperliquid
تقوم حزمة Python SDK بتجريد استدعاءات API إلى فئات. تستورد Info للاستعلامات و Exchange للإجراءات.
تضع طلبًا أساسيًا مثل هذا (من الأمثلة):
أولاً، قم بتحميل التكوين:
import json
def address_and_private_key():
with open("examples/config.json") as f:
config = json.load(f)
return config["account_address"], config["secret_key"]
ثم، قم بتهيئة Exchange:
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
address, private = address_and_private_key()
exchange = Exchange(address, private, base_url=constants.TESTNET_API_URL)
ضع الطلب:
order_result = exchange.order("BTC", True, 0.02, 30000, {"limit": {"tif": "Gtc"}})
print(order_result)
يشتري هذا 0.02 BTC بسعر حد 30,000 دولار.
يمكنك توسيع هذا ليشمل ميزات متقدمة، مثل الطلبات المجمعة أو الإلغاءات.
تدعم حزمة تطوير البرامج (SDK) أيضًا عناوين الخزائن للحسابات المدارة.
تغطي الأمثلة في المستودع basic_order، user_state، والمزيد، مما يوضح سير العمل الكامل.
أثناء البناء، تدمج أفضل الممارسات لتحسين الأداء.
أفضل الممارسات لاستخدام واجهة برمجة تطبيقات Hyperliquid
تراقب حدود المعدل لتجنب التقييد—تفرض Hyperliquid حدودًا لكل عنوان IP ولكل حساب.
تستخدم الشبكة التجريبية (testnet) لجميع عمليات التطوير لمنع الخسارة المالية.
يتضمن التعامل مع الأخطاء تسجيل التفاصيل وإعادة محاولة الفشل المؤقت مع تأخير.
للتوسع، يمكنك تجميع الطلبات حيثما أمكن، مثل عمليات الإلغاء المتعددة.
يمتد الأمان إلى استخدام محافظ API ومبادئ أقل الامتيازات.
تقوم أيضًا بتحديث إصدار الكود الخاص بك مع تحديثات SDK، حيث تتبع Hyperliquid ترقيم الإصدارات الدلالي.
تساعد أدوات مثل Apidog في محاكاة الاستجابات لاختبارات الوحدة.
يأتي استكشاف الأخطاء وإصلاحها بعد ذلك عند ظهور المشاكل.
استكشاف الأخطاء الشائعة في واجهة برمجة تطبيقات Hyperliquid وإصلاحها
تواجه "هامش غير كافٍ" عندما يكون الضمان منخفضًا—قم بإيداع USDC لحل المشكلة.
إذا كان "الأصل غير موجود"، تحقق من الفهارس من البيانات الوصفية (meta).
تنبع أخطاء المصادقة من مفاتيح غير صالحة—أعد إنشاء وتفويض محافظ API.
تتطلب مشاكل الشبكة التحقق من عناوين URL واستخدام وكلاء إذا لزم الأمر.
يمكنك تصحيح الأخطاء باستخدام Apidog عن طريق إعادة تشغيل الطلبات الفاشلة.
توفر سجلات حزم تطوير البرامج (SDKs) الطوابع الزمنية والحمولات للتحليل.
باستخدام هذه النصائح، تحافظ على تكاملات موثوقة.
حالات الاستخدام المتقدمة مع واجهة برمجة تطبيقات Hyperliquid
يمكنك بناء روبوتات تداول تراقب l2Book وتضع أوامر عند وجود اختلالات.
تتضمن الاستراتيجيات معدلات التمويل من التاريخ إلى فرص المراجحة.
تتيح الحسابات الفرعية التداول المنفصل: قم بإنشاء حساب باسم، وحوّل الأموال، وتداول بشكل منفصل.
تدعم تحويلات الخزائن مجمعات السيولة المشتركة.
يمكنك المحاكاة ببيانات تاريخية من API للاختبار الخلفي.
يتيح التكامل مع Apidog تصحيح الأخطاء التعاوني في الفرق.
أخيرًا، تختتم بالنظر في التحسينات المستقبلية.
الخاتمة: إتقان واجهة برمجة تطبيقات Hyperliquid للتداول اللامركزي
أنت الآن تمتلك المعرفة اللازمة لاستخدام واجهة برمجة تطبيقات Hyperliquid بفعالية. من الإعداد والمصادقة إلى نقاط النهاية وحزم تطوير البرامج (SDKs)، يجهزك هذا الدليل لبناء تطبيقات متطورة. تذكر أن التحسينات التدريجية في التعليمات البرمجية الخاصة بك تحقق مكاسب كبيرة في الأداء. جرب على الشبكة التجريبية (testnet)، واستفد من أدوات مثل Apidog، وابقَ على اطلاع دائم بوثائق Hyperliquid. مع تطور المنصة، تضعك مهاراتك في موقع يمكنك من الاستفادة من الميزات الجديدة.
زر