الانتقال إلى المحتوى الرئيسي
يستخدم Ace Data Cloud X402 حاليًا نوعين من الـ scheme: exact وupto. وهما يعالجان مشكلات فوترة مختلفة.

exact

تعني exact أنه يمكن تحديد السعر لهذا الطلب قبل دخوله إلى API الهدف. المبلغ الذي يوقّعه العميل هو مبلغ الخصم النهائي. مناسب لـ:
  • إنشاء الصور ذات السعر الثابت؛
  • إنشاء مهام الفيديو ذات السعر الثابت؛
  • واجهات API للبحث أو الأدوات ذات السعر الثابت؛
  • دفع الطلبات.
يستخدم EVM exact آلية USDC EIP-3009 TransferWithAuthorization:
يتحقق Facilitator من التوقيع والمبلغ في مرحلة /verify، ويُرسل هذا التفويض إلى السلسلة في مرحلة /settle.

upto

تعني upto أن العميل يصرّح بحد أقصى، ويقوم Ace Data Cloud بالتسوية حسب الاستخدام الفعلي بعد اكتمال الطلب، ولا يمكن أن يتجاوز الخصم الفعلي الحد الأقصى. مناسب لـ:
  • إكمالات الدردشة: يعتمد السعر النهائي على prompt tokens وcompletion tokens؛
  • الاستجابات المتدفقة: لا يُعرف طول الإخراج الحقيقي إلا بعد انتهائه؛
  • واجهات API المستقبلية للقياس اللاحق.
يستخدم upto آلية Permit2 PermitWitnessTransferFrom. لا يوقّع العميل على تحويل ثابت، بل على تفويض حد أقصى مع witness:
يمثل permitted.amount الحد الأقصى، وليس بالضرورة مبلغ الخصم النهائي. يحوّل Gateway الاستخدام الفعلي إلى amount ويمرره إلى Facilitator في مرحلة /record. لا يسمح Facilitator بالتسوية إلا عندما يكون amount <= permitted.amount. نتيجة تشغيل برنامج Base upto:
التوضيح:
  • الحد الأقصى للتفويض المُعاد في 402 هو 95215 atomic USDC، ويوقّع العميل وفقًا لهذا الحد الأقصى.
  • بعد الاستجابة الفعلية للنموذج، تمت تسوية 3 atomic USDC فقط، ويمكن التحقق من المعاملة على السلسلة في BaseScan.
  • توضح هذه النتيجة الفرق الأساسي في upto: مبلغ التوقيع هو الحد الأقصى، ويمكن أن تكون الـ settlement على السلسلة أقل من الحد الأقصى.
  • إذا تجاوز الاستخدام الفعلي الحد الأقصى، يجب أن يرفض Facilitator الـ settlement، ويحتاج العميل إلى إعادة التفويض وفق حد أقصى أعلى.
يتوفر upto حاليًا على Base فقط. عند الحاجة إلى قياس لاحق، يُرجى استخدام Base.

لماذا تحتاج إلى Permit2 approve

يقوم x402 proxy في النهاية بسحب USDC من محفظة الدفع عبر Permit2 باستخدام upto. قبل الاستخدام الأول، تحتاج محفظة الدفع إلى منح Permit2 ERC-20 allowance مرة واحدة. Python CLI:
برمجيًا:
بعد إكمال التفويض، لا يزال كل طلب يحتاج إلى توقيع envelope جديد لـ upto، لأن nonce وdeadline وwitness والحد الأقصى للمبلغ كلها مختلفة.

تسوية المبلغ الصفري

يدعم upto الحالات التي يكون فيها المبلغ الفعلي 0. على سبيل المثال، إذا لم تنجح API الهدف في إنتاج استخدام قابل للفوترة، يمكن لـ Gateway تمرير amount = "0". سيُرجع Facilitator النجاح، لكنه لن يُنشئ معاملة على السلسلة. يمكن أن يتجنب ذلك مشكلة «عدم نجاح الطلب مع استمرار خصم رسوم على السلسلة».

توصيات الاختيار

إذا لم تكن متأكدًا مما ينبغي اختياره، فاستخدم سلوك SDK الافتراضي أولًا؛ سيختار SDK payment requirement للشبكة المطابقة التي يُرجعها الخادم.

قائمة التحقق لـ Base upto

عند التكامل أو استكشاف الأخطاء وإصلاحها، يُرجى التأكد من أن المعلمات التالية تأتي من استجابة 402 نفسها، وتبقى متسقة عند توقيع العميل: الأخطاء الشائعة وطرق التعامل معها: