كيفية استخدام Circle API: مدفوعات USDC، محافظ رقمية، وتحويلات مالية

تصدر Circle عملة USDC، ثاني أكبر عملة مستقرة من حيث القيمة السوقية، وتوفر مجموعة من واجهات برمجة التطبيقات (APIs) التي تتيح لك نقل الدولارات عبر السلسلة دون الحاجة إلى بناء بنية تحتية للحضانة أو الامتثال أو الخدمات المصرفية من الصفر. إذا أردت تسوية دفعة سوق في دقائق، أو السماح للمستخدم بالإيداع عبر البطاقة والسحب كـ USDC، أو نقل العملات المستقرة عبر ثماني سلاسل كتل بمكالمة واحدة، فإن واجهة برمجة تطبيقات Circle هي أقصر طريق لذلك. الوثائق الرسمية متوفرة على developers.circle.com، ومقدمة USDC على circle.com/en/usdc تستحق القراءة قبل البدء.

يرشدك هذا الدليل عبر جميع جوانب التطوير: إنشاء الحساب، بيئة الاختبار (sandbox) مقابل بيئة الإنتاج (production)، مصادقة رمز Bearer، نقاط نهاية المدفوعات والمدفوعات الصادرة، محافظ Circle (خدمات Web3)، بروتوكول النقل عبر السلاسل (CCTP)، نص التشفير السري للكيان للمحافظ التي يتحكم فيها المطور، الـ webhooks، مبدأ الثباتية (idempotency)، والامتثال لـ KYB. توقع مقتطفات من أوامر curl و Node يمكنك لصقها في محطتك الطرفية. قراءة ذات صلة: دليلنا حول أفضل واجهة برمجة تطبيقات (API) لربط العملات الورقية بالرقمية والعكس يقارن Circle بمنافسيها الأقرب.

💡

ستحتاج أيضًا إلى عميل واجهة برمجة تطبيقات (API) يتحدث كلاً من REST و Web3 بطلاقة أثناء عملية النمذجة الأولية. يتعامل Apidog مع مصادقة Bearer الخاصة بـ Circle، وتبديل البيئات، وإعادة تشغيل الـ webhook في مساحة عمل واحدة، بحيث يمكنك اختبار بيئة الاختبار والإنتاج جنبًا إلى جنب دون إعادة كتابة مجموعتك.

زر

ملخص سريع

واجهة برمجة تطبيقات Circle (Circle API) هي مجموعة من الخدمات: Circle Payments (البطاقات، التحويلات البنكية، ACH)، Circle Mint (إصدار USDC المؤسسي)، محافظ Circle / W3S (محافظ قابلة للبرمجة)، و CCTP (حرق-و-سك عملة USDC الأصلية عبر السلاسل).
قم بالمصادقة باستخدام رمز Bearer؛ مفاتيح بيئة الاختبار تبدأ بـ TEST_API_KEY: ومفاتيح الإنتاج بـ LIVE_API_KEY:.
تتطلب المحافظ التي يتحكم فيها المطورون نصًا مشفرًا سريًا للكيان (مشفر بـ RSA، يتم تجديده لكل طلب) لجميع عمليات الكتابة.
ينقل CCTP عملة USDC الأصلية عبر Ethereum و Arbitrum و Base و Optimism و Polygon PoS و Avalanche و Solana والمزيد عبر عملية حرق وسك معتمدة.
موافقة KYB مطلوبة للإنتاج. بيئة الاختبار مفتوحة لأي مطور.
استخدم مفاتيح الثباتية (idempotency) في كل طلب تغيير وتحقق من توقيعات الـ webhook باستخدام المفتاح العام من /notifications/publicKey/get.

ما هي واجهة برمجة تطبيقات Circle (Circle API)؟

Circle هي شركة مدفوعات منظمة تصدر عملة USDC وتدير البنى التحتية التي تحافظ على ربطها بالدولار الأمريكي. تكشف واجهة برمجة تطبيقات Circle (Circle API) عن أربعة خطوط إنتاج يمكنك دمجها ومطابقتها:

واجهة برمجة تطبيقات مدفوعات Circle (Circle Payments API) تقبل البطاقات، ACH، SEPA، والتحويلات البنكية، ثم تسوي النتيجة كـ USDC في محفظة التاجر الخاصة بك.
واجهة برمجة تطبيقات مدفوعات Circle الصادرة (Circle Payouts API) ترسل تحويلات بنكية أو ACH من رصيد USDC الخاص بك إلى أي حساب مصرفي قمت بإعداده كمستفيد.
محافظ Circle (W3S) تنشئ محافظ حراسة أو محافظ يتحكم فيها المطورون على سلاسل متعددة، وتوقع المعاملات، وتتعامل مع رسوم الغاز.
CCTP يحرق USDC على سلسلة المصدر ويصدر USDC مكافئًا على سلسلة الوجهة، لذلك تحصل على أصول أصلية، وليس غلافًا معبرًا.

إذا كنت تقارن Circle بالبنية التحتية العامة لـ Web3، فاقرأ تحليلنا حول أفضل واجهة برمجة تطبيقات لمحافظ العملات المشفرة ودليل كيفية استخدام Alchemy API لمعرفة أين تتناسب كل أداة.

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

