エージェントのサインアップ

エージェント向けのルール

• ユーザーをサインアップさせる前に、ユーザーの了承を得てください。
• ユーザーが教えてくれたメールアドレスだけを使ってください。
• ユーザーのメールボックスからコードを自分で読み取ってはいけません。コードはユーザーが伝える必要があります。
• 429 と 503 の再試行は最大3回までとし、Retry-After の秒数だけ待ってください。それでもだめなら中止して、ユーザーに伝えてください。Retry-After が300秒を超える場合は1日の上限に達しています。すぐに中止して、ユーザーに伝えてください。
• 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分で、間違えられるのは5回までです。1つのアドレスに送るコードのメールは30日間で最大3通です。

コードを確認する

エージェントはユーザーに6桁のコードを読み上げてもらい、最初の手順で受け取ったキーを Bearer トークンとして付けて送信します。コードを伝えることが、ユーザーが規約に同意する方法です。確認は無料で、クレジットが0でも使えます。

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 が付きます。サインアップ、確認、ステータスの呼び出しに料金はかかりません。料金は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」というリンクは、ボタンが1つだけのページを開きます。リンクを開くだけでは何も変わりません。ボタンを押すとキーが失効し、Narwhal はそのアドレスにメールを送らなくなります。

エラー

エラーはエラーガイドの problem 形式を使います。まず status、次に code で分岐してください。

エラーガイド全体を読む

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.