Blog

كيفية استخدام Coinbase API: دليل خطوة بخطوة

Rebecca Kovács

Rebecca Kovács

27 مايو 2025

كيفية استخدام Coinbase API: دليل خطوة بخطوة

تُعد Coinbase، الرائدة عالميًا في مجال تبادل الأصول الرقمية، منصة تقدم مجموعة قوية من واجهات برمجة التطبيقات (APIs). تُشكل هذه الواجهات العمود الفقري للمطورين والمتداولين الخوارزميين والمؤسسات المالية التي تسعى إلى التكامل البرمجي مع خدمات التداول والبيانات الخاصة بـ Coinbase. يقدم هذا الدليل استكشافًا تقنيًا مفصلاً لواجهة برمجة تطبيقات Coinbase Exchange، مع التركيز على التنفيذ العملي والوظائف الأساسية وأفضل ممارسات التشغيل.

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API Testing) تولد توثيق API جميل؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر معقول أكثر بكثير!
button

الإعداد الأولي والمصادقة

يبدأ التفاعل الناجح مع واجهة برمجة تطبيقات Coinbase Exchange بإعداد الحساب، وإدارة مفاتيح API بشكل آمن، وفهم دقيق لبروتوكول المصادقة.

متطلبات الحساب المسبقة وإنشاء مفتاح API

يتطلب حساب Coinbase Exchange حساب Coinbase تم التحقق منه، وعادة ما يكون حساب Coinbase Advanced Trade أو حساب مؤسسي. يتم إنشاء مفاتيح API ضمن إعدادات حسابك. تسفر هذه العملية عن ثلاثة أجزاء حيوية من المعلومات:

  1. مفتاح API: سلسلة أبجدية رقمية عامة (على سبيل المثال، k7b9f2d7e8h1g3j4) تحدد تطبيقك.
  2. سر API: سلسلة أبجدية رقمية خاصة (على سبيل المثال، S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i). يتم عرض هذا السر مرة واحدة فقط عند الإنشاء ويجب تخزينه بشكل آمن.
  3. عبارة المرور (Passphrase): بيانات اعتماد أمنية إضافية (على سبيل المثال، mySecureP@$$phr@se2024!) تقوم بإنشائها أثناء إنشاء المفتاح.

أذونات مفتاح API دقيقة، مما يسمح لك بتقييد الإجراءات (مثل، عرض فقط، تنفيذ التداول، إمكانيات السحب). التزم دائمًا بمبدأ الحد الأدنى من الامتياز.

مصادقة طلب API

تستخدم واجهة برمجة تطبيقات Coinbase Exchange آلية مصادقة قائمة على التوقيع (HMAC-SHA256) لجميع نقاط النهاية الخاصة والمصادق عليها. يتطلب كل طلب عدة رؤوس HTTP مخصصة:

يتم إنشاء التوقيع (CB-ACCESS-SIGN) عن طريق إنشاء تجزئة HMAC-SHA256 لسلسلة ما قبل التجزئة (prehash string). سلسلة ما قبل التجزئة هي سلسلة متصلة من:

  1. الطابع الزمني (كسلسلة نصية).
  2. طريقة HTTP بالأحرف الكبيرة (مثل، GET، POST).
  3. مسار الطلب (مثل، /orders، /products/BTC-USD/book).
  4. نص الطلب (لطلبات POST؛ سلسلة فارغة إذا لم يكن هناك نص).

مثال على بناء سلسلة ما قبل التجزئة (لطلب POST):

timestamp = str(time.time())
method = "POST"
request_path = "/orders"
body_json_string = '{"product_id": "BTC-USD", "side": "buy", "type": "limit", "price": "50000.00", "size": "0.1"}' // JSON string, not Python dict
prehash_string = timestamp + method + request_path + body_json_string

// The API Secret needs to be base64-decoded before being used as the HMAC key.
// secret_decoded = base64.b64decode(api_secret)
// signature = hmac.new(secret_decoded, prehash_string.encode('utf-8'), hashlib.sha256).digest()
// CB_ACCESS_SIGN = base64.b64encode(signature)

