> ## 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

> Platform API guide - Ace Data Cloud

يتمحور Ace Data Cloud X402 حاليًا حول تسوية USDC، ويدعم نوعين من السلاسل: EVM وSolana. تختلف طريقة التوقيع وعنوان الأصل وسلوك gas وسيناريوهات الاستخدام باختلاف الشبكات، ويجب اختيار الشبكة مسبقًا قبل التكامل.

## تستخدم معرّفات الشبكات CAIP-2

إن `accepts[].network` في x402 v2 هو معرّف CAIP-2، وليس اختصارات مثل `base` و`skale`. يجب على العميل مطابقة الشبكة عبر المقارنة بسلسلة CAIP-2:

| الشبكة | معرّف CAIP-2 |
| - | - |
| Base | `eip155:8453` |
| SKALE Base | `eip155:1187947933` |
| Solana mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |

## مصفوفة الدعم

| الشبكة | scheme | الأصل | طريقة التوقيع | سيناريو الاستخدام |
| - | - | - | - | - |
| Base | `exact` | Base USDC | EIP-3009 `TransferWithAuthorization` | موصى بها افتراضيًا، ودعم المحافظ والسيولة ناضج. |
| Base | `upto` | Base USDC + Permit2 | Permit2 `PermitWitnessTransferFrom` | واجهات API للفوترة اللاحقة مثل الدردشة والنماذج. |
| SKALE | `exact` | SKALE bridged USDC | EIP-3009 `TransferWithAuthorization` | تكلفة gas منخفضة، مناسبة للتحقق من مدفوعات EVM والاستدعاءات منخفضة التكلفة. |
| Solana | `exact` | Solana USDC | SPL `TransferChecked` | سيناريوهات محافظ Solana أو Agent أو التطبيقات على السلسلة. |

يتوفر `upto` حاليًا على Base فقط. تعتمد العناصر المتاحة فعليًا على `accepts` التي تعيدها API. يمكنك أيضًا عرض Facilitator:

```bash theme={null}
curl https://facilitator.acedata.cloud/supported
```

استجابة Facilitator `/supported`:

```json theme={null}
{
  "kinds": [
    { "x402Version": 2, "scheme": "exact", "network": "eip155:8453" },
    {
      "x402Version": 2,
      "scheme": "upto",
      "network": "eip155:8453",
      "extra": { "facilitatorAddress": "0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708" }
    },
    { "x402Version": 2, "scheme": "exact", "network": "eip155:1187947933" },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "extra": { "feePayer": "3SPm6qbgsDkj24MuR8Ss4sH97fziqyCiqFKDyeVU2igq" }
    }
  ]
}
```

توضيح النتائج:

* إن `exact` في Base وSKALE وSolana هو مسار دفع بمبلغ ثابت.
* توفر Base فقط مسار الفوترة اللاحقة `upto`، والذي يعتمد على approve لـ Permit2.
* إن `extra.facilitatorAddress` في عنصر `upto` هو العنوان الذي يجب كتابته في witness عند توقيع العميل، ويجب أن يتطابق مع القيمة التي يعيدها الخادم.

## Base

تستخدم Base عقد USDC الرسمي:

