واجهة API والوكلاء
يمكن للسكربتات والبوتات ووكلاء الذكاء الاصطناعي استخدام Watchdog عبر واجهة x402 API، بالمحفظة والأرصدة والمراقبات والمستلمين أنفسهم الذين تراهم في التطبيق.
آخر تحديث: 30/09/2026كل ما تفعله في صفحة Watchdog متاح أيضًا تحت /api/x402: عرض المراقبات وإنشاؤها، وتغيير الإشارات والتوجيه، وإدارة المستلمين وإرسال الاختبارات، وقراءة سجل التنبيهات وتصديره، والحصول على الأسعار، وشراء الخانات، وشحن الأرصدة. تظهر التغييرات التي تتم عبر API في التطبيق فورًا، والعكس صحيح.
تسجّل الآلة الدخول بالمحفظة، لا بكلمة مرور. تتكون العملية من خمس خطوات:
- POST /api/x402/auth/challenge مع عنوان المحفظة، والصلاحيات (scopes) المطلوبة، واسم اختياري للرمز.
- يحتوي الرد على رسالة تسجيل دخول بتنسيق SIWE (EIP-4361). وهي صالحة لمدة 5 دقائق وتسرد الصلاحيات المطلوبة.
- توقّع المحفظة الرسالة. وتعمل أيضًا محافظ العقود الذكية التي تدعم EIP-1271.
- POST /api/x402/auth/token مع الرسالة والتوقيع.
- يحتوي الرد على رمز يبدأ بـ fbx_ وعلى وقت انتهاء صلاحيته، وهو 24 ساعة افتراضيًا. ترسله الآلة في الترويسة Authorization: Bearer.
لا يُعرض الرمز إلا في هذا الرد. احفظه كما تحفظ كلمة المرور.
- read مضمّنة دائمًا: قراءة المراقبات والمستلمين والتنبيهات والأسعار والحساب.
- write تسمح بالتغييرات: إنشاء المراقبات والمستلمين والإعدادات وتعديلها.
- spend تسمح بالإجراءات التي تستهلك أرصدة، مثل شراء الخانات.
أمثلة: لوحة معلومات تعرض التنبيهات فقط تحتاج إلى read. وبوت يُعدّ مراقبات لأعضاء الفريق الجدد يحتاج إلى read وwrite. ووكيل يشتري الخانات بنفسه أيضًا يحتاج إلى read وwrite وspend. وإذا نقصت صلاحية، تردّ API بالحالة 403 مع رمز الخطأ insufficient_scope وتذكر الصلاحية المطلوبة.
تُدرَج جميع رموز محفظتك في «إعدادات الحساب ← الوصول إلى API»، مع الاسم وتاريخ الإنشاء وتاريخ الانتهاء وآخر استخدام. يوقف «إلغاء الرمز» الرمز فورًا؛ ولا يمكن التراجع عن ذلك. يمكن أن يكون للمحفظة 10 رموز نشطة على الأكثر في الوقت نفسه. ويمكن للآلات إلغاء رمز بنفسها عبر DELETE /api/x402/auth/tokens/{id}.
امنح كل آلة رمزًا خاصًا بها باسم خاص بها، وبالصلاحيات التي تحتاجها فقط. إذا اختُرقت آلة، تلغي ذلك الرمز وحده ولا يتوقف أي شيء آخر.
تحتاج الطلبات التي تنشئ شيئًا أو تستهلك أرصدة إلى الترويسة Idempotency-Key، وهي قيمة من 8 إلى 128 حرفًا أو رقمًا أو _ أو -. إذا انقطع الاتصال، ترسل الآلة الطلب نفسه بالمفتاح نفسه مرة أخرى وتحصل على النتيجة الأولى، بدلًا من الدفع مرتين. ويُرفض المفتاح نفسه مع طلب مختلف بالخطأ idempotency_key_reused.
إذا احتاجت مراقبة إلى خانة أو كان الرصيد منخفضًا جدًا، تردّ API بالحالة 402. يحتوي الرد على رمز الخطأ slot_required أو insufficient_credits، واقتراح شراء جاهز، ونقطة النهاية الخاصة بالشحن. ويمكن للوكيل حينها أن يقرر بنفسه، أو أن يسألك أولًا.
- وصف OpenAPI لجميع العمليات، بما فيها الصلاحيات ورموز الأخطاء.
- مخطط Webhook v2 للتنبيهات التي يتلقاها Webhook الخاص بك.
- llms.txt كنقطة دخول مختصرة لنماذج اللغة.
- كتالوج API وفق RFC 9727.
- توثيق API للبشر، مع أمثلة شيفرة.