تُعد سلاسل ما قبل التجزئة التي تم إنشاؤها بشكل غير صحيح أو التناقضات في الطوابع الزمنية (تأكد من مزامنة ساعة خادمك عبر NTP) مصادر شائعة لأخطاء المصادقة (HTTP 401).

مكتبات العميل وبيئة التطوير

تقوم مكتبات العميل الرسمية والمطورة من قبل المجتمع للغات مثل Python (cbpro)، Node.js (coinbase-pro-node)، Java، وGo بتجريد تعقيدات المصادقة هذه. بدلاً من ذلك، يمكن إجراء طلبات HTTP مباشرة باستخدام أدوات مثل curl أو وحدات عميل HTTP القياسية، مما يتطلب تنفيذ عملية التوقيع يدويًا.

بيئة Sandbox للاختبار

توفر Coinbase بيئة Sandbox للتطوير والاختبار، وهي ضرورية قبل التفاعل مع الأسواق الحية.

الغرض والوظيفة

تعكس بيئة Sandbox وظائف API الإنتاجية ولكنها تستخدم أموال اختبار وبيانات سوق محاكاة. تسمح بما يلي:

الاختلافات الرئيسية عن الإنتاج

الانتقال إلى الإنتاج

تتضمن استراتيجية النشر القوية تكوينات مميزة لبيئة Sandbox والإنتاج، تختلف بشكل أساسي في بيانات اعتماد API وعناوين URL الأساسية. يعد الاختبار الشامل في بيئة Sandbox أمرًا بالغ الأهمية لمنع الأخطاء باستخدام الأموال الحقيقية.

وظائف API الأساسية: نقاط النهاية وهياكل البيانات

تنقسم واجهة برمجة التطبيقات بشكل عام إلى إدارة الحساب، واسترداد بيانات السوق، وعمليات التداول.

إدارة الحساب

نقاط النهاية للاستعلام عن حالات الحساب والسجل.

جلب أرصدة الحساب (GET /accounts)
يسترد قائمة بجميع حسابات المستخدمين (العملات الورقية والمشفرة) مع أرصدتها.
مقتطف مثال للاستجابة لحساب BTC:

{
  "id": "7532b1f0-20f4-4ba7-96f0-303b592d130f",
  "currency": "BTC",
  "balance": "0.50123456",
  "available": "0.49123456",
  "hold": "0.01000000",
  "profile_id": "your-profile-id-string"
}

balance هو المبلغ الإجمالي، وavailable هو ما يمكن استخدامه للتداول، وhold هي الأموال المحجوزة للأوامر المفتوحة.

سجل الحساب / دفتر الأستاذ (GET /accounts/{account_id}/ledger)
يوفر قائمة مقسمة على صفحات بالمعاملات (التداولات، الرسوم، التحويلات) لحساب معين.
معلمات الاستعلام النموذجية: before (مؤشر للصفحات)، after (مؤشر)، limit (الحد الأقصى 100، الافتراضي 100)، start_date، end_date.
مقتطف مثال لإدخال دفتر الأستاذ:

{
  "id": "1001874",
  "created_at": "2023-10-26T10:00:00.000Z",
  "amount": "-0.00005000",
  "balance": "0.50118456",
  "type": "fee",
  "details": {
    "order_id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "product_id": "BTC-USD",
    "trade_id": "7423736"
  }
}

نقاط نهاية بيانات السوق

الوصول إلى معلومات السوق في الوقت الفعلي والتاريخية.

المنتجات / أزواج التداول (GET /products)
يسرد جميع أزواج التداول المتاحة وخصائصها.
مقتطف مثال للمنتج (BTC-USD):

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // Minimum order size in base currency
  "base_max_size": "200.0",  // Maximum order size in base currency
  "quote_increment": "0.01", // Smallest price change unit for quote currency
  "base_increment": "0.00000001", // Smallest size change unit for base currency
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // Minimum funds for a market order in quote currency
  "max_market_funds": "1000000", // Maximum funds for a market order
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

