الانتقال إلى المحتوى الرئيسي
بالإضافة إلى الدفع مباشرةً حسب طلبات API، تدعم Ace Data Cloud أيضًا دفع طلبات وحدة تحكم X402. البروتوكول الأساسي لدفع الطلبات واستدعاءات API هو نفسه: يعيد الطلب الأول 402، ويوقّع العميل PAYMENT-SIGNATURE، ثم يعيد المحاولة باستخدام الطلب نفسه. الفرق هو أن دفع الطلبات يُعد API للمنصة ويتطلب رمز حساب؛ بينما يمكن لواجهة AI API التي تستدعي x402.acedata.cloud مباشرةً استخدام X402 فقط، ولا تحتاج إلى API Token.

تحضير الطلب

انتقل إلى وحدة تحكم Ace Data Cloud، واختر الطلب الذي تحتاج إلى دفعه، وسجّل معرّف الطلب. إذا لم يكن لديك طلب بعد، يمكنك إنشاء طلب بانتظار الدفع في صفحة الباقات. يعتمد سعر الطلب على ما يظهر في الصفحة، وamount في استجابة X402 402 هو الأساس النهائي للتوقيع.

إنشاء رمز الحساب

يتطلب طلب دفع الطلب رمز حساب. افتح صفحة Token للمنصة، وأنشئ token بصيغة platform-v1-.... تستخدم الطلبات اللاحقة:
يختلف رمز الحساب عن API Token العادي. يُستخدم API Token العادي لاستهلاك رصيد API؛ بينما يُستخدم رمز الحساب لتمثيل حسابك في تشغيل موارد المنصة، مثل دفع الطلبات.

تشغيل 402

أرسل أولًا طلبًا واحدًا دون PAYMENT-SIGNATURE:
تكون حالة الإرجاع 402، وتتضمن الاستجابة accepts:
يستخدم دفع الطلبات x402 v2 الرسمي: تكون x402Version هي 2، وتستخدم network معرّف CAIP-2، وحقل المبلغ هو amount. نتيجة تشغيل البرنامج لإنشاء طلب 10 Credits وتشغيل 402:
سجلات المعاملات التالية هي عينات اختبار تاريخية بموجب السياسة القديمة، وقد تم الاحتفاظ بالمبلغ وهاش المعاملة كما هما. لم تعد طلبات X402 الجديدة تقدم خصومات على طريقة الدفع؛ يرجى اعتماد amount في استجابة 402 الحالية كأساس للتوقيع والدفع.
توضيح النتائج:
  • بعد إنشاء الطلب بنجاح، تكون حالته Pending، ولا يوجد دفع على السلسلة في هذه المرحلة.
  • لم يحمل طلب pay/ الأول PAYMENT-SIGNATURE، لذا أعاد HTTP 402.
  • يقدّم accepts كلاً من Base exact وSolana exact، ويختار هذا الدليل Base لاحقًا.
  • كان السعر عند إنشاء الطلب هو 1.26، وخلال فترة سياسة خصم الدفع القديمة عبر X402، كان مبلغ التوقيع والتسوية الفعلي هو 1.2 USDC، الموافق لـ 1200000 atomic USDC.
لاحظ أن resource هنا هو حقل يعيده الخادم ويشارك في التوقيع، ويجب على العميل ألا يعيد كتابة البروتوكول أو المسار أو معرّف الطلب فيه بنفسه.

التوقيع وإعادة المحاولة

يمكن لدفع الطلبات إعادة استخدام دوال التوقيع منخفضة المستوى في @acedatacloud/x402-client أو acedatacloud-x402. فيما يلي مثال TypeScript:
نتيجة تشغيل البرنامج بعد توقيع الطلب نفسه باستخدام Base exact وإعادة المحاولة:
نتيجة التأكيد على السلسلة:
توضيح النتيجة:
  • يشير status 200 إلى أن واجهة دفع طلبات المنصة قبلت PAYMENT-SIGNATURE هذه.
  • يشير has_x_payment_response True إلى أن رأس الاستجابة يحتوي على إيصال PAYMENT-RESPONSE بترميز Base64.
  • يشير settle_header.success=True وnetwork=base إلى أن الـ Facilitator قد أكمل تسوية Base.
  • الحالة النهائية للطلب هي Finished، وpay_way هو X402، وpay_id يكتب تجزئة معاملة السلسلة.
  • يعرض حدث Transfer على BaseScan أن عنوان الدفع حوّل 1200000 atomic USDC إلى عنوان استلام المنصة، أي 1.2 USDC.

الاستجابة الناجحة والإيصال

