Ctrlk
x-twitteryoutube
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Address Labels

Retrieves all entity and behavioural labels associated with an address on a chain.

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

  • Returns the current set of labels for an address — there is no date-range parameter or historical look-back; labels reflect Nansen's latest label data and update within the standard live latency.

Empty results and credit charges

Both endpoints return HTTP 200 with data: [] when no eligible labels match the request. A successful empty response costs 0 credits, including an empty page after the last result. A nonempty response costs 100 credits for /labels or 500 credits for /premium-labels.

The balance check happens before the lookup. You still need at least 100 or 500 credits respectively to make the request. X-Nansen-Credits-Cost quotes that upfront amount; X-Nansen-Credits-Used reports the actual charge, which is 0 for an empty response. This rule applies to plan credits. Separate pay-per-request payments retain their own pricing.

Labels are scoped to chains. An address can have labels on Ethereum and none on BNB, even though the address format is valid on both. Use chain: "all" to search all chains compatible with the address format.

When the lookup finds no rows on the first page for a specific EVM chain, both endpoints return the same generic hint:

{
  "data": [],
  "hint": "Try chain: \"all\". No API credits were charged for this call."
}

The example omits the usual pagination fields. This suggestion is returned regardless of whether labels exist on another chain. The response does not include a list of available chains. Requests using chain: "all", non-EVM addresses, and empty later pages do not receive this hint.

chain: "all" returns one combined list of eligible labels across chains compatible with the address format. Each label has label, category, and kind; labels are not grouped by chain. To retrieve labels for a particular chain, request that chain explicitly. Nonempty responses retain the endpoint's 100/500-credit price.

Other reasons for an empty response include an address with no known labels, premium-only labels excluded by /labels, and exhausted pagination.

/premium-labels can return a derived address name even when no labels are scoped to the requested chain. A response containing that name is nonempty and costs 500 credits.

Retrieve address label data

post

Get labels for a wallet address. Returns non-premium labels only.

Labels include ENS domains, behavioral labels, DeFi labels, CEX labels, and more. Premium labels (smart money, alpha trader) are excluded from this endpoint.

Use /api/v1/profiler/address/premium-labels to get all labels including premium ones.

Successful empty responses cost 0 credits; nonempty responses cost 100 credits. The upfront balance check still requires 100 credits. Empty first pages for a specific EVM chain may include a generic hint to use chain="all". The hint does not report whether labels exist on other chains. Empty later pages are also free.

Authorizations
apikeystringRequired

API key for authentication

Body

Request model for Address Labels endpoint.

addressstringRequired

Wallet address to get labels for

Example: 0x4a7c6899cdcb379e284fbfd045462e751da4c7ce
chainstring · enumRequired

Blockchain chain. Use 'all' to search all chains compatible with the address format.

Example: ethereumPossible values:
Responses
200

Address labels data

application/json
post/api/v1/profiler/address/labels
POST /api/v1/profiler/address/labels HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "address": "0x4a7c6899cdcb379e284fbfd045462e751da4c7ce",
  "chain": "ethereum",
  "pagination": {
    "page": 1,
    "per_page": 100
  }
}
{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "label": "Token Millionaire",
      "category": "behavioral",
      "kind": [
        "entity",
        "name"
      ]
    }
  ],
  "hint": "text"
}

Get Address Premium Labels

post

Get all labels for a wallet address, including premium labels.

Returns all labels including smart money labels, alpha trader labels, and public figure tags that are excluded from the standard /labels endpoint.

Successful empty responses cost 0 credits; nonempty responses cost 500 credits. The upfront balance check still requires 500 credits. Empty first pages for a specific EVM chain may include a generic hint to use chain="all". The hint does not report whether labels exist on other chains. Empty later pages are also free. Derived address names can appear without labels scoped to the requested chain; these make the response nonempty and it costs 500 credits.

Authorizations
apikeystringRequired

API key for authentication

Body

Request model for Address Labels endpoint.

addressstringRequired

Wallet address to get labels for

Example: 0x4a7c6899cdcb379e284fbfd045462e751da4c7ce
chainstring · enumRequired

Blockchain chain. Use 'all' to search all chains compatible with the address format.

Example: ethereumPossible values:
Responses
200

Address labels data (including premium)

application/json
post/api/v1/profiler/address/premium-labels
POST /api/v1/profiler/address/premium-labels HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "address": "0x4a7c6899cdcb379e284fbfd045462e751da4c7ce",
  "chain": "ethereum",
  "pagination": {
    "page": 1,
    "per_page": 100
  }
}
{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "label": "Token Millionaire",
      "category": "behavioral",
      "kind": [
        "entity",
        "name"
      ]
    }
  ],
  "hint": "text"
}

Related guides

PreviousAddress PnL & Trade Performance
NextAddress Perp Positions

Last updated

Was this helpful?