瀏覽全部文件

智慧代理註冊

Let an AI agent get a Narwhal API key for its user.

AI 智慧代理無需瀏覽器即可為使用者取得 Narwhal API 金鑰。代理傳送使用者的電子郵件地址，立即得到一把可用的金鑰，並附有少量試用額度。使用者把郵件中的 6 位數驗證碼告訴代理，代理完成驗證後，同一把金鑰就成為正式帳戶。

代理可以在 /auth.md 以純 markdown 格式讀取相同的流程。

給代理的規則

  • 在為使用者註冊之前，先徵得使用者同意。
  • 只使用使用者提供給你的電子郵件地址。
  • 絕不要自己去讀取使用者信箱裡的驗證碼，必須由使用者告訴你。
  • 429 和 503 最多重試 3 次，每次等待 Retry-After 中的秒數。之後就停下來，告訴使用者。如果 Retry-After 超過 300 秒，表示已達每日上限：請立即停止並告訴使用者。
  • 出現 403 或 410 後，重新註冊前先詢問使用者。每次註冊都會再寄給使用者一封驗證碼郵件。

申請金鑰

傳送使用者的電子郵件地址，無需 API 金鑰。回應一律是狀態 202 和相同的文字，因此無法藉此判斷某個地址是否已有帳戶。api_key 在待驗證帳戶上立即可用。

POST /v1/agent-signup
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"
}

請求欄位

欄位必填含義
email是使用者的電子郵件地址。Narwhal 會向它寄送 6 位數驗證碼。一次性電子郵件網域會被拒絕。
agent_name是代理給自己取的名稱：1 到 80 個字母、數字、空格或 _ - / ( )。句點只能出現在兩個數字之間，例如版本號。不能包含網址、網域或冒號。郵件會把它顯示給使用者。
client否代理所執行的工具，例如 claude-code 或 cursor：小寫字母、數字、_ 和 -，最多 40 個字元。

回應欄位

欄位含義
status在驗證碼通過之前一律為 pending。
message每個請求都是相同的文字。
api_key待驗證帳戶上的可用金鑰。請妥善保密，它只顯示一次。
trial_credit_micro一次性試用額度，單位為微美元（1,000,000 等於 1 美元）。200000 即 0.20 美元。
expires_at未驗證時金鑰停止運作的時間：請求後 7 天。
verify_path使用者告知的驗證碼應傳送到的路徑。

如果該地址已有帳戶，其擁有者會收到提示登入的郵件，而不會收到驗證碼。新地址會收到驗證碼郵件。驗證碼有效期為 15 分鐘，最多可輸錯 5 次。同一地址在 30 天內最多收到 3 封驗證碼郵件。

驗證驗證碼

代理請使用者念出 6 位數驗證碼，然後把第一步得到的金鑰作為 Bearer 權杖，連同驗證碼一起傳送。使用者告知驗證碼，即表示接受條款。驗證免費，額度為零時也能使用。

POST /v1/agent-signup/verify
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\"."
}

請求欄位

欄位必填含義
code是The 6-digit code from the email Narwhal sent to the user.

回應欄位

欄位含義
status驗證碼通過後為 claimed。
message確認帳戶，並重申署名規則。

驗證成功後，同一把金鑰變為一般帳戶，每月 10 美元、為期 12 個月的免費額度從驗證之日起計算。

查看狀態

免費，需要使用金鑰。它會告訴你註冊進行到哪一步。

GET /v1/agent-signup/status
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
}

回應欄位

欄位含義
statepending、claimed、expired 或 blocked。
trial_credit_left_micro剩餘試用額度，單位為微美元。待驗證期間才會出現。
expires_at未驗證時金鑰停止運作的時間。待驗證期間才會出現。
code_expires_at郵件中的驗證碼失效的時間。待驗證期間才會出現。
attempts_left驗證碼被鎖定前還能輸錯的次數。待驗證期間才會出現。
verified_at使用者完成驗證的時間。驗證後才會出現。

驗證前後的限制

驗證前（待驗證）驗證後
額度一次性試用額度 0.20 美元，按每 1,000 次 2 美元計，約可呼叫資料 100 次。12 個月內每月免費 10 美元，無需綁卡，之後為預付儲值。
每分鐘請求數10僅有免費額度時為 50，帳戶持有付費額度後為 500。
Webhook、事件串流、團隊邀請和儲值不可用。可用。
有效期7 天，之後金鑰會被撤銷。適用一般規則。

對待驗證金鑰的每個回應都帶有 X-Narwhal-Account-State: pending。註冊、驗證和狀態呼叫從不收費。價格為每 1,000 次呼叫 2 美元，Companies 為每 1,000 次 10 美元。

試用額度用完後，資料呼叫會回傳 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 不再向該地址寄信。

錯誤

錯誤使用錯誤指南中的 problem 格式：先依 status 分支，再依 code 分支。

狀態公開錯誤代碼端點含義
400invalid_query全部欄位缺失或格式錯誤，例如電子郵件不是一般地址，或驗證碼不是 6 位數字。
400invalid_code驗證驗證碼錯誤。訊息會說明還剩幾次機會。
401invalid_api_key驗證、狀態Bearer 金鑰缺失、格式錯誤、未知或已被撤銷。
402insufficient_credits資料呼叫試用額度已用完。回應內容會增加 verify_required 和 message_for_user。
403code_locked驗證輸錯驗證碼次數過多。重新註冊前請先詢問使用者。
403account_pendingWebhook、串流票證待驗證的金鑰不能使用 Webhook 或事件串流。
404not_an_agent_account狀態此金鑰不是透過代理註冊取得的。
404block_link_invalid封鎖郵件中的連結無效。
404route_not_found全部智慧代理註冊尚未開啟。
409email_has_account驗證該地址已有帳戶，金鑰已被撤銷，請讓使用者直接登入。
409already_verified驗證、封鎖該金鑰已驗證。驗證碼不能重複使用。
409not_pending驗證該註冊已不再等待驗證（已過期或已被封鎖）。
409verify_in_progress驗證、封鎖此金鑰的另一次驗證正在進行。請查看狀態。
410code_expired驗證驗證碼已過期。重新註冊前請先詢問使用者。
422agent_name_not_allowed請求代理名稱包含不允許的字元。
422email_domain_not_allowed請求該電子郵件網域屬於一次性電子郵件服務。
429rate_limit_exceeded全部此網路的請求過多，或待驗證金鑰每分鐘的請求過多。請等待 Retry-After 中給出的秒數。
429domain_daily_limit驗證今天此電子郵件網域下完成驗證的帳戶過多。請在 UTC 00:00 之後用同一個驗證碼重試。
503agent_signup_unavailable請求、封鎖註冊暫時無法使用，或已達到每日上限。請查看 Retry-After。
503verify_unavailable驗證驗證暫時無法使用。請用同一個驗證碼重試。

閱讀完整的錯誤指南

Data by Narwhal API

帳戶只有免費額度時，向他人展示 Narwhal 資料需註明 "Data by Narwhal API" 並附上指向 Narwhal API 的連結。驗證成功時的 message 和 402 的 message_for_user 都重複了這條規則。持有付費額度的帳戶可以不註明來源直接展示資料。

之後登入

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.

此頁面對你有幫助嗎?