Agent sign-up

Rules for agents

• Get the user's OK before you sign them up.
• Use only an email address the user gave you.
• Never read the code from the user's mailbox yourself. The user must give it to you.
• Retry 429 and 503 at most 3 times, waiting the seconds in Retry-After. Then stop and tell the user. If Retry-After is over 300 seconds, a daily limit was reached: stop at once and tell the user.
• After 403 or 410, ask the user before starting a new sign-up. Each one emails them another code.

Request a key

Send the user's email address. No API key is needed. The answer is always status 202 with the same text, so it cannot be used to find out whether an address already has an account. The api_key works at once on a pending account.

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"
}

Request fields

Response fields

If the address already has an account, its owner gets an email that says to sign in, and no code. A new address gets the code email. The code lasts 15 minutes and allows 5 wrong attempts. An address gets at most 3 code emails in 30 days.

Verify the code

The agent asks the user to read the 6-digit code aloud, then sends it with the key from the first step as a Bearer token. Sharing the code is how the user accepts the Terms. Verify is free and works at zero credit.

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\"."
}

Request fields

Response fields

On success the same key becomes a normal account, and the free credit of $10 a month for 12 months starts on the verify date.

Check the status

Free, and it needs the key. It says where the sign-up stands.

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
}

Response fields

Limits before and after verify

Every response to a pending key carries X-Narwhal-Account-State: pending. Sign-up, verify and status calls are never charged. Prices are $2 per 1,000 calls, and $10 per 1,000 for Companies.

When the trial credit runs out, a data call returns 402 insufficient_credits with verify_required: true and a message_for_user for the agent to show.

{
  "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\"."
}

If the user never shares the code, the key keeps working until the trial credit runs out or 7 days pass.

The code email names the agent, its tool and the country of the request. It has a link called "This wasn't me" that opens a page with one button. Opening the link changes nothing; pressing the button revokes the key and stops Narwhal emailing that address.

Errors

Errors use the problem shape in the errors guide: branch on status, then code.

Read the full errors guide

Data by Narwhal API

While an account holds only free credit, show Narwhal data to people with the credit "Data by Narwhal API" and a link to Narwhal API. The verify message and the message_for_user of a 402 repeat this rule. Accounts with paid credit may show data without a credit.

Sign in later

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. The authentication guide covers storing and rotating the key.