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وBaseuptoودفع الطلبات جميعًا عناوين explorer يمكن فتحها علنًا. - الحد الأقصى الموقّع لـ Base
uptoهو95215atomic USDC، بينما التسوية الفعلية هي3atomic 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.
