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
Log in to your Nansen Account
Generate a new API key
Using Your API Key
Header Format
apikey: YOUR_API_KEYHTTP 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:
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:
Immediately revoke it in your dashboard
Generate a new key
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?