```text theme={null}
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

في مخطط `exact`، يوقع العميل EIP-712 `TransferWithAuthorization`. يتضمن محتوى التوقيع:

* `from`: عنوان محفظة الدفع
* `to`: عنوان المستلم الخاص بـ Ace Data Cloud
* `value`: مبلغ الدفع لهذه المرة
* `validAfter` / `validBefore`: نافذة صلاحية التوقيع
* `nonce`: nonce عشوائي من 32 بايت

بعد أن يتحقق Facilitator من التوقيع، سيستدعي `transferWithAuthorization` الخاص بـ USDC على السلسلة لإتمام التحويل.

Base هي شبكة التكامل الرسمية الأكثر توصية، وهي مناسبة بشكل خاص للفوترة اللاحقة `upto`، لأن نظام Permit2 وUSDC والمحافظ أكثر نضجًا.

مثال على نتيجة التحقق من Base `exact`:

```text theme={null}
payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
block 46726299
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
transfer value 95215 atomic USDC
```

توضيح النتائج:

* تعيد API paid retry محتوى النموذج `ADC_BASE_E2E_OK`.
* يمكن البحث عن المعاملة على السلسلة في BaseScan، ورقم الكتلة هو `46726299`.
* إن `95215` atomic USDC تساوي `0.095215` USDC، وهو مبلغ التسوية الفعلي لاستدعاء API هذا.

نتيجة تشغيل البرنامج لدفع طلب Base `exact`:

```text theme={null}
order 78481793-304e-47f7-bc0c-8231aec9cc1e
state Finished
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC
```

توضيح النتائج:

* الحالة النهائية لطلب المنصة هي `Finished`.
* يُكتب `pay_id` الخاص بالطلب في نفس تجزئة معاملة Base.
* إن `1200000` atomic USDC تساوي `1.2` USDC، وهو مبلغ الدفع الفعلي التاريخي لطلب 10 Credits هذا بموجب السياسة القديمة؛ لا تتمتع الطلبات الجديدة بخصم إضافي لطريقة دفع X402، ويُعتد بمبلغ التوقيع المحدد في استجابة 402 هذه.

## SKALE

تستخدم SKALE USDC المُجسَّر، وطريقة التوقيع مشابهة لـ Base، وهي أيضًا EIP-3009. وهي مناسبة لسيناريوهات الدفع EVM ذات تكلفة gas المنخفضة؛ وتظل الاستدعاءات الفعلية خاضعة لـ `accepts` التي تعيدها API.

سيحتوي `accepts` النموذجي لـ 402 في SKALE على:

```json theme={null}
{
  "network": "eip155:1187947933",
  "scheme": "exact",
  "extra": {
    "name": "Bridged USDC (SKALE Bridge)",
    "version": "2",
    "chainId": 1187947933,
    "verifyingContract": "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20"
  }
}
```

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

مثال على نتيجة التحقق من SKALE `exact`:

```text theme={null}
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
block 1969317
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
paid 0.095215 USDC
```

توضيح النتائج:

* تعيد محاولة الدفع عبر API محتوى النموذج `ADC_SKALE_E2E_OK`.
* يمكن الاستعلام عن المعاملة في مستكشف SKALE، ورقم الكتلة هو `1969317`.
* مبلغ التسوية لهذه الدفعة `exact` هو `0.095215` USDC.

## Solana

تستخدم Solana عملية `TransferChecked` الخاصة بـ SPL USDC. سيُنشئ العميل معاملة تحويل، ويوقّع عليها ويقدّمها، ثم يضع توقيع المعاملة أو المعاملة المتسلسلة في envelope `PAYMENT-SIGNATURE`.

خصائص Solana:

* استخدام Solana wallet adapter أو base58 secret key؛
* الأصل هو Solana USDC mint؛
* يدعم حاليًا `exact` فقط؛
* سيتحقق الـ Facilitator من mint وdestination وauthority وamount الخاصة بتعليمة التحويل.

إذا تم استخدام نمط wallet fee payer، فستقدّم المحفظة المعاملة مباشرةً، وسيكون الـ Facilitator مسؤولًا عن تأكيد المعاملة وإرجاع نتيجة settlement.

مثال على نتيجة التحقق من `exact` في Solana:

```text theme={null}
payer AY2RmGm2zPxB1uKvvF4dKyYdr2VySyL3wcD1MKJZoLRd
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run
```

شرح النتائج:

* أعادت paid retry بالفعل HTTP 200، وكان خرج النموذج `ADC_SOLANA_E2E_OK`.
* قد تواجه استعلامات RPC العامة عن signature على السلسلة تقييدًا للمعدل.
* نظرًا لأن استعلامات RPC العامة قد تكون مقيّدة بالمعدل، فلا يُكتب هنا مستكشف Solana. عند الحاجة إلى مطابقة صارمة، يُرجى استخدام Solana RPC خاص بك أو سجلات settlement من جهة المنصة لتأكيد توقيع المعاملة.

## كيفية الاختيار

| ما الذي تريد القيام به | الشبكة الموصى بها |
| - | - |
| تشغيل الحد الأدنى من المسار بسرعة | SKALE `exact` أو Base `exact` |
| موجّه لمستخدمي Web3 العاديين | Base |
| إجراء قياس لاحق مثل إكمال الدردشة | Base `upto` |
| تطبيقات منظومة Solana | Solana `exact` |
| التحقق من مدفوعات EVM منخفضة التكلفة | SKALE `exact` |

بغض النظر عن السلسلة التي تختارها، لا تقم بترميز السعر بشكل ثابت في العميل. يحدده السعر الذي يعيده الخادم عبر `accepts[].maxAmountRequired`.


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