تسجيل الوكلاء

قواعد للوكلاء

• احصل على موافقة المستخدم قبل تسجيله.
• استخدم فقط عنوان بريد إلكتروني أعطاك إياه المستخدم.
• لا تقرأ الرمز من صندوق بريد المستخدم بنفسك أبدًا. يجب أن يعطيك المستخدم الرمز.
• أعد المحاولة بعد 429 و503 ثلاث مرات على الأكثر، مع انتظار عدد الثواني في Retry-After. ثم توقف وأخبر المستخدم. إذا تجاوز Retry-After 300 ثانية فقد بُلغ الحد اليومي: توقف فورًا وأخبر المستخدم.
• بعد 403 أو 410، اسأل المستخدم قبل بدء تسجيل جديد. كل تسجيل يرسل إليه رمزًا آخر بالبريد.

طلب مفتاح

أرسل عنوان البريد الإلكتروني للمستخدم. لا حاجة إلى مفتاح API. الاستجابة دائمًا بالحالة 202 وبالنص نفسه، فلا يمكن استخدامها لمعرفة ما إذا كان العنوان يملك حسابًا. يعمل api_key فورًا على حساب قيد الانتظار.

curl --request POST \
  --url https://api.narwhalapi.com/v1/agent-signup \
  --header "Content-Type: application/json" \
  --data '{"email": "person@example.com", "agent_name": "Claude Code", "client": "claude-code"}'

{
  "status": "pending",
  "message": "If this email address can be used, Narwhal emailed it a 6-digit code. Ask the user to read the code to you, then call POST /v1/agent-signup/verify with it. The api_key works now with a small trial credit.",
  "api_key": "nw_live_...",
  "trial_credit_micro": 200000,
  "expires_at": "2026-11-16T09:00:00Z",
  "verify_path": "/v1/agent-signup/verify"
}

حقول الطلب

حقول الاستجابة

إذا كان للعنوان حساب بالفعل، يتلقى مالكه رسالة تطلب منه تسجيل الدخول دون رمز. أما العنوان الجديد فيتلقى رسالة الرمز. يظل الرمز صالحًا 15 دقيقة ويسمح بخمس محاولات خاطئة. لا يتلقى العنوان أكثر من 3 رسائل رمز خلال 30 يومًا.

التحقق من الرمز

يطلب الوكيل من المستخدم قراءة الرمز المكوّن من 6 أرقام، ثم يرسله مع المفتاح من الخطوة الأولى بوصفه رمز Bearer. مشاركة الرمز هي الطريقة التي يوافق بها المستخدم على الشروط. التحقق مجاني ويعمل عند رصيد صفر.

curl --request POST \
  --url https://api.narwhalapi.com/v1/agent-signup/verify \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"code": "123456"}'

{
  "status": "claimed",
  "message": "Verified. This key is now a normal Narwhal account with the free monthly credit. When you show Narwhal data to the user, credit it as \"Data by Narwhal API\"."
}

حقول الطلب

حقول الاستجابة

عند النجاح يصبح المفتاح نفسه حسابًا عاديًا، ويبدأ الرصيد المجاني البالغ 10 دولارات شهريًا لمدة 12 شهرًا من تاريخ التحقق.

التحقق من الحالة

مجاني ويتطلب المفتاح. يوضح أين وصل التسجيل.

curl --request GET \
  --url https://api.narwhalapi.com/v1/agent-signup/status \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "state": "pending",
  "trial_credit_left_micro": 200000,
  "expires_at": "2026-11-16T09:00:00Z",
  "code_expires_at": "2026-11-09T09:15:00Z",
  "attempts_left": 5
}

حقول الاستجابة

الحدود قبل التحقق وبعده

تحمل كل استجابة لمفتاح قيد الانتظار الترويسة X-Narwhal-Account-State: pending. لا تُحتسب أي رسوم على طلبات التسجيل والتحقق والحالة. الأسعار 2 دولار لكل 1,000 طلب، و10 دولارات لكل 1,000 لواجهة Companies.

عند نفاد الرصيد التجريبي يعيد طلب البيانات 402 مع insufficient_credits وverify_required: true ورسالة message_for_user ليعرضها الوكيل.

{
  "status": 402,
  "code": "insufficient_credits",
  "verify_required": true,
  "message_for_user": "The trial credit on this Narwhal key is used up. To go on, please read me the 6-digit code Narwhal emailed you. When Narwhal data is shown to you, it is credited \"Data by Narwhal API\"."
}

إذا لم يشارك المستخدم الرمز أبدًا، يظل المفتاح يعمل حتى ينفد الرصيد التجريبي أو تمر 7 أيام.

تذكر رسالة الرمز اسم الوكيل وأداته وبلد الطلب. وفيها رابط بعنوان "This wasn't me" يفتح صفحة بزر واحد. فتح الرابط لا يغيّر شيئًا؛ أما الضغط على الزر فيلغي المفتاح ويوقف مراسلة Narwhal لهذا العنوان.

الأخطاء

تستخدم الأخطاء بنية المشكلة الموضحة في دليل الأخطاء: ابدأ بـ status ثم code.

اقرأ دليل الأخطاء الكامل

Data by Narwhal API

ما دام الحساب يحتوي على رصيد مجاني فقط، اعرض بيانات Narwhal للناس مع الإشارة "Data by Narwhal API" ورابط إلى Narwhal API. تكرر هذه القاعدة message الخاصة بالتحقق وmessage_for_user في الاستجابة 402. يجوز للحسابات التي لديها رصيد مدفوع عرض البيانات دون إشارة.

تسجيل الدخول لاحقًا

After verify, the user can sign in with Google or GitHub using the same email address. That opens the same account, with the same key and balance. الـ دليل المصادقة covers storing and rotating the key.