浏览全部文档

智能体注册

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.

此页面对你有帮助吗?