الانتقال إلى المحتوى الرئيسي
X402 هو بروتوكول دفع على السلسلة «يتم فيه الفوترة وفق HTTP 402» اقترحته Coinbase: يعيد الخادم 402 Payment Required على الطلبات التي لا تحتوي على token، مرفقًا بحقل accepts: [...] يسرد السلاسل / الأصول / الأسعار المقبولة؛ يوقّع العميل محليًا تفويضًا (Permit2 / EIP-712 على EVM، وتفويض تحويل SPL token على Solana)، ويضع envelope بعد ترميزه بـ base64 في ترويسة PAYMENT-SIGNATURE ثم يعيد الإرسال. بعد التحقق، ينفّذ الخادم التسوية فعليًا على السلسلة، ثم يعيد نتيجة العمل.
يستدعي عميل X402 الخاص بـ Ace Data Cloud واجهة API المستهدفة مباشرةً، ويستخدم 402 Payment Required وaccepts المعادين لحظيًا من هذا الطلب كأساس للسعر والتوقيع. يمكن التحقق من قدرة دفع الـ Facilitator عبر /.well-known/x402.
يكشف كل من @acedatacloud/sdk وacedatacloud عن خطاف paymentHandler: عندما يتلقى طلب صادر من SDK نفسه 402، يستدعي handler الذي تحقنه للحصول على ترويسة PAYMENT-SIGNATURE، ثم يعيد إرسال الطلب الأصلي. بدمج @acedatacloud/x402-client / acedatacloud-x402 مع SDK، تكون العملية كاملةً شفافة تمامًا لكود العمل——تستخدم فقط client.openai.chat.completions.create(...)، ويبدو الأمر مطابقًا تمامًا لوضع token، لكن الدفع في الطبقة السفلية يكون لكل استدعاء ولا يتطلب شحنًا مسبقًا. هذه المقالة:
  • تربط فعليًا سلسلة «بدون token + حقن X402 handler» على طرف TS (تحقق T12)
  • تسرد الفروقات بين سلسلتي التوقيع EVM / Solana
  • تقدّم ثلاث طرق تكييف: وضع المفتاح الخاص viem، ووضع محفظة المتصفح، ووضع Python EVMAccountSigner
  • توضّح حقل preferScheme / prefer_scheme السهل الوقوع في مشكلاته

أولًا، نظرة عامة على البروتوكول (لا بد من قراءتها)

يتضمن استدعاء X402 ناجح واحد 3 HTTP RTT:
إن X402 envelope هو جزء من JSON، يُوضع في ترويسة PAYMENT-SIGNATURE بعد ترميزه بـ base64. البنية (مقتطف):
تكون الطبقة العليا من envelope هي x402Version: 2، ويُعلن عن scheme وnetwork المختارين لهذه المرة باستخدام كائن accepted (معرّف CAIP-2). يُستخدم preferScheme / prefer_scheme لاختيار التفضيل عندما يوفّر الخادم عدة scheme في الوقت نفسه. إذا كان الخادم يكشف exact فقط، فسيتم تجاهل هذا الحقل؛ وإذا تم تعيين upto لكن الخادم لا يكشفه، فسيتم الرجوع إلى أول عنصر مطابق.

ثانيًا، TypeScript: مجموعتا استخدام لمحفظة المتصفح + viem على الخادم

التثبيت

أرقام الإصدارات المختبرة:

التوقيع الكامل لـ createX402PaymentHandler

القيمة المعادة هي (ctx) => Promise&lt;{ headers: Record<string, string> }>، وهي تتوافق تمامًا مع توقيع خطاف paymentHandler الخاص بـ SDK.

الاستخدام 1: المتصفح (MetaMask / WalletConnect)

في أول استدعاء، سيظهر في المتصفح طلبا توقيع: الأول هو approve لمرة واحدة لـ Permit2 على USDC (المبلغ هو MaxUint256، ويُكتب على السلسلة)؛ والثاني هو توقيع EIP-712 لـ X402 envelope (لا يُكتب على السلسلة، وإنما للتحقق من قِبل facilitator). تحتاج الاستدعاءات اللاحقة إلى التوقيع الثاني فقط، وتجربة الاستخدام هي «انقر توقيعًا واحدًا → احصل على النتيجة».

الاستخدام 2: خادم Node + مفتاح viem الخاص (مناسب للواجهة الخلفية / CLI)

يقبل @acedatacloud/x402-client على طرف TS مزوّد EIP-1193 فقط——ولا يدير المفاتيح الخاصة مباشرةً. في سيناريوهات Node / CLI، الطريقة القياسية هي استخدام viem لتغليف المفتاح الخاص في WalletClient، ثم المرور عبر تكييف EIP-1193 الخاص بـ @ethereumjs/util أو الداخلي في viem.
إذا شعرت أن توافق EIP-1193 الخاص بـ viem غير مستقر بما يكفي، يمكنك أيضًا اتباع المسار منخفض المستوى عبر signEVMUptoPayment، وربط مسار accepts → signed envelope → PAYMENT-SIGNATURE header بنفسك، مع تجاوز خطاف SDK؛ لكن يُوصى بأن يكون الخيار الأول هو createX402PaymentHandler، حتى لا تضطر إلى صيانة ترقيات البروتوكول بنفسك.

الاستخدام 3: Solana

على سلسلة Solana، يتم حاليًا كشف مخطط exact فقط، لذلك لا يكون لـ preferScheme أي تأثير على Solana.

ثالثًا، Python: وضع المفتاح الخاص

يتبع acedatacloud-x402 في Python مسار التوقيع المباشر باستخدام المفتاح الخاص (ولا توجد تجريدات EIP-1193)، وهو أنسب للخوادم / منفذات المهام.

التثبيت

إصدارات تم اختبارها فعليًا:

EVM (Base)

Solana

approve لمرة واحدة (EVM فقط في المرة الأولى)

في EVM Base، يستخدم X402 Permit2، ويحتاج المحفظة إلى تنفيذ approve واحد بقيمة MaxUint256 لعقد Permit2 بالنسبة إلى USDC. يتضمن acedatacloud-x402 دالة approve_permit2 مدمجة:
تحتاج إلى إرسال هذه المعاملة مرة واحدة فقط، وبعد ذلك تستخدم جميع مدفوعات X402 EVM هذا التفويض. لا تحتاج Solana إلى ذلك.

رابعًا، التحقق من التشغيل الفعلي

هدف الاختبار: لا يمرر TS SDK رمزًا مميزًا، ويحقن معالج X402، ويمكنه الإنشاء وإطلاق الطلبات بشكل طبيعي (تحقق خفيف لا يستهلك USDC حقيقيًا على السلسلة).
المخرجات:
توضح النتائج:
  • لم يتم تمرير apiToken، ولا يُظهر إنشاء SDK أي خطأ، مما يثبت أن وضع X402 هو بالفعل بديل قانوني للرمز المميز.
  • تُرجع createX402PaymentHandler دالة (خطافًا)، ولا يستدعيها SDK إلا عند تلقي 402.
  • لم يتم تضمين اختبار شامل من طرف إلى طرف لنجاح الدفع الفعلي على السلسلة في هذا الدليل، لأنه يتضمن خصم USDC حقيقيًا؛ يمكنك الرجوع إلى مثال e2e في دليل تكامل X402.
أجرت جهة Python في create_x402_payment_handler التحقق نفسه أيضًا —— قيمة إرجاع الدالة هي callable، ولا يُظهر إنشاء AceDataCloud(...) أي خطأ عند حقن payment_handler=.... الدلالات متوافقة على الجانبين.

خامسًا، المقارنة مع «وضع Bearer token»

سادسًا، الأخطاء الشائعة

  1. يجب أن يكون preferScheme=upto لفئة chat: استخدام exact سيجعل facilitator يخصم USDC وفقًا لـ maxAmountRequired (وليس وفقًا للاستخدام الفعلي).
  2. لا تمرّر مفتاحًا خاصًا خامًا إلى createX402PaymentHandler في طرف Node: حزمة TS لا تقبل { privateKey }، ويجب تغليفه ضمن provider متوافق مع EIP-1193 (يوصى بـ viem WalletClient).
  3. الاستدعاء الأول يتضمن توقيعين: الأول يوقّع Permit2 approve (على السلسلة، ويتطلب gas)، والثاني يوقّع X402 envelope (ليس على السلسلة). الاستدعاءات اللاحقة لا يبقى فيها سوى الثاني.
  4. لا يوجد مفهوم Permit2 في Solana: يتم توقيع تفويض نقل SPL token مباشرةً، ولا حاجة إلى approve؛ لكن حاليًا تدعم سلسلة Solana فقط exact.
  5. ميّز بين أخطاء الأعمال وأخطاء الدفع: 402 → فشل handler ويرمي X402SignError (يختلف النوع المحدد حسب السلسلة)؛ أما أخطاء واجهة الأعمال بعد إعادة الإرسال (401 / 422 / 5xx) فتظل مصنفة كاستثناءات SDK عادية.
  6. الطريقة الأكثر استقرارًا لتكييف viem: سيؤدي evmProvider: walletClient as any إلى فقدان التحقق من الأنواع لكنه يوفر أفضل توافق؛ وإذا أردت الاحتفاظ بالأنواع، فاستخدم .transport.request من viem لتغليف كائن { request } منفصل وتمريره.

اعرف المزيد