الانتقال إلى المحتوى الرئيسي
يشرح هذا الدليل العملية الكاملة لـ Ace Data Cloud X402 باستخدام طلب API بأقل قدر ممكن. الهدف ليس كتابة كود معقد أولًا، بل فهم: لماذا يعيد الطلب الأول 402، وما الذي يوجد داخل accepts، وكيف تجعل PAYMENT-SIGNATURE طلب API نفسه طلبًا مدفوعًا.

التحضيرات

تحتاج إلى تجهيز: لا تحتاج استدعاءات X402 إلى Ace Data Cloud API Token. لا يحمل الطلب الأول من SDK Authorization، وستعيد Gateway 402 Payment Required ومتطلبات الدفع؛ ثم يعيد SDK المحاولة تلقائيًا بعد التوقيع.

تثبيت SDK

عناوين المصدر والحزم: TypeScript:
Python:
إذا أردت استخدام Solana، تحتاج أيضًا إلى تثبيت الاعتمادات المقابلة:
اعتمادات signer الخاصة بـ Solana في إصدار Python مضمنة بالفعل في acedatacloud-x402. مخرجات التثبيت والتحقق من الاستيراد في بيئة مؤقتة نظيفة:
توضيح النتائج:
  • حزم npm وحزم PyPI كلاهما حزم منشورة فعلية، وليست أسماءً مؤقتة في الوثائق.
  • يقوم acedatacloud-x402[cli] بتثبيت CLI، ويمكن استخدام الأمر الفرعي approve-permit2 لتفويض Permit2 في سيناريوهات upto.

يعيد الطلب الأول 402

يمكنك أولًا استخدام curl لمعرفة ما الذي يعيده الطلب غير المدفوع. لن ينتج المثال التالي أي رسوم، لأنه لا يحمل PAYMENT-SIGNATURE:
سيحتوي جسم الاستجابة على مصفوفة accepts، ويكون الهيكل الشائع كما يلي:
يوضع محتوى التحدي نفسه أيضًا بصيغة base64 في ترويسة الاستجابة PAYMENT-REQUIRED، لتسهيل قراءة العميل لمتطلبات الدفع دون تحليل body. ملخص مخرجات البرنامج لطلب API إنتاجي غير مدفوع كما يلي:
توضيح النتائج:
  • لم يحمل الطلب الأول Authorization أو PAYMENT-SIGNATURE، لذلك يعيد HTTP 402 ولا ينتج رسومًا.
  • accepts هو الأساس الوحيد الموثوق للتوقيع لهذا الطلب، ويتضمن الشبكات الاختيارية، وscheme، والحد الأقصى للمبلغ، وعنوان المستلم، وعنوان الأصل.
  • network هو معرّف CAIP-2، ويجب على العميل المطابقة باستخدام سلسلة CAIP-2 عند اختيار الشبكة.
  • الحد الأقصى للمبلغ لطلب المحادثة الأدنى هذا من gpt-4o-mini هو 95215 atomic USDC، أي 0.095215 USDC.
  • يجب قراءة استجابة 402 الخاصة بكل طلب، ولا تضع مبلغ المثال في الكود التجاري بشكل ثابت.
معاني الحقول:

إكمال إعادة محاولة الدفع باستخدام SDK

فيما يلي مثال TypeScript بأقل قدر ممكن. يحدد network: 'base'، وسيختار handler payment requirement الخاص بـ Base من استجابة 402 لهذه المرة؛ بينما يبقى المبلغ الفعلي وعنوان المستلم معتمدين على accepts:
تحدث أربع خطوات خلف هذه الشفرة:
  1. ترسل SDK طلب API عاديًا، دون Authorization.
  2. تعيد Gateway 402 Payment Required وaccepts.
  3. يختار createX402PaymentHandler متطلب الدفع الخاص بـ network = 'base' ويوقّع PAYMENT-SIGNATURE.
  4. تعيد SDK محاولة الطلب باستخدام نفس جسم الطلب، وتستدعي Gateway الـ Facilitator للتحقق والتسوية قبل السماح بالوصول إلى API الهدف.

عرض القدرات التي يدعمها Facilitator

لا تعتمد X402 API على دليل الموارد. يستدعي العميل مباشرةً API المعروف، ويستخدم 402 Payment Required وaccepts المعادَين لحظيًا من ذلك الطلب باعتبارهما الأساس الوحيد للسعر والتوقيع. يوجد إعلان قدرات Facilitator في:
وهو يصف فقط /supported و/verify و/settle وشبكات الدفع المفعّلة حاليًا، ولا يسرد موارد API. عنوان Facilitator الإنتاجي لـ Ace Data Cloud هو:
يمكنك عرض الشبكات وscheme التي يدعمها:
ستسرد kinds المعادة الشبكات وscheme التي يدعمها Facilitator. عند الاستدعاء الفعلي، يظل المرجع هو accepts المعاد من API. مخرجات Facilitator /supported:
توضح النتيجة:
  • يوضح /supported أن Facilitator يمتلك قدرات التحقق والتسوية لهذه الشبكات وscheme.
  • يدعم كل من Base وSolana exact؛ بينما يتوفر upto حاليًا على Base فقط.
  • ما إذا كانت API محددة تسمح بشبكة معينة يظل خاضعًا لـ 402 accepts الخاصة بتلك API.