الانتقال إلى المحتوى الرئيسي
يُعد TypeScript إحدى أكثر الطرق الموصى بها لتكامل Ace Data Cloud X402. تتولى SDK الرسمية استدعاءات API العادية، واستطلاع المهام، ومعالجة الأخطاء، وإعادة المحاولة التلقائية؛ بينما يتولى @acedatacloud/x402-client توقيع ترويسة طلب PAYMENT-SIGNATURE عند مواجهة 402 Payment Required. عناوين المصدر والحزم:

تثبيت التبعيات

إذا كنت تستخدم Base، فتحتاج إلى قدرة توقيع EVM:
إذا كنت تستخدم Solana، فتحتاج إلى Solana wallet adapter أو @solana/web3.js:
مخرجات التحقق من التثبيت والاستيراد لمشروع npm نظيف:
توضيح النتائج:
  • يمكن تثبيت كل من @acedatacloud/sdk و@acedatacloud/x402-client من npm واستيرادهما بواسطة Node.js.
  • يُستخدم ethers لتوقيع EVM typed data، ويُستخدم @solana/web3.js لبناء Solana transaction.

مثال Base

يمكن استخدام window.ethereum مباشرة في المتصفح. في Node.js، يمكن تغليف ethers.Wallet بطبقة provider بأسلوب EIP-1193.

مثال محفظة المتصفح

عند استخدام MetaMask أو Coinbase Wallet أو WalletConnect في تطبيق الواجهة الأمامية، يُمرَّر عادةً EIP-1193 provider مباشرةً:
ستظهر لمحفظة المتصفح نافذة تأكيد التوقيع. لا يوقع المستخدم على رسالة عشوائية، بل على متطلبات الدفع التي يعيدها API: عنوان المستلم، وعقد USDC، والمبلغ، وفترة الصلاحية، وnonce كلها مشمولة في التوقيع.

مثال Solana

تستخدم Solana ‏SPL USDC TransferChecked. يجب أن يكشف wallet adapter المُمرَّر عن publicKey وsignAndSendTransaction.
يدعم مسار Solana حاليًا exact فقط، ولا يدعم upto. إذا أعاد API عدة accepts، فسيختار handler العنصر الذي له network = 'solana'. تم التحقق من أن paid retry لمسار Solana على نفس API العام يمكن أن يعيد HTTP 200 وADC_SOLANA_E2E_OK. قد تخضع استعلامات RPC العامة لتحديد المعدل، لذلك لا تكتب هذه المقالة Solana tx hash؛ عند الحاجة إلى المطابقة على السلسلة، يرجى استخدام Solana RPC الخاص بك أو تأكيد سجلات وحدة التحكم.

اختيار exact أو upto

سيختار TypeScript handler الحالي أول payment requirement للشبكة المطابقة يعيدها الخادم. يضع API الخاص بـ Ace Data Cloud عادةً exact للشبكة نفسها قبل upto، لذلك إذا كنت تريد صراحةً استخدام القياس المؤجل، تحتاج إلى تمرير preferScheme: 'upto'. مثال:
إذا لم يعيد الخادم upto requirement لتلك الشبكة، فسيرجع handler تلقائيًا إلى أول requirement متاح لتلك الشبكة، والذي يكون عادةً exact. يتطلب upto تفويض Permit2 لمرة واحدة. يُوفر upto حاليًا على Base فقط، لذلك تحتاج فقط إلى تنفيذ تفويض واحد لـ Base USDC:
أكمل Base upto التحقق من API العام: HTTP 402 -> HTTP 200، ومعاملة settlement المؤجلة هي 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. راجع شرح خطة الفوترة للحصول على المخرجات الكاملة.

ما الذي تفعله SDK

سينفذ transport الخاص بـ @acedatacloud/sdk payment handler مرة واحدة عند استلام 402:
سيقوم handler الذي يعيده @acedatacloud/x402-client بما يلي:
  1. اختيار payment requirement للشبكة المستهدفة من ctx.accepts.
  2. بناء توقيع EVM EIP-712 أو Solana transfer transaction وفقًا للشبكة.
  3. تسلسل envelope إلى Base64.
  4. إرجاع { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. تعيد SDK المحاولة تلقائيًا باستخدام نص الطلب الأصلي.
يعني هذا أن كود الأعمال يحتاج فقط إلى أن يُكتب مثل استدعاء SDK عادي، دون الحاجة إلى معالجة إعادة محاولة 402 يدويًا.