PAYMENT-SIGNATURE، ثم يعيد المحاولة باستخدام الطلب نفسه.
الفرق هو أن دفع الطلبات يُعد API للمنصة ويتطلب رمز حساب؛ بينما يمكن لواجهة AI API التي تستدعي x402.acedata.cloud مباشرةً استخدام X402 فقط، ولا تحتاج إلى API Token.
تحضير الطلب
انتقل إلى وحدة تحكم Ace Data Cloud، واختر الطلب الذي تحتاج إلى دفعه، وسجّل معرّف الطلب. إذا لم يكن لديك طلب بعد، يمكنك إنشاء طلب بانتظار الدفع في صفحة الباقات. يعتمد سعر الطلب على ما يظهر في الصفحة، وamount في استجابة X402 402 هو الأساس النهائي للتوقيع.
إنشاء رمز الحساب
يتطلب طلب دفع الطلب رمز حساب. افتح صفحة Token للمنصة، وأنشئ token بصيغةplatform-v1-....
تستخدم الطلبات اللاحقة:
تشغيل 402
أرسل أولًا طلبًا واحدًا دونPAYMENT-SIGNATURE:
accepts:
x402Version هي 2، وتستخدم network معرّف CAIP-2، وحقل المبلغ هو amount.
نتيجة تشغيل البرنامج لإنشاء طلب 10 Credits وتشغيل 402:
سجلات المعاملات التالية هي عينات اختبار تاريخية بموجب السياسة القديمة، وقد تم الاحتفاظ بالمبلغ وهاش المعاملة كما هما. لم تعد طلبات X402 الجديدة تقدم خصومات على طريقة الدفع؛ يرجى اعتماد amount في استجابة 402 الحالية كأساس للتوقيع والدفع.
- بعد إنشاء الطلب بنجاح، تكون حالته
Pending، ولا يوجد دفع على السلسلة في هذه المرحلة. - لم يحمل طلب
pay/الأولPAYMENT-SIGNATURE، لذا أعاد HTTP 402. - يقدّم
acceptsكلاً من BaseexactوSolanaexact، ويختار هذا الدليل Base لاحقًا. - كان السعر عند إنشاء الطلب هو
1.26، وخلال فترة سياسة خصم الدفع القديمة عبر X402، كان مبلغ التوقيع والتسوية الفعلي هو1.2USDC، الموافق لـ1200000atomic USDC.
resource هنا هو حقل يعيده الخادم ويشارك في التوقيع، ويجب على العميل ألا يعيد كتابة البروتوكول أو المسار أو معرّف الطلب فيه بنفسه.
التوقيع وإعادة المحاولة
يمكن لدفع الطلبات إعادة استخدام دوال التوقيع منخفضة المستوى في@acedatacloud/x402-client أو acedatacloud-x402. فيما يلي مثال TypeScript:
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 أن عنوان الدفع حوّل1200000atomic USDC إلى عنوان استلام المنصة، أي1.2USDC.
الاستجابة الناجحة والإيصال
بعد نجاح دفع الطلب، يكون جسم الاستجابة هو معلومات الطلب. ستحمل المنصة أيضًا settlement response بترميز Base64 في رأس الاستجابةPAYMENT-RESPONSE، وتشمل الحقول الشائعة بعد فك الترميز:
إذا كنت بحاجة إلى المطابقة، فيوصى بحفظ معرّف الطلب وعنوان محفظة الدفع و
transaction والحالة النهائية للطلب في الوقت نفسه.
ملاحظات
- يتطلب دفع الطلب رمز حساب المنصة، ولا يمكن إكماله بالاعتماد على توقيع محفظة X402 فقط.
- يستخدم
amountوحدات USDC atomic، ويمثل1200000مقدار1.2USDC. - لا تقم بتجميع عنوان الاستلام أو عنوان الأصل بنفسك؛ اعتمد على
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 التي وصلت بالفعل.
