Authentication

Overview

The Nansen API uses API key authentication. All requests must include your API key in the apikey header.

Getting Your API Key

1. Log in to your Nansen Dashboard

2. Generate a new API key

Using Your API Key

Header Format

apikey: YOUR_API_KEY

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

import httpx

headers = {
    "Content-Type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = httpx.post(
    "https://api.nansen.ai/api/v1/smart-money/holdings",
    headers=headers,
    json={"chains": ["ethereum"]}
)

Python with Environment Variable

import os
import httpx

API_KEY = os.environ.get("NANSEN_API_KEY")

headers = {
    "Content-Type": "application/json",
    "apikey": API_KEY
}

response = httpx.post(
    "https://api.nansen.ai/api/v1/smart-money/holdings",
    headers=headers,
    json={"chains": ["ethereum"]}
)

Authentication Errors

401 Unauthorized

Returned when the API key is missing or invalid:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

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 doesn't have permission for the requested resource:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this endpoint"
  }
}

Solutions:

• Verify your subscription tier includes access to this endpoint

• Contact support to upgrade your plan

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