에이전트 가입

에이전트를 위한 규칙

• 사용자를 가입시키기 전에 사용자의 동의를 받으세요.
• 사용자가 알려 준 이메일 주소만 사용하세요.
• 사용자의 메일함에서 코드를 직접 읽지 마세요. 사용자가 직접 알려 줘야 합니다.
• 429와 503은 최대 3번까지만 다시 시도하고, 그때마다 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분 동안 유효하고 틀릴 수 있는 횟수는 5번입니다. 한 주소로 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"라는 링크는 버튼이 하나뿐인 페이지를 엽니다. 링크를 여는 것만으로는 아무것도 바뀌지 않습니다. 버튼을 누르면 키가 폐기되고 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.