Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authentication

Overview

The Nansen API uses API key authentication. All requests must include your API key in the apikey header, unless you pay per request with Agentic Payments (x402 or MPP). The OpenAPI specification lists those payment rails as security alternatives on each eligible operation.

Getting Your API Key

  1. Log in to your Nansen Account

  2. Generate a new API key

Using Your API Key

Header Format

apikey: YOUR_API_KEY

HTTP header names are case-insensitive, but Nansen docs use lowercase apikey as the canonical form.

curl Example

curl -X POST 'https://api.nansen.ai/api/v1/smart-money/holdings' \
  -H 'Content-Type: application/json' \
  -H 'apikey: YOUR_API_KEY' \
  -d '{"chains": ["ethereum"]}'

Python Example

Python with Environment Variable

Authentication Errors

Authentication failures handled by the API use the standard error envelope described in Error Handling. A key rejected by the gateway is the exception described below.

401 Unauthorized

Returned when the API key is missing, invalid, or revoked. There are two bodies to expect.

A keyless request to an API-key-only endpoint returns the full envelope, with code set to unauthenticated:

A key that is present but not recognised is rejected up front, before the request is processed, so that response carries a message only and no code:

Branch on the HTTP status first — a 401 always means authentication failed — and read code only when it is present.

Endpoints that accept Agentic Payments answer a keyless request with 402 Payment Required and a payment challenge rather than a 401.

Solutions:

  • Verify your API key is correct

  • Ensure the header name is apikey (lowercase)

  • Check that the key hasn't been revoked

403 Forbidden

Returned when the API key is valid but not permitted to call the endpoint. The body is the same envelope shown above with "status": 403; the code field names the specific reason — forbidden, plan_upgrade_required, insufficient_credits, insufficient_scope (the key lacks a permission), or api_key_disabled (the key is switched off). See Error Handling for what each one means.

Solutions:

  • Verify your subscription tier includes access to this endpoint

  • Check the key's permissions on the API page

  • Contact support to upgrade your plan

Key Permissions

Each key can be limited to what the application using it needs:

Permission
Endpoints

data

Read-only data endpoints (Token God Mode, Profiler, Smart Money, screeners, and the rest)

trading

Spot trading and bridging (/api/v1/trade/*) and Hyperliquid perps (/api/v1/perp/*)

account

Changing account state through the API, such as smart alerts (/api/v1/smart-alert*)

GET /api/v1/account and POST /api/v1/sanctions/screen work with any key. The agent endpoints (/api/v1/agent/*) need a key with the data and account permissions: the agent answers with Nansen data and can create or change your smart alerts. It can't trade through the API, so trading isn't needed. A key created before permissions existed has all three.

Permissions only narrow what a key can do. Your account's own limits still apply on top: plan features (such as Pro-only options), regional restrictions on trading, and your credit balance. A key with every permission can do exactly what your account can, and no more.

A call the key isn't permitted to make returns 403 with code insufficient_scope; required_scope names a missing permission and required_scopes lists every permission the endpoint needs. Permission changes apply within about 30 seconds.

Key Management

If your key is compromised:

  1. Immediately revoke it in your dashboard

  2. Generate a new key

  3. Update all applications using the old key

Per-key credit limits

Each key can have an optional daily and monthly credit cap, configured on the API page. Limits are positive whole credits; leaving a limit unset means unlimited. Daily limits reset at midnight UTC and monthly limits on the first day of the UTC calendar month. Existing keys remain unlimited until you set a cap.

A request that would exceed either cap is blocked before it runs with HTTP 429 and code api_key_credit_limit_reached. The body includes limit_period, credit_limit, credits_used (including in-flight reservations), and resets_at; Retry-After gives the wait in seconds. A request that costs more than the cap itself has no Retry-After, since waiting cannot help. The limit applies to that key, so other keys on the account can continue. Free requests remain free. Account balance and plan requirements still apply.

Concurrent requests reserve their quoted credits before running. A charged call counts against the UTC day and month when it was admitted, including calls that finish after midnight. Failed or uncharged calls release their reservation. In the rare case that a charge's outcome cannot be confirmed, its reservation stays counted until that window resets. Changing or removing a cap does not erase the key's current-window usage; this tracking begins when credit limits are deployed.

Last updated

Was this helpful?