X402 `exact` و `upto` خطط الفوترة

تستخدم Ace Data Cloud X402 حاليًا نوعين من الخطط: exact و upto. وهما يحلان مشكلات فوترة مختلفة.

`exact`

exact تعني أن السعر يمكن تحديده قبل دخول الطلب إلى واجهة برمجة التطبيقات المستهدفة. المبلغ الذي يوقعه العميل هو المبلغ النهائي الذي سيتم خصمه. مناسب لـ:

توليد الصور بسعر ثابت؛
إنشاء مهام الفيديو بسعر ثابت؛
واجهة برمجة التطبيقات للبحث أو الأدوات بسعر ثابت؛
دفع الطلبات.

تستخدم EVM exact USDC EIP-3009 TransferWithAuthorization:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453"
  },
  "payload": {
    "authorization": {
      "from": "0x...",
      "to": "0x...",
      "value": "95215",
      "validAfter": "1780237345",
      "validBefore": "1780240945",
      "nonce": "0x..."
    },
    "signature": "0x..."
  }
}

يتحقق Facilitator من التوقيع والمبلغ في مرحلة /verify، ويقدم هذا التفويض على السلسلة في مرحلة /settle.

`upto`

upto تعني أن العميل يمنح تفويضًا بحد أقصى، وتقوم Ace Data Cloud بتسوية الفاتورة بناءً على الاستخدام الفعلي بعد إتمام الطلب، ولا يمكن أن يتجاوز المبلغ الفعلي الحد الأقصى. مناسب لـ:

إكمال الدردشة: السعر النهائي يعتمد على prompt tokens و completion tokens؛
الاستجابة المتدفقة: لا تعرف طول الإخراج الحقيقي إلا بعد الانتهاء؛
واجهة برمجة التطبيقات للقياس اللاحق في المستقبل.

تستخدم upto Permit2 PermitWitnessTransferFrom. المبلغ الذي يوقعه العميل ليس تحويلًا ثابتًا، بل هو تفويض بحد أقصى مع شاهد:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "upto",
    "network": "eip155:8453"
  },
  "payload": {
    "permit2Authorization": {
      "from": "0x...",
      "spender": "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002",
      "nonce": "123456789",
      "deadline": "1780240945",
      "permitted": {
        "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "95215"
      },
      "witness": {
        "to": "0x...",
        "facilitator": "0x...",
        "validAfter": "1780237345"
      }
    },
    "signature": "0x..."
  }
}

permitted.amount هو الحد الأقصى، وليس بالضرورة المبلغ النهائي الذي سيتم خصمه. في مرحلة /record، سيقوم Gateway بتحويل الاستخدام الفعلي إلى amount وإرساله إلى Facilitator. يسمح Facilitator بالتسوية فقط إذا كان amount <= permitted.amount. نتيجة تشغيل برنامج Base upto:

payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
elapsed_ms 5104
content ADC_BASE_UPTO_OK
id chatcmpl-DlcbyS4IT8kUAMo4Ri97HiIHc9T8V
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

توضيح:

الحد الأقصى للتفويض الذي تم إرجاعه في 402 هو 95215 atomic USDC، وقد وقع العميل على هذا الحد.
بعد استجابة النموذج، تم تسوية فقط 3 atomic USDC، ويمكن التحقق من المعاملة على السلسلة في BaseScan.
يمكن أن توضح هذه النتيجة الفرق الرئيسي في upto: المبلغ الموقع هو الحد الأقصى، ويمكن أن تكون التسوية على السلسلة أقل من الحد الأقصى.
إذا تجاوز الاستخدام الفعلي الحد الأقصى، يجب على Facilitator رفض التسوية، ويحتاج العميل إلى إعادة التفويض بمبلغ أعلى.

حاليًا، يتوفر upto فقط على Base. توفر SKALE فقط exact، إذا كنت بحاجة إلى قياس لاحق، يرجى استخدام Base.

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

يتم سحب USDC في النهاية بواسطة x402 proxy عبر Permit2 من محفظة الدفع. قبل الاستخدام الأول، تحتاج محفظة الدفع إلى منح Permit2 تفويض ERC-20 مرة واحدة. Python CLI:

pip install 'acedatacloud-x402[cli]'
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base

طريقة البرنامج:

from acedatacloud_x402 import EVMAccountSigner, approve_permit2

approve_permit2(
    rpc_url="https://mainnet.base.org",
    signer=EVMAccountSigner.from_private_key("0x..."),
    token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
)

بعد الانتهاء من التفويض، لا يزال يتعين توقيع مظروف upto جديد في كل طلب، لأن nonce و deadline و witness و الحد الأقصى للمبلغ جميعها مختلفة.

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

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

اقتراحات الاختيار

السيناريو	الاقتراح
واجهة برمجة التطبيقات بسعر ثابت	استخدم `exact`، المنطق بسيط.
دفع الطلب	استخدم `exact`。
إكمال الدردشة، الفوترة حسب token	استخدم Base `upto`。
لم تقم بعد بعمل Permit2 approve	ابدأ باستخدام `exact`، ثم انتقل إلى `upto`。
تحتاج إلى قياس لاحق على SKALE	غير مدعوم حاليًا، توفر SKALE فقط `exact`。

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

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

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

المعلمة	نقطة الفحص
`network`	يجب أن تكون `eip155:8453`。
`scheme`	يجب أن تكون `upto`。
`extra.chainId`	معرف سلسلة Base هو `8453`。
`asset`	استخدم عنوان عقد Base USDC من استجابة 402.
`extra.facilitatorAddress`	يجب أن تشارك في الشاهد، وأن تتطابق مع Facilitator `/supported`。
Permit2 allowance	تحتاج محفظة الدفع إلى منح Permit2 تفويضًا لـ Base USDC.

الأخطاء الشائعة وطرق المعالجة:

الخطأ	طريقة المعالجة
`invalid_upto_evm_payload_invalid_signature`	تحقق من معرف السلسلة، عنوان facilitator، مجال Permit2، المنفق، حساب التوقيع والشاهد إذا كانت متطابقة مع استجابة 402.
`PERMIT2_ALLOWANCE_REQUIRED`	نفذ Permit2 approve لـ USDC على السلسلة المستهدفة ثم أعد إرسال الطلب.
`amount exceeds permitted amount`	تجاوز الاستخدام الفعلي الحد الأقصى الموقع، تحتاج إلى إعادة التوقيع بمبلغ أعلى.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

Coding

المزيد من الأدلة

X402 `exact` و `upto` خطط الفوترة

`exact`

`upto`

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

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

اقتراحات الاختيار

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

​exact

​upto

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

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

​اقتراحات الاختيار

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

`exact`

`upto`

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

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

اقتراحات الاختيار

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