دفاتر الأوامر (GET /products/{product_id}/book)
يسترد دفتر الأوامر الحالي لمنتج.
معلمات الاستعلام: level (1، 2، أو 3).
*   المستوى 1: أفضل سعر عرض وطلب فقط.
*   المستوى 2: قائمة مجمعة من عروض الشراء والبيع عند كل مستوى سعر. (الحد الأقصى 50 إدخالًا لكل جانب).
*   المستوى 3: دفتر الأوامر الكامل مع الأوامر الفردية غير المجمعة (يتطلب المصادقة وقد يكون لديه حدود معدل أكثر صرامة).
مقتطف مثال لدفتر أوامر المستوى 2 (BTC-USD):

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [price, size, num-orders-at-this-price]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

مؤشر المنتج (GET /products/{product_id}/ticker)
معلومات لقطة حول آخر تداول (tick)، أفضل سعر عرض/طلب، وحجم 24 ساعة.
مقتطف مثال للمؤشر (BTC-USD):

{
  "trade_id": 7423739,
  "price": "50001.50", // Last trade price
  "size": "0.005",    // Last trade size
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // 24-hour trading volume in base currency
  "time": "2023-10-26T10:06:15.234Z"
}

الأسعار التاريخية / الشموع (GET /products/{product_id}/candles)
يسترد بيانات الأسعار التاريخية (OHLCV).
معلمات الاستعلام: start (طابع زمني ISO 8601)، end (ISO 8601)، granularity (بالثواني: 60، 300، 900، 3600، 21600، 86400). الحد الأقصى 300 شمعة لكل طلب.
مثال على بيانات الشمعة (دقة ساعة واحدة):

[
  // [time, low, high, open, close, volume]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // time is Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

عمليات التداول

نقاط النهاية لوضع الأوامر وإدارتها والاستعلام عنها.

وضع الأوامر (POST /orders)
يقدم أوامر جديدة إلى محرك المطابقة.
معلمات نص الطلب الشائعة:

{
  "client_oid": "my-unique-client-order-id-001", // Optional: UUID for idempotency
  "product_id": "BTC-USD",
  "side": "buy", // "buy" or "sell"
  "type": "limit", // "limit", "market", or "stop" (stop orders are more complex)
  "price": "49500.00", // Required for limit orders
  "size": "0.0125", // Amount of base currency to buy/sell
  // "funds": "500.00", // For market buy orders: amount of quote currency to spend
  "time_in_force": "GTC", // GTC (Good 'Til Canceled), GTT (Good 'Til Time), IOC (Immediate Or Cancel), FOK (Fill Or Kill)
  // "cancel_after": "min" / "hour" / "day" (used with GTT)
  "post_only": false, // If true, order is rejected if it would immediately match (ensures maker)
  "stp": "dc" // Self-trade prevention: "dc" (Decrease and Cancel), "co" (Cancel Oldest), "cn" (Cancel Newest), "cb" (Cancel Both)
}

يعيد وضع الأمر الناجح تفاصيل الأمر بما في ذلك id المعين من قبل الخادم.

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

عمليات الملء (Fills) (GET /fills)
يسترد قائمة مقسمة على صفحات بتداولاتك المنفذة (عمليات الملء).
معلمات الاستعلام: order_id، product_id، before، after، limit.
مقتطف مثال لعملية ملء:

{
  "trade_id": 7423800,
  "product_id": "BTC-USD",
  "price": "49500.00",
  "size": "0.00500000",
  "order_id": "e4f2c1a0-f3d8-4b9b-8b7e-1f2a3c4d5e6f",
  "created_at": "2023-10-26T10:15:30.123Z",
  "liquidity": "T", // "M" for Maker, "T" for Taker
  "fee": "0.00000250", // Fee in quote currency (USD for BTC-USD) or base currency depending on API.
  "settled": true,
  "side": "buy"
}

محرك المطابقة

يقوم محرك المطابقة بمطابقة أوامر الشراء والبيع بناءً على خوارزمية أولوية السعر والوقت:

  1. أولوية السعر: يتم إعطاء الأولوية للأوامر ذات الأسعار الأكثر ملاءمة (سعر أعلى لعروض الشراء، سعر أقل لعروض البيع).
  2. أولوية الوقت: من بين الأوامر التي لها نفس السعر، يتم إعطاء الأولوية للأمر الذي تم تقديمه أولاً.

يعد فهم هذا المنطق أمرًا حيويًا لاستراتيجيات وضع الأوامر، وإدارة الانزلاق، وتحسين الرسوم.

حدود المعدل والتقييد

يخضع الوصول إلى API لحدود المعدل لضمان استقرار المنصة والاستخدام العادل.

الأنواع والتحديد

تطبق الحدود عادة لكل مفتاح API، لكل عنوان IP، ويمكن أن تختلف لكل نقطة نهاية (على سبيل المثال، نقاط النهاية الخاصة الموقعة مقابل نقاط النهاية العامة غير الموقعة). قد تكون لنقاط النهاية العامة حدود مثل 3-10 طلبات/ثانية لكل IP. غالبًا ما تكون لنقاط النهاية الخاصة (الموقعة) حدود أعلى، أيضًا لكل مفتاح API.

تتضمن استجابات API رؤوسًا تشير إلى حالة حد المعدل الحالي:

يؤدي تجاوز الحدود إلى خطأ HTTP 429 Too Many Requests.

استراتيجيات المعالجة

  1. المراقبة الاستباقية: تحقق من CB-RATELIMIT-REMAINING قبل إجراء الطلبات.
  2. الاستخدام الفعال لواجهة برمجة التطبيقات:
  1. الارتداد الأسي (Exponential Backoff): عند تلقي خطأ 429، انتظر قبل إعادة المحاولة. نفذ ارتدادًا أسيًا (على سبيل المثال، انتظر ثانية واحدة، ثم ثانيتين، 4 ثوانٍ، 8 ثوانٍ، إلخ، مع اهتزاز) لتجنب إغراق الخادم.
  2. WebSockets للبيانات في الوقت الفعلي: لتحديثات دفتر الأوامر، التداولات الحية، والمؤشرات، تكون اتصالات WebSocket أكثر كفاءة بكثير من استطلاع REST.

التميز التشغيلي: مبادئ دليل التشغيل

تُعد الممارسات التشغيلية القوية حاسمة لأي تكامل لواجهة برمجة تطبيقات التداول.

المراقبة والتنبيه

التسجيل

سجل المعلومات الأساسية لتصحيح الأخطاء والتدقيق:

أفضل ممارسات الأمان

مواضيع وتقنيات متقدمة

موجزات WebSocket للبيانات في الوقت الفعلي

توفر Coinbase Exchange موجزات WebSocket للحصول على بيانات في الوقت الفعلي بزمن استجابة منخفض.

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // For Level 2 order book updates
        "heartbeat", // To keep connection alive and monitor status
        {
            "name": "ticker", // Ticker channel for specific products
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // For updates on product trading statuses
    ],
    // For user-specific updates (orders, balances), authentication is required within the WebSocket handshake or initial messages.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." (if auth needed for certain channels)
}

