المصادقة والـ Scopes

تستخدم مصادقة الآلات challenge من نوع SIWE وفق EIP-4361 على سلسلة Flare برقم chainId 14. وقّع الرسالة المعادة بالضبط بمحفظتك (EIP-191 personal_sign). الـ Nonce أحادي الاستخدام ومرتبط بالمحفظة وتنتهي صلاحيته بعد خمس دقائق. اطلب فقط الصلاحيات التي يحتاجها عميلك. يطلب المثال write وspend لأن أمثلة الشحن والاشتراك التالية تستخدم كليهما؛ read مضمّن دائمًا.

curl -X POST 'https://ftso.app/api/x402/auth/challenge' \
  -H 'content-type: application/json' \
  -d '{"wallet":"0xYOUR_WALLET","scopes":["write","spend"],"label":"My agent"}'

تحتوي الاستجابة على wallet وnonce وissuedAt وmessage. احتفظ بـ message كما هي بالضبط، بما في ذلك المسافات البيضاء. في viem استخدم account.signMessage({ message }). الـ Scopes جزء من الموافقة الموقّعة؛ أما label فبيانات وصفية تجميلية بحد أقصى 40 حرفًا. لا تُعِد بناء الرسالة من الـ Nonce.

curl -X POST 'https://ftso.app/api/x402/auth/token' \
  -H 'content-type: application/json' \
  -d '{"message":"EXACT_RETURNED_SIWE_MESSAGE","signature":"0xSIGNATURE"}'
# Response: { token: "fbx_...", wallet, scopes, expiresAt }

خزّن token بشكل آمن وأرسل Authorization: Bearer fbx_… في الاستدعاءات اللاحقة. لا تضعه في سلسلة استعلام (query string) أو سجلات مشتركة أو أمثلة. استبدال الـ Token يستخدم no-store. توقيعات EOA تُتحقَّق محليًا؛ أما التحقق من محافظ العقود فيعتمد على RPC الخادم المكوَّن ويرفض المصادقة عند فشل التحقق.

• read: القراءات ومعاينات الرسائل؛ يشمل الوصول المدفوع إلى البيانات إذا فُعّل الإنفاذ (enforcement).
• write: التغييرات، واختبارات المستلمين، ومسودات الشحن وتأكيداتها، وقبول الشروط، والتجارب، وإيقاف Auto-Renew.
• spend: شراء سعة الاشتراك وتفعيل Auto-Renew.
• read يُمنح دائمًا، بما في ذلك مع write أو spend. يستطيع token بصلاحية write إبطال أي token للمحفظة نفسها.

curl 'https://ftso.app/api/x402/auth/tokens' -H 'authorization: Bearer fbx_TOKEN'
curl -X DELETE 'https://ftso.app/api/x402/auth/tokens/42' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN'

يمكن أن يكون للمحفظة عشرة tokens نشطة على الأكثر. يعيد العرض حتى 50 إدخالًا من البيانات الوصفية، النشطة أولًا؛ ولا يعيد أبدًا أسرارًا أو تجزئات (hashes). يسري الإبطال عند الطلب المصادَق التالي. المعرّفات الغريبة تعيد 404. يمكن للمتصفح إدارة الـ Tokens في Wallet-Center Settings → Security. يستخدم MCP مسار OAuth خاصًا به؛ ‏Bearer-Token الخاص بـ x402 ليس access token لـ MCP.

• مدة صلاحية الـ Bearer-Token بالثواني: 86400
• الاستدعاءات المجانية المجهولة في اليوم (وضع enforce فقط): 50