أنشئ حسابًا على console.circle.com. توفر لك وحدة التحكم بيئتين: بيئة الاختبار (sandbox) وبيئة الإنتاج (production). بيئة الاختبار مجانية وذاتية الخدمة؛ بينما تتطلب بيئة الإنتاج موافقة "اعرف عملك" (KYB)، والتي تستغرق بضعة أيام عمل وتحتاج إلى مستندات التأسيس، ومعلومات المالك المستفيد، وحساب تمويل.

أنشئ مفتاح API ضمن المطورين ← مفاتيح API. تنسيق المفتاح هو TEST_API_KEY:<id>:<secret> في بيئة الاختبار أو LIVE_API_KEY:<id>:<secret> في بيئة الإنتاج. مرره كرمز Bearer:

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

روابط URL الأساسية:

بيئة الاختبار: https://api-sandbox.circle.com
بيئة الإنتاج: https://api.circle.com

بالنسبة للمحافظ التي يتحكم فيها المطورون في W3S، ستحتاج أيضًا إلى سر الكيان (entity secret): وهو سلسلة سداسية عشرية بطول 32 بايت تنشئها مرة واحدة وتسجلها عبر لوحة التحكم. يجب أن تتضمن كل مكالمة كتابة entitySecretCiphertext جديدًا، وهو سر الكيان المشفر بالمفتاح العام RSA الخاص بـ Circle. يقوم Node SDK بتجديده تلقائيًا؛ إذا قمت بإنشائه بنفسك، فقم بتدوير النص المشفر في كل طلب لأن Circle يرفض القيم المعاد استخدامها.

تثبيت Node SDK:

npm install @circle-fin/developer-controlled-wallets

نقاط النهاية الأساسية

إنشاء مجموعة محافظ ومحفظة

تعيش المحافظ في W3S ضمن مجموعة محافظ (wallet set) (مجموعة تتشارك في بذرة HD واحدة). أنشئ المجموعة أولاً، ثم أنشئ المحافظ داخلها.

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

تعيد كل محفظة id، و address، وسلسلة الكتل التي توجد عليها. قم بتمويلها بعملة USDC من شبكة الاختبار من صنبور Circle للاستمرار.

تحويل USDC من محفظة يتحكم فيها المطور

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC on ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

يعيد الرد id معاملة يمكنك استطلاعه عبر GET /v1/w3s/transactions/{id} أو الاستماع إليه عبر الـ webhook.

قبول دفعة بطاقة وتسويتها كـ USDC

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "buyer@example.com", "sessionId": "..." }
  }'

يجب أن تكون بيانات البطاقة مشفرة بتقنية PGP باستخدام المفتاح العام لـ Circle (يمكن الحصول عليه من /v1/encryption/public). يعيد الرد id دفعة تمر عبر pending → confirmed → paid.

إرسال دفعة صادرة عبر تحويل بنكي أو ACH

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "vendor@example.com" }
  }'

نقل USDC عبر السلاسل باستخدام CCTP

CCTP هو بروتوكول عقود ذكية، وليس نقطة نهاية REST، لذلك تقوم بدمج عملية حرق على السلسلة مع خدمة تصديق Circle:

استدعاء depositForBurn على عقد TokenMessenger على سلسلة المصدر.
استطلع https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} حتى يصبح status: "complete" وتتلقى كائن attestation سداسي عشري.
استدعاء receiveMessage على عقد MessageTransmitter على سلسلة الوجهة مع بايتات الرسالة والتصديق.

ينتهي بك المطاف بـ USDC أصلي على سلسلة الوجهة، تم سكه من لا شيء مقابل عملية حرق قابلة للتحقق. لا توجد رموز مغلفة، ولا مخاطر سيولة الجسور.

الـ Webhooks والثباتية (Idempotency)

تقوم Circle بإرسال أحداث POST (payments، payouts، transfers، chargebacks) إلى أي نقطة نهاية HTTPS تشترك فيها عبر /v1/notifications/subscriptions. يتم توقيع كل webhook بمفتاح ECDSA؛ احصل على المفتاح العام من /v1/notifications/publicKey/get وتحقق من رأس X-Circle-Signature قبل الثقة بالحمولة.

تتطلب كل نقطة نهاية قابلة للتعديل رأس Idempotency-Key (UUID v4 هو المعيار). إعادة محاولة طلب بنفس المفتاح يعيد الرد الأصلي بدلاً من إنشاء دفعة مكررة. هذا مهم: البطاقات والتحويلات البنكية لا تسامح الإرسال المزدوج.

الأخطاء الشائعة وحدود المعدل

401 غير مصرح به: رمز Bearer مفقود، أو خاطئ التنسيق، أو بيئة خاطئة.
400 نص تشفير سر الكيان غير صالح: لقد أعدت استخدام نص مشفر أو قمت بالتشفير باستخدام مفتاح عام قديم. أعد التوليد وحاول مرة أخرى.
429 طلبات كثيرة جدًا: بيئة الاختبار محدودة بحوالي 10 طلبات في الثانية لكل نقطة نهاية؛ تتناسب حدود الإنتاج مع الحجم. تراجع بشكل أسي.
أموال غير كافية: المحفظة المصدر لا تحتوي على ما يكفي من USDC، أو فشلت بطاقة المصدر في فحص AVS/CVV.

لإلقاء نظرة أوسع على البنية التحتية للبطاقات، تغطي مراجعتنا لأفضل واجهة برمجة تطبيقات لإصدار البطاقات الجهات المصدرة التي تتناسب جيدًا مع مدفوعات Circle الصادرة.

تسعير واجهة برمجة تطبيقات Circle

بيئة الاختبار مجانية. في بيئة الإنتاج، لا تفرض Circle Mint أي رسوم لسك أو استرداد USDC للعملاء المؤسسيين المعتمدين ذوي الحجم المؤهل. تأخذ Circle Payments نسبة مئوية بالإضافة إلى رسوم ثابتة لكل معاملة بطاقة (عادة 2.9% + 30 سنتًا، يتم التفاوض عليها عند الحجم الكبير). تتكلف المدفوعات الصادرة إلى التحويلات البنكية الأمريكية بضعة دولارات لكل معاملة. يتم تسعير محافظ W3S لكل محفظة ولكل معاملة؛ اتصل بالمبيعات للحصول على عرض أسعار للإنتاج. CCTP نفسه مجاني؛ تدفع رسوم الغاز لسلسلة المصدر والوجهة.

اختبار واجهة برمجة تطبيقات Circle باستخدام Apidog

تغطي واجهة Circle خدمات REST، والـ webhooks الموقعة، والعقود على السلسلة، لذلك نادرًا ما تلتقط مجموعة Postman واحدة التدفق الكامل. يقوم Apidog باستيراد مواصفات OpenAPI الخاصة بـ Circle مباشرةً، ويخزن رموز Bearer لبيئتي الاختبار والإنتاج كبيئات منفصلة، ويتيح لك كتابة نص اختبار يربط دفعة بطاقة، ودفعة صادرة، والتحقق من الـ webhook في عملية تشغيل واحدة.

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

الأسئلة الشائعة

هل أحتاج إلى KYB لاختبار واجهة برمجة تطبيقات Circle؟لا. حسابات بيئة الاختبار مفتوحة لأي شخص لديه عنوان بريد إلكتروني. تحتاج فقط إلى KYB لنقل دولارات حقيقية في بيئة الإنتاج. تأتي بيئة الاختبار مع صنابير لـ USDC على كل سلسلة مدعومة.

ما الفرق بين Circle Mint ومحافظ Circle؟Circle Mint هي بوابة دخول المؤسسات: تقوم بتحويل الدولار الأمريكي، وتحصل على USDC (والعكس صحيح). محافظ Circle / W3S هي بنية تحتية للحضانة والمعاملات للمستخدمين النهائيين. تستخدم معظم تطبيقات المستهلك المحافظ (Wallets)؛ بينما تستخدم تطبيقات الخزانة Mint مباشرةً. يغطي دليلنا كيفية استخدام MoonPay API بديلاً مخصصًا لتجار التجزئة إذا لم تكن بحاجة إلى إصدار على مستوى Mint.

كيف يتجنب CCTP مخاطر الجسور؟يتم حرق USDC الأصلي على سلسلة المصدر وسكه حديثًا على سلسلة الوجهة مقابل تصديق موقع من Circle. لا يوجد مجمع سيولة مغلق يمكن استنزافه من خلال استغلال جسر. ما زلت تثق بخدمة تصديق Circle، لكنك لا تثق بمجموعة مدققين لجسور طرف ثالث.

هل يمكنني استخدام محافظ Circle دون الاحتفاظ بالمفاتيح؟نعم. تستخدم المحافظ التي يتحكم فيها المستخدمون (User-Controlled Wallets) في W3S تقنية MPC والمصادقة المستندة إلى PIN، لذلك يقوم المستخدمون النهائيون بتفويض المعاملات عبر SDK الخاص بـ Circle ولا تلمس مفتاحًا خاصًا أبدًا. تضع المحافظ التي يتحكم فيها المطورون (Developer-Controlled Wallets) سلطة التوقيع على الواجهة الخلفية الخاصة بك عبر سر الكيان.

هل تدعم Circle سلاسل Solana والسلاسل غير المتوافقة مع EVM؟نعم. تغطي W3S سلاسل Solana و Aptos و NEAR، والعديد من طبقات EVM L2s. قامت CCTP v2 بتوسيع دعم Solana في عام 2024، لذلك تنتقل USDC الأصلية الآن بحرية بين Solana ونظام EVM البيئي.

كيف أقوم بتدوير سر الكيان بأمان؟تدعم Circle تدوير سر الكيان عبر لوحة التحكم. قم بإنشاء سر جديد، سجله، وقم بتشغيل النصين المشفرين القديم والجديد بالتوازي لفترة قصيرة من الانتقال. يقرأ SDK أي سر موجود في متغير البيئة الخاص بك، لذلك يتعامل النشر المتدحرج معه بسلاسة.