أنواع الرسائل:

الاستبقاء على نفس الحالة (Idempotency) وclient_oid

لمنع تكرار تقديم الأوامر بسبب مشكلات الشبكة أو إعادة المحاولة، يمكن أن تتضمن طلبات POST /orders حقل client_oid. يجب أن يكون هذا معرفًا فريدًا (على سبيل المثال، UUID v4) يتم إنشاؤه بواسطة عميلك.

منع التداول الذاتي (STP)

تساعد معلمة stp في وضع الأمر (POST /orders) على منع أوامر حساب ما من التطابق مع بعضها البعض. تشمل الخيارات عادةً:

الخلاصة

توفر واجهة برمجة تطبيقات Coinbase Exchange مجموعة أدوات شاملة للمطورين لبناء تطبيقات وتكاملات تداول متطورة. إتقان مصادقتها، فهم هياكل بياناتها، احترام حدود المعدل، وتطبيق ممارسات تشغيلية قوية هي مفاتيح للاستفادة من إمكانياتها الكاملة. الانتقال نحو موجزات WebSocket للبيانات في الوقت الفعلي وميزات مثل client_oid للاستبقاء على نفس الحالة يزيد من تمكين المطورين لإنشاء أنظمة مرنة وفعالة في عالم تداول العملات المشفرة سريع الوتيرة. يعد الاهتمام المستمر بوثائق المطورين الرسمية لـ Coinbase أمرًا حاسمًا للبقاء على اطلاع دائم بالميزات الجديدة، تغييرات نقاط النهاية، وأفضل الممارسات.

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل