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، ووضع محفظة المتصفح، ووضع PythonEVMAccountSigner - توضّح حقل
preferScheme/prefer_schemeالسهل الوقوع في مشكلاته
أولًا، نظرة عامة على البروتوكول (لا بد من قراءتها)
يتضمن استدعاء X402 ناجح واحد 3 HTTP RTT:PAYMENT-SIGNATURE بعد ترميزه بـ base64. البنية (مقتطف):
x402Version: 2، ويُعلن عن scheme وnetwork المختارين لهذه المرة باستخدام كائن accepted (معرّف CAIP-2).
يُستخدم
preferScheme / prefer_scheme لاختيار التفضيل عندما يوفّر الخادم عدة scheme في الوقت نفسه. إذا كان الخادم يكشف exact فقط، فسيتم تجاهل هذا الحقل؛ وإذا تم تعيين upto لكن الخادم لا يكشفه، فسيتم الرجوع إلى أول عنصر مطابق.
ثانيًا، TypeScript: مجموعتا استخدام لمحفظة المتصفح + viem على الخادم
التثبيت
التوقيع الكامل لـ createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }>، وهي تتوافق تمامًا مع توقيع خطاف paymentHandler الخاص بـ SDK.
الاستخدام 1: المتصفح (MetaMask / WalletConnect)
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
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 مدمجة:
رابعًا، التحقق من التشغيل الفعلي
هدف الاختبار: لا يمرر TS SDK رمزًا مميزًا، ويحقن معالج X402، ويمكنه الإنشاء وإطلاق الطلبات بشكل طبيعي (تحقق خفيف لا يستهلك USDC حقيقيًا على السلسلة).- لم يتم تمرير
apiToken، ولا يُظهر إنشاء SDK أي خطأ، مما يثبت أن وضع X402 هو بالفعل بديل قانوني للرمز المميز. - تُرجع
createX402PaymentHandlerدالة (خطافًا)، ولا يستدعيها SDK إلا عند تلقي 402. - لم يتم تضمين اختبار شامل من طرف إلى طرف لنجاح الدفع الفعلي على السلسلة في هذا الدليل، لأنه يتضمن خصم USDC حقيقيًا؛ يمكنك الرجوع إلى مثال e2e في دليل تكامل X402.
أجرت جهة Python فيcreate_x402_payment_handlerالتحقق نفسه أيضًا —— قيمة إرجاع الدالة هي callable، ولا يُظهر إنشاءAceDataCloud(...)أي خطأ عند حقنpayment_handler=.... الدلالات متوافقة على الجانبين.
خامسًا، المقارنة مع «وضع Bearer token»
سادسًا، الأخطاء الشائعة
- يجب أن يكون
preferScheme=uptoلفئة chat: استخدامexactسيجعل facilitator يخصم USDC وفقًا لـmaxAmountRequired(وليس وفقًا للاستخدام الفعلي). - لا تمرّر مفتاحًا خاصًا خامًا إلى
createX402PaymentHandlerفي طرف Node: حزمة TS لا تقبل{ privateKey }، ويجب تغليفه ضمن provider متوافق مع EIP-1193 (يوصى بـ viemWalletClient). - الاستدعاء الأول يتضمن توقيعين: الأول يوقّع Permit2 approve (على السلسلة، ويتطلب gas)، والثاني يوقّع X402 envelope (ليس على السلسلة). الاستدعاءات اللاحقة لا يبقى فيها سوى الثاني.
- لا يوجد مفهوم Permit2 في Solana: يتم توقيع تفويض نقل SPL token مباشرةً، ولا حاجة إلى approve؛ لكن حاليًا تدعم سلسلة Solana فقط
exact. - ميّز بين أخطاء الأعمال وأخطاء الدفع: 402 → فشل handler ويرمي
X402SignError(يختلف النوع المحدد حسب السلسلة)؛ أما أخطاء واجهة الأعمال بعد إعادة الإرسال (401 / 422 / 5xx) فتظل مصنفة كاستثناءات SDK عادية. - الطريقة الأكثر استقرارًا لتكييف
viem: سيؤديevmProvider: walletClient as anyإلى فقدان التحقق من الأنواع لكنه يوفر أفضل توافق؛ وإذا أردت الاحتفاظ بالأنواع، فاستخدم.transport.requestمن viem لتغليف كائن{ request }منفصل وتمريره.

