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

X402 هو بروتوكول دفع على السلسلة يعتمد على HTTP `402 Payment Required`. من خلال قدرة X402 في Ace Data Cloud، يمكن للجهة المستدعية إجراء الدفع على السلسلة مباشرة باستخدام USDC دون الحاجة لإنشاء رمز API أو شحن رصيد الحساب مسبقًا في كل طلب API.

تم تنظيم هذه المجموعة من الوثائق وفقًا لترتيب الاتصال الحقيقي: أولاً قم بتشغيل طلب الحد الأدنى، ثم قم بتكامل SDK، وبعد ذلك فهم الشبكة، وخطط الفوترة، ودفع الطلبات وFacilitator. يُنصح بقراءة الجدول أدناه من الأعلى إلى الأسفل.

| الدليل | السيناريو المناسب | الرابط |
| - | - | - |
| البدء السريع | أولاً استخدم طلبًا حد أدنى لفهم 402، `accepts` و `PAYMENT-SIGNATURE` | [X402 البدء السريع](https://platform.acedata.cloud/documents/x402-quickstart) |
| TypeScript SDK | استدعاء Ace Data Cloud API في المتصفح أو Node.js أو التطبيقات الأمامية | [تكامل TypeScript SDK](https://platform.acedata.cloud/documents/x402-typescript-sdk) |
| Python SDK | استدعاء API في خدمات Python أو السكربتات أو الوكلاء أو خطوط البيانات | [تكامل Python SDK](https://platform.acedata.cloud/documents/x402-python-sdk) |
| دفع الطلب | استخدام X402 لدفع طلبات لوحة تحكم Ace Data Cloud | [دليل دفع الطلب](https://platform.acedata.cloud/documents/x402-order-payment) |
| الشبكة وطرق الدفع | فهم الأصول والتوقيعات والسيناريوهات المناسبة لـ Base وSKALE وSolana | [الشبكة وطرق الدفع](https://platform.acedata.cloud/documents/x402-networks) |
| `exact` و `upto` | التمييز بين API السعر الثابت وAPI التسوية اللاحقة | [شرح خطط الفوترة](https://platform.acedata.cloud/documents/x402-metered-upto) |
| شرح الأسعار | فهم العلاقة بين أسعار X402 وسعر الائتمانات، والأسعار الحقيقية لكل خدمة | [شرح أسعار X402](https://platform.acedata.cloud/documents/x402-pricing) |
| Facilitator | فهم العلاقة بين `verify` و `settle` وAPI الدفع الذاتي على الخادم | [تكامل Facilitator](https://platform.acedata.cloud/documents/x402-facilitator) |
| E2E واستكشاف الأخطاء | فحص المدخلات العامة، وتشغيل أدوات التحقق المتقدمة، وتحديد المشكلات الشائعة في 402، والتوقيع والتسوية | [التحقق E2E واستكشاف الأخطاء](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting) |

## مسار التكامل الموصى به

إذا كنت ترغب فقط في استدعاء Ace Data Cloud API، يُفضل استخدام SDK الرسمي:

* TypeScript: `@acedatacloud/sdk` + `@acedatacloud/x402-client`
* Python: `acedatacloud` + `acedatacloud-x402`

عناوين المصدر العامة والحزم:

| المشروع | العنوان |
| - | - |
| Ace Data Cloud SDK | [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) |
| X402 Client | [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client) |
| X402 Facilitator | [https://github.com/AceDataCloud/FacilitatorX402](https://github.com/AceDataCloud/FacilitatorX402) |
| npm SDK | [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk) |
| npm X402 Client | [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client) |
| PyPI SDK | [https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/) |
| PyPI X402 Client | [https://pypi.org/project/acedatacloud-x402/](https://pypi.org/project/acedatacloud-x402/) |

سيقوم SDK تلقائيًا بإجراء الطلب الأول بدون مصادقة، وتحليل `402 Payment Required`، واستدعاء معالج الدفع، وإعادة محاولة هذه الخطوات مع `PAYMENT-SIGNATURE`. كل ما تحتاجه هو إعداد محفظة تحتوي على USDC، واختيار الشبكة التي ترغب في استخدامها.

إذا كنت ترغب في جعل API الخاص بك يدعم أيضًا تحصيل X402، فستحتاج إلى قراءة وثائق Facilitator، وفهم العلاقة بين `paymentRequirements` و`paymentPayload` و`/verify` و`/settle`.

## حالة الدعم

تم التحقق من Ace Data Cloud X402 في API العامة، وSDK الرسمية، وFacilitator، ومسار التسوية على السلسلة. يلخص الجدول أدناه الحالة الحالية وفقًا لأبعاد القدرات الأكثر استخدامًا عند تكامل المطورين.

| القدرة | الحالة | الشرح |
| - | - | - |
| قدرات Facilitator | متاحة | `https://facilitator.acedata.cloud/.well-known/x402` ترجع شبكة الدفع ونقاط البروتوكول. |
| API 402 `accepts` | متاحة | الطلبات غير المدفوعة ستعيد متطلبات الدفع المتاحة لـ Base وSKALE وSolana. |
| TypeScript SDK | متاحة | `@acedatacloud/sdk` و `@acedatacloud/x402-client` يمكنهما معالجة 402، والتوقيع وإعادة المحاولة تلقائيًا. |
| Python SDK | متاحة | `acedatacloud` و `acedatacloud-x402` يمكنهما معالجة 402، والتوقيع وإعادة المحاولة تلقائيًا. |
| Base `exact` | تم التحقق على السلسلة | مناسب لAPI المبلغ الثابت ودفع الطلبات. |
| Base `upto` | تم التحقق على السلسلة | مناسب لـ API القياس اللاحق مثل إكمال الدردشة، الشبكة الوحيدة التي تقدم `upto` حاليًا. |
| SKALE `exact` | تم التحقق على السلسلة | مناسب لسيناريوهات الدفع EVM ذات تكلفة الغاز المنخفضة. |
| Solana `exact` | تم التحقق من إعادة المحاولة المدفوعة عبر HTTP | تم التحقق من إعادة المحاولة المدفوعة API مع استجابة النموذج؛ يُنصح باستخدام تسوية RPC الخاصة بـ Solana. |
| دفع الطلب | تم التحقق على السلسلة | تم إكمال تسوية الدفع على السلسلة لطلبات Base `exact` وتحديث حالة الطلب. |

الناتج أدناه مخصص فقط لشرح شكل الاستجابة للمسارات التي تم التحقق منها. عند التكامل الفعلي، يرجى دائمًا الاعتماد على `accepts` الذي ترجع به API الحالية.

```text theme={null}
الحزم
@acedatacloud/sdk@2026.504.2 استيراد ok
@acedatacloud/x402-client@2026.531.3 استيراد ok
acedatacloud==2026.4.26.1 استيراد ok
acedatacloud-x402==2026.5.31.3 استيراد ok

API 402
الحالة 402
يقبل eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact

TypeScript SDK
المحتوى ADC_TS_SDK_X402_OK

Python SDK
المحتوى ADC_PY_SDK_X402_OK

Base exact
المحتوى ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
المستكشف https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3

SKALE exact
المحتوى ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
المستكشف https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

Base upto
المحتوى ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
المستكشف https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
التوقيع الأقصى 95215 USDC الذري
قيمة التحويل 3 USDC الذري

Solana exact
HTTP 402 -> HTTP 200
المحتوى ADC_SOLANA_E2E_OK
توقيع السلسلة غير مؤكد في هذه العملية

دفع الطلب
الطلب 78481793-304e-47f7-bc0c-8231aec9cc1e الحالة منتهية pay_way X402
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
المستكشف https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
```

ملاحظات:

* تم تثبيت حزم npm و PyPI في بيئة نظيفة وتم استيرادها بنجاح.
* لم يتم دفع طلب API، مما أدى إلى إرجاع 402، و`accepts` يحتوي على طرق الدفع المتاحة لـ Base و SKALE و Solana.
* `accepts[].network` هو معرف CAIP-2، ويجب على العميل مطابقة الشبكة وفقًا لسلسلة CAIP-2.
* يمكن لـ TypeScript SDK و Python SDK معالجة 402 تلقائيًا وإكمال إعادة الدفع.
* تحتوي Base `exact` و SKALE `exact` و Base `upto` ودفع الطلب على عناوين مستكشف يمكن فتحها علنًا.
* الحد الأقصى للتوقيع لـ Base `upto` هو `95215` USDC الذري، بينما التسوية الفعلية هي `3` USDC الذري، مما يعكس خاصية التسوية حسب الاستخدام الفعلي.
* تم التحقق من Solana `exact` HTTP 402 -> HTTP 200 وإخراج النموذج. نظرًا لأن استعلامات RPC العامة قد تكون محدودة، يُنصح باستخدام RPC الخاص بـ Solana أو سجلات التسوية على الجانب المنصة لتأكيد توقيع المعاملة.

## ملاحظات حول التكامل

عند التكامل، يجب على المطورين التركيز أولاً على متطلبات الدفع الفورية التي تم إرجاعها في الطلب الحالي، بدلاً من نسخ المبالغ أو العناوين من الوثائق:

* `accepts[].maxAmountRequired` هو الحد الأقصى للمبلغ الذي يمكن توقيعه في الطلب الحالي.
* `accepts[].asset` هو عقد USDC أو mint الذي سيتم استخدامه في هذا الطلب.
* ستشارك `accepts[].extra.chainId` و `accepts[].extra.facilitatorAddress` و `accepts[].extra.verifyingContract` في توقيع بيانات EVM المخصصة.
* يحتاج `upto` إلى أن يقوم المحفظة أولاً بتفويض USDC على السلسلة المستهدفة باستخدام Permit2؛ إذا لم يتم التفويض، سيتم إرجاع `PERMIT2_ALLOWANCE_REQUIRED`.
* إذا كنت ترغب بوضوح في استخدام القياس اللاحق، يرجى تمرير `preferScheme: 'upto'` في TypeScript SDK، وإلا ستختار SDK أول متطلبات متاحة تم إرجاعها من الخادم تحت تلك الشبكة.

## النطاق القابل للتحقق علنًا

يمكن التحقق من هذه النقاط العامة وسلوك SDK قبل التكامل:

* ستعيد طلبات API التي لا تحتوي على `Authorization` أو `PAYMENT-SIGNATURE` `402 Payment Required`، و`accepts` في الاستجابة هو الأساس الوحيد للتوقيع في هذا الطلب.
* يوفر كل من TypeScript SDK و Python SDK معالج دفع، حيث ستقوم طبقة النقل في SDK باستدعاء المعالج وإعادة المحاولة مرة واحدة عند تلقي 402.
* `https://facilitator.acedata.cloud/.well-known/x402`: يعيد الشبكات المدعومة من Facilitator، والمخطط ونقاط النهاية للبروتوكول؛ لا يزال سعر API يعتمد على 402 الذي تم إرجاعه في الطلب المستهدف.
* `https://facilitator.acedata.cloud/supported`: يعيد الشبكات والمخططات المدعومة من Facilitator.
* يحتوي مستودع X402Client على أدوات تحقق متقدمة على السلسلة، يمكن استخدامها لتأكيد التوقيع، وإعادة المحاولة وسلوك التسوية؛ لا تحل مخرجات الأدوات محل `accepts` التي تم إرجاعها من API عبر الإنترنت.

`upto` ينتمي إلى تسوية القياس اللاحق، وهو مناسب لإكمال الدردشة، واستدعاءات النموذج، وغيرها من الاستخدامات الفعلية التي تُعرف فقط بعد الاستجابة. حاليًا، توفر Base فقط `upto`؛ إذا فشل التحقق من التوقيع، يرجى التحقق من معرف السلسلة، وعنوان الميسر، والمصرف، وعقد USDC، وتفويض Permit2 للتأكد من توافقها مع استجابة 402.


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