بعد نجاح دفع الطلب، يكون جسم الاستجابة هو معلومات الطلب. ستحمل المنصة أيضًا settlement response بترميز Base64 في رأس الاستجابة PAYMENT-RESPONSE، وتشمل الحقول الشائعة بعد فك الترميز: إذا كنت بحاجة إلى المطابقة، فيوصى بحفظ معرّف الطلب وعنوان محفظة الدفع وtransaction والحالة النهائية للطلب في الوقت نفسه.

ملاحظات

  • يتطلب دفع الطلب رمز حساب المنصة، ولا يمكن إكماله بالاعتماد على توقيع محفظة X402 فقط.
  • يستخدم amount وحدات USDC atomic، ويمثل 1200000 مقدار 1.2 USDC.
  • لا تقم بتجميع عنوان الاستلام أو عنوان الأصل بنفسك؛ اعتمد على accepts في استجابة 402.
  • إذا تم إرسال PAYMENT-SIGNATURE نفسها بشكل متكرر، فسيقوم الـ Facilitator بحماية من إعادة التشغيل وفقًا لـ nonce.

استجابة فشل الدفع

إن أول HTTP 402 لا يحمل PAYMENT-SIGNATURE هو تحدي دفع عادي، ولا يمثل فشل الدفع. لا يزال فشل التحقق أو التسوية بعد التوقيع يحتفظ بـ error النصي القياسي كحل احتياطي للتوافق، ويعيد بنية خطأ مستقرة في extensions.acedatacloud.paymentError:
يجب أن يعطي العميل الأولوية للترجمة المحلية وفقًا لـ code، وأن يعود إلى فشل الدفع العام عند وجود code غير معروف. إن charged حقل ثلاثي الحالات: لا يعيد false إلا عند الرفض الواضح قبل التسوية؛ ويعني غياب الحقل أن حالة الخصم غير معروفة، ولا يمكن تفسيره على أنه «لم يتم الخصم». بعد أن يدخل الطلب الحالي إلى Failed، لا يمكن إعادة المحاولة للطلب الأصلي؛ يرجى إنشاء طلب جديد بعد تصحيح مشكلة المحفظة. يحتفظ metadata.x402.last_error وmetadata.x402.errors في قائمة الطلبات وتفاصيلها بالمجموعة نفسها من code وstage وretryable وcharged وparams؛ ويتم حفظ النص التوضيحي العام في reason، ووقت الحدوث في timestamp. على سبيل المثال، يشير insufficient_token_balance إلى أن رصيد USDC على الشبكة المحددة غير كافٍ، ويشير invalid_signature إلى أن توقيع الدفع غير صالح؛ ولن تؤدي إعادة قراءة الطلب إلى تغييرها إلى payment_failed عام. لا تسجل أو ترسل PAYMENT-SIGNATURE الكامل، أو توقيع المحفظة، أو payload التفويض، أو تشخيصات الـ Facilitator الخام، أو استجابة RPC. لا يحتاج استكشاف دعم العملاء إلا إلى معرّف الطلب وcode الخطأ العام.

إعادة شراء ACE وحرقها لمدفوعات Base وSolana

بعد تفعيل سياسة إعادة الشراء، يتم استخدام 3% من المبلغ المستلم فعليًا من Circle USDC المؤهل على شبكة Base الرئيسية وUSDC على شبكة Solana الرئيسية لشراء ACE وحرقه، دون خصم إضافي من محفظة الدفع. يُحتسب ذلك مرة واحدة عند الشحن، ولا يُحتسب مرة أخرى عند استخدام هذه Credits لاحقًا لاستدعاء API؛ ولا تُحتسب بأثر رجعي طلبات الخصم التاريخية وطلبات السياسة القديمة تلقائيًا. تحتفظ مدفوعات Base بإيصال الدفع على سلسلة Base، بينما يتم شراء ACE وحرقه بشكل غير متزامن على Solana. تُحتسب للمدفوعات المؤهلة نسبة 3% بدقة من المبلغ المستلم فعليًا، دون حد ثابت لمبلغ إعادة الشراء لكل معاملة أو يوم؛ وقد تظل الأموال المتاحة وعروض السوق والتأكيدات على السلسلة مؤثرة في وقت الإكمال. يوفر كائن ace_burn في تفاصيل الطلب settlement_network وsettlement_transaction وexecution_network، ويوفر swap_signature وburn_signature بعد الإكمال. لا يعني Pending أو Processing أنه تم الحرق؛ فقط Completed يمثل أن الإثبات النهائي على السلسلة قد تمت مطابقته. عندما لا تكون دفعة Base قد وصلت بعد إلى التأكيد النهائي، ستنتظر إعادة الشراء التأكيد، لكن ذلك لا يؤثر في Credits التي وصلت بالفعل.