Skip to main content
X402 هو بروتوكول دفع على السلسلة يعتمد على HTTP 402 Payment Required. من خلال قدرة X402 في Ace Data Cloud، يمكن للجهة المستدعية إجراء الدفع على السلسلة مباشرة باستخدام USDC دون الحاجة لإنشاء رمز API أو شحن رصيد الحساب مسبقًا في كل طلب API. تم تنظيم هذه المجموعة من الوثائق وفقًا لترتيب الاتصال الحقيقي: أولاً قم بتشغيل طلب الحد الأدنى، ثم قم بتكامل SDK، وبعد ذلك فهم الشبكة، وخطط الفوترة، ودفع الطلبات وFacilitator. يُنصح بقراءة الجدول أدناه من الأعلى إلى الأسفل.

​
مسار التكامل الموصى به

إذا كنت ترغب فقط في استدعاء Ace Data Cloud API، يُفضل استخدام SDK الرسمي:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
عناوين المصدر العامة والحزم: سيقوم SDK تلقائيًا بإجراء الطلب الأول بدون مصادقة، وتحليل 402 Payment Required، واستدعاء معالج الدفع، وإعادة محاولة هذه الخطوات مع PAYMENT-SIGNATURE. كل ما تحتاجه هو إعداد محفظة تحتوي على USDC، واختيار الشبكة التي ترغب في استخدامها. إذا كنت ترغب في جعل API الخاص بك يدعم أيضًا تحصيل X402، فستحتاج إلى قراءة وثائق Facilitator، وفهم العلاقة بين paymentRequirements وpaymentPayload و/verify و/settle.

​
حالة الدعم

تم التحقق من Ace Data Cloud X402 في API العامة، وSDK الرسمية، وFacilitator، ومسار التسوية على السلسلة. يلخص الجدول أدناه الحالة الحالية وفقًا لأبعاد القدرات الأكثر استخدامًا عند تكامل المطورين. الناتج أدناه مخصص فقط لشرح شكل الاستجابة للمسارات التي تم التحقق منها. عند التكامل الفعلي، يرجى دائمًا الاعتماد على accepts الذي ترجع به API الحالية.
ملاحظات:
  • تم تثبيت حزم npm و PyPI في بيئة نظيفة وتم استيرادها بنجاح.
  • لم يتم دفع طلب API، مما أدى إلى إرجاع 402، وaccepts يحتوي على طرق الدفع المتاحة لـ Base و SKALE و Solana.
  • accepts[].network هو معرف CAIP-2، ويجب على العميل مطابقة الشبكة وفقًا لسلسلة CAIP-2.
  • يمكن لـ TypeScript SDK و Python SDK معالجة 402 تلقائيًا وإكمال إعادة الدفع.
  • تحتوي Base exact و SKALE exact و Base upto ودفع الطلب على عناوين مستكشف يمكن فتحها علنًا.
  • الحد الأقصى للتوقيع لـ Base upto هو 95215 USDC الذري، بينما التسوية الفعلية هي 3 USDC الذري، مما يعكس خاصية التسوية حسب الاستخدام الفعلي.
  • تم التحقق من Solana exact HTTP 402 -> HTTP 200 وإخراج النموذج. نظرًا لأن استعلامات RPC العامة قد تكون محدودة، يُنصح باستخدام RPC الخاص بـ Solana أو سجلات التسوية على الجانب المنصة لتأكيد توقيع المعاملة.

​
ملاحظات حول التكامل

عند التكامل، يجب على المطورين التركيز أولاً على متطلبات الدفع الفورية التي تم إرجاعها في الطلب الحالي، بدلاً من نسخ المبالغ أو العناوين من الوثائق:
  • accepts[].maxAmountRequired هو الحد الأقصى للمبلغ الذي يمكن توقيعه في الطلب الحالي.
  • accepts[].asset هو عقد USDC أو mint الذي سيتم استخدامه في هذا الطلب.
  • ستشارك accepts[].extra.chainId و accepts[].extra.facilitatorAddress و accepts[].extra.verifyingContract في توقيع بيانات EVM المخصصة.
  • يحتاج upto إلى أن يقوم المحفظة أولاً بتفويض USDC على السلسلة المستهدفة باستخدام Permit2؛ إذا لم يتم التفويض، سيتم إرجاع PERMIT2_ALLOWANCE_REQUIRED.
  • إذا كنت ترغب بوضوح في استخدام القياس اللاحق، يرجى تمرير preferScheme: 'upto' في TypeScript SDK، وإلا ستختار SDK أول متطلبات متاحة تم إرجاعها من الخادم تحت تلك الشبكة.

​
النطاق القابل للتحقق علنًا

يمكن التحقق من هذه النقاط العامة وسلوك SDK قبل التكامل:
  • ستعيد طلبات API التي لا تحتوي على Authorization أو PAYMENT-SIGNATURE 402 Payment Required، وaccepts في الاستجابة هو الأساس الوحيد للتوقيع في هذا الطلب.
  • يوفر كل من TypeScript SDK و Python SDK معالج دفع، حيث ستقوم طبقة النقل في SDK باستدعاء المعالج وإعادة المحاولة مرة واحدة عند تلقي 402.
  • https://facilitator.acedata.cloud/.well-known/x402: يعيد الشبكات المدعومة من Facilitator، والمخطط ونقاط النهاية للبروتوكول؛ لا يزال سعر API يعتمد على 402 الذي تم إرجاعه في الطلب المستهدف.
  • https://facilitator.acedata.cloud/supported: يعيد الشبكات والمخططات المدعومة من Facilitator.
  • يحتوي مستودع X402Client على أدوات تحقق متقدمة على السلسلة، يمكن استخدامها لتأكيد التوقيع، وإعادة المحاولة وسلوك التسوية؛ لا تحل مخرجات الأدوات محل accepts التي تم إرجاعها من API عبر الإنترنت.
upto ينتمي إلى تسوية القياس اللاحق، وهو مناسب لإكمال الدردشة، واستدعاءات النموذج، وغيرها من الاستخدامات الفعلية التي تُعرف فقط بعد الاستجابة. حاليًا، توفر Base فقط upto؛ إذا فشل التحقق من التوقيع، يرجى التحقق من معرف السلسلة، وعنوان الميسر، والمصرف، وعقد USDC، وتفويض Permit2 للتأكد من توافقها مع استجابة 402.