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

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

إذا كنت تريد فقط استدعاء Ace Data Cloud API، فاستخدم SDK الرسمي بالأولوية:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
عناوين المصدر المفتوح والحزم العامة: سيُكمل SDK تلقائيًا خطوات أول طلب غير موثق، وتحليل 402 Payment Required، واستدعاء payment handler، وإعادة المحاولة مع 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 وSolana.
  • accepts[].network هو معرّف CAIP-2، ويجب على العميل المطابقة وفق سلسلة CAIP-2 عند اختيار الشبكة.
  • يمكن لكل من TypeScript SDK وPython SDK معالجة 402 تلقائيًا وإكمال إعادة المحاولة المدفوعة.
  • لدى Base exact وBase upto ودفع الطلبات جميعًا عناوين explorer يمكن فتحها علنًا.
  • الحد الأقصى الموقّع لـ Base upto هو 95215 atomic USDC، بينما التسوية الفعلية هي 3 atomic USDC، مما يعكس خاصية التسوية حسب الاستخدام الفعلي في القياس اللاحق.
  • تم التحقق من Solana exact عبر HTTP 402 -> HTTP 200 ومخرجات النموذج. نظرًا لأن استعلامات RPC العامة قد تكون محدودة بالمعدل، يُوصى باستخدام Solana RPC خاص بك أو سجلات تسوية المنصة لتأكيد توقيع المعاملة عند إجراء مطابقة صارمة.

ملاحظات التكامل

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

نطاق يمكن التحقق منه علنًا

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