الانتقال إلى المحتوى الرئيسي
Facilitator هو مكوّن التسوية من جانب الخادم في مسار X402. العميل مسؤول عن التوقيع، وGateway أو خادمك مسؤول عن استدعاء /verify و/settle الخاصين بـ Facilitator. عنوان Facilitator الإنتاجي لـ Ace Data Cloud هو:
مستودع الشفرة المصدرية: https://github.com/AceDataCloud/FacilitatorX402

اتفاقية wire للإصدار v2

يستخدم مسار X402 الخاص بـ Ace Data Cloud بالكامل الآن x402 v2 الرسمي، ولم يعد يقبل ترويسة الطلب X-Payment الخاصة بـ v1. هناك ثلاث نقاط يجب الانتباه إليها عند التكامل:
  • ترويسة الطلب هي PAYMENT-SIGNATURE، وقيمتها هي JSON envelope مرمّز بـ base64.
  • يجب أن يحتوي المستوى الأعلى من envelope على x402Version: 2، وأن يستخدم كائن accepted لتعريف scheme وnetwork المختارين لهذه المرة.
  • يستخدم network معرّف CAIP-2 (مثل eip155:8453)، ولا يمكن كتابة اختصارات مثل base.
بنية envelope:
بالإضافة إلى JSON body، سيحمل رد 402 أيضاً ترويسة استجابة PAYMENT-REQUIRED، وقيمتها هي ترميز base64 لنفس محتوى التحدي، لتسهيل قراءة متطلبات الدفع على العميل دون تحليل body.

الواجهات الأساسية

GET /supported

عرض الشبكات وscheme المدعومة:
مثال على الرد:
شرح النتائج:
  • يستخدم network معرّف CAIP-2، وليس اختصارات مثل base أو solana.
  • يشير /supported إلى أن Facilitator يمتلك قدرة التحقق والتسوية المقابلة.
  • يدعم كل من Base وSolana exact؛ أما upto فيتوفر حالياً على Base فقط.
  • signers هي العناوين التي يستخدمها Facilitator لإرسال معاملات التسوية.
  • ما إذا كانت API محددة تسمح بهذه الخيارات يظل خاضعاً لـ accepts في 402 الخاص بتلك API.

POST /verify

التحقق مما إذا كان PAYMENT-SIGNATURE المرسل من العميل يفي بمتطلب دفع معين. نص الطلب:
حقول paymentRequirements في v2 هي scheme وnetwork وasset وamount وpayTo وmaxTimeoutSeconds وextra، وحقل المبلغ هو amount. ستعيد accepts[] في استجابة API 402 أيضاً maxAmountRequired إضافياً ليقرأ العميل الحد الأعلى، لكنه لا ينتمي إلى حقول نص طلب Facilitator. رد النجاح:
بعد فك ترميز ترويسة الاستجابة PAYMENT-RESPONSE الخاصة بدفع طلب الإنتاج، فإنها تحتوي على نتيجة settlement. نتيجة تشغيل البرنامج لدفع طلب Base:
شرح النتائج:
  • يشير success=True إلى نجاح Facilitator settlement.
  • transaction هو هاش المعاملة على السلسلة، وتُكتب قيمة الطلب pay_id بالقيمة نفسها أيضاً.
  • يمكن رؤية تحويل Base USDC بقيمة 1200000 atomic على explorer.
  • يشير errorReason=None إلى أن هذه التسوية لم تُرجع خطأً تجارياً.
يعيد فشل التحقق عادةً أيضاً HTTP 200، لكن تكون قيمة isValid هي false. ينبغي لجانب الأعمال قراءة invalidReason، بدلاً من النظر إلى رمز حالة HTTP فقط.

POST /settle

تسوية التفويض الذي تم التحقق منه بالفعل على السلسلة. نص الطلب مطابق بشكل أساسي لـ /verify. الفرق في upto هو: يُعاد كتابة paymentRequirements.amount إلى مبلغ التسوية الفعلي عند settle؛ يُسجل Facilitator حد التوقيع في مرحلة verify، ويتحقق عند settle من ألا يتجاوز المبلغ الفعلي هذا الحد. رد النجاح:
إذا كان المبلغ الفعلي لـ upto هو 0، فقد يكون transaction سلسلة فارغة، ما يشير إلى عدم الحاجة إلى إرسال معاملة على السلسلة.

كيف يستخدم Ace Data Cloud Gateway Facilitator

مسار Ace Data Cloud API Gateway هو كما يلي:
  1. يطلب العميل API للمرة الأولى، دون Authorization وPAYMENT-SIGNATURE.
  2. يحسب Gateway السعر التقديري للطلب، ويعيد 402 وaccepts.
  3. يعيد العميل المحاولة مع PAYMENT-SIGNATURE بعد التوقيع.
  4. يفك Gateway ترميز PAYMENT-SIGNATURE، ويختار payment requirement المطابق.
  5. يستدعي Gateway /verify الخاص بـ Facilitator.
  6. بعد نجاح /verify، يسمح Gateway بتمرير الطلب إلى API الهدف.
  7. بعد أن تعيد API الهدف النتيجة، يستدعي Gateway /settle الخاص بـ Facilitator في مرحلة /record.
  8. يكتب Gateway هاش المعاملة على السلسلة في metadata لسجل الاستخدام.
يقوم exact بتسوية مبلغ التوقيع في الخطوة 7؛ أما upto فيكتب amount وفقاً للاستخدام الفعلي في الخطوة 7، ثم يسوي المبلغ الفعلي.

كيفية تكامل API الخاصة بك

إذا كنت تريد أن تدعم API الخاصة بك X402، فيمكنك تنفيذها وفقاً لهذا الهيكل:
  1. جهّز paymentRequirements لكل واجهة مدفوعة، بما في ذلك الشبكة والمبلغ وعنوان المستلم وعنوان الأصل وdomain التوقيع.
  2. إذا لم يحتوي الطلب على PAYMENT-SIGNATURE، فأعد HTTP 402 وaccepts.
  3. إذا احتوى الطلب على PAYMENT-SIGNATURE، فقم بفك ترميز Base64 للحصول على paymentPayload.
  4. استدعِ Facilitator /verify.
  5. بعد نجاح التحقق، نفّذ منطق الأعمال.
  6. بعد نجاح الأعمال، استدعِ Facilitator /settle.
  7. احفظ payer وtransaction وamount وnetwork لأغراض المطابقة.
يجب أن يستخدم الخادم paymentRequirements الذي أنشأه بنفسه لاستدعاء /verify و/settle، ولا تثق بالمبلغ أو عنوان المستلم أو عنوان الأصل الذي يعيده العميل.

الحماية من إعادة التشغيل

يسجّل Facilitator قيمة nonce. لا يمكن التحقق من التفويضات ذات nonce نفسه وتسويتها بشكل متكرر. هذا يعني:
  • يجب على العميل توقيع envelope جديد لكل طلب؛
  • إذا كان /settle قد أرسل المعاملة ولكن لم يتم تأكيدها مؤقتًا، فيمكن إعادة محاولة /settle باستخدام nonce نفسه لإجراء مطابقة متكررة بشكل آمن؛
  • لا تقم بتخزين PAYMENT-SIGNATURE نفسه مؤقتًا ثم استخدامه لعدة استدعاءات API.

الأخطاء الشائعة