> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Platform API guide - Ace Data Cloud

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

## `exact`

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

مناسب لـ:

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

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

```json theme={null}
{
  "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`. المبلغ الذي يوقعه العميل ليس تحويلًا ثابتًا، بل هو تفويض بحد أقصى مع شاهد:

```json theme={null}
{
  "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`:

```text theme={null}
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:

```bash theme={null}
pip install 'acedatacloud-x402[cli]'
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base
```

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

```python theme={null}
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` | تجاوز الاستخدام الفعلي الحد الأقصى الموقع، تحتاج إلى إعادة التوقيع بمبلغ أعلى. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.