exact وupto. وهما يعالجان مشكلات فوترة مختلفة.
exact
تعني exact أنه يمكن تحديد السعر لهذا الطلب قبل دخوله إلى API الهدف. المبلغ الذي يوقّعه العميل هو مبلغ الخصم النهائي.
مناسب لـ:
- إنشاء الصور ذات السعر الثابت؛
- إنشاء مهام الفيديو ذات السعر الثابت؛
- واجهات API للبحث أو الأدوات ذات السعر الثابت؛
- دفع الطلبات.
exact آلية USDC EIP-3009 TransferWithAuthorization:
/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 هو
95215atomic USDC، ويوقّع العميل وفقًا لهذا الحد الأقصى. - بعد الاستجابة الفعلية للنموذج، تمت تسوية
3atomic USDC فقط، ويمكن التحقق من المعاملة على السلسلة في BaseScan. - توضح هذه النتيجة الفرق الأساسي في
upto: مبلغ التوقيع هو الحد الأقصى، ويمكن أن تكون الـ settlement على السلسلة أقل من الحد الأقصى. - إذا تجاوز الاستخدام الفعلي الحد الأقصى، يجب أن يرفض Facilitator الـ settlement، ويحتاج العميل إلى إعادة التفويض وفق حد أقصى أعلى.
upto حاليًا على Base فقط. عند الحاجة إلى قياس لاحق، يُرجى استخدام Base.
لماذا تحتاج إلى Permit2 approve
يقوم x402 proxy في النهاية بسحب USDC من محفظة الدفع عبر Permit2 باستخدامupto. قبل الاستخدام الأول، تحتاج محفظة الدفع إلى منح Permit2 ERC-20 allowance مرة واحدة.
Python CLI:
upto، لأن nonce وdeadline وwitness والحد الأقصى للمبلغ كلها مختلفة.
تسوية المبلغ الصفري
يدعمupto الحالات التي يكون فيها المبلغ الفعلي 0. على سبيل المثال، إذا لم تنجح API الهدف في إنتاج استخدام قابل للفوترة، يمكن لـ Gateway تمرير amount = "0". سيُرجع Facilitator النجاح، لكنه لن يُنشئ معاملة على السلسلة.
يمكن أن يتجنب ذلك مشكلة «عدم نجاح الطلب مع استمرار خصم رسوم على السلسلة».
توصيات الاختيار
إذا لم تكن متأكدًا مما ينبغي اختياره، فاستخدم سلوك SDK الافتراضي أولًا؛ سيختار SDK payment requirement للشبكة المطابقة التي يُرجعها الخادم.
قائمة التحقق لـ Base upto
عند التكامل أو استكشاف الأخطاء وإصلاحها، يُرجى التأكد من أن المعلمات التالية تأتي من استجابة 402 نفسها، وتبقى متسقة عند توقيع العميل:
الأخطاء الشائعة وطرق التعامل معها:

