Search

Search across all categories

post

Search for tokens and entities by name, symbol, or contract address. This endpoint provides a unified search experience across all Nansen data.

Use Cases:

1. Find token addresses: Search by name or symbol to get contract addresses (e.g., "AAVE", "Uniswap")

2. Discover entities: Find known entities like exchanges, funds, and public figures (e.g., "vitalik", "Binance")

3. Resolve addresses: Search by contract address to identify tokens

4. Filter by chain: Narrow down results to specific blockchains

Search Parameters:

• search_query: Token name, symbol, contract address, or entity name

• result_type: Filter by "token", "entity", or "any" (default: "any")

• chain: Optional blockchain filter (e.g., "ethereum", "solana", "base")

• limit: Maximum results (1-50, default: 25)

Example Request:

{
  "search_query": "AAVE",
  "result_type": "token",
  "chain": "ethereum"
}

Example Response:

{
  "tokens": [
    {
      "name": "Aave",
      "symbol": "AAVE",
      "chain": "ethereum",
      "address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
      "price": 123.45,
      "volume_24h": 50000000,
      "market_cap": 1500000000,
      "rank": 25
    }
  ],
  "entities": [],
  "total_results": 1
}

Important Notes:

• Prices may be delayed; use token OHLCV endpoints for real-time prices

• Results are sorted by relevance/popularity rank

• Use the chain parameter (not the query string) to filter by blockchain

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for general search endpoint.

This endpoint searches for tokens and entities by name, symbol, or address.

search_querystring · min: 1 · max: 200Required

Search query - token name, symbol, contract address, or entity name.

Example: AAVE

result_typestring · enumOptional

Type filter - 'token' for tokens only, 'entity' for entities only, 'any' for both.

Default: anyPossible values:

chainany ofOptional

Optional chain filter to narrow down token results (e.g., 'ethereum', 'solana', 'base').

Example: ethereum

stringOptional

limitinteger · min: 1 · max: 50Optional

Maximum number of results to return (default: 25, max: 50).

Default: 25

Responses

200

Search results with tokens and entities

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post/api/v1/search/general

HTTPcURLJavaScriptPython

POST /api/v1/search/general HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "search_query": "AAVE",
  "result_type": "any",
  "chain": "ethereum",
  "limit": 25
}

{
  "tokens": [
    {
      "name": "text",
      "symbol": "text",
      "chain": "text",
      "address": "text",
      "price": 1,
      "volume_24h": 1,
      "market_cap": 1,
      "rank": 1
    }
  ],
  "entities": [
    {
      "name": "text",
      "tags": [
        "text"
      ],
      "rank": 1
    }
  ],
  "total_results": 1
}

Search for entity names by query

post

Search for entity names to use in other v1 endpoints that support entity_name parameters.

This endpoint helps users find the correct entity name format when they want to query by entity instead of address. Many endpoints accept either address or entity_name as parameters, but entity names must match exactly. This search endpoint makes it easy to find the right entity name.

Key Features:

• Case-insensitive search that matches anywhere in the entity name

• Returns up to 100 results ordered alphabetically

• Minimum 2 character search query required

• Free endpoint (0 credits)

Use Cases:

1. Find entity names for profiler endpoints: Search "vitalik" to find "Vitalik Buterin" for use in address balance or transaction queries

2. Discover exchange entities: Search "binance" to find all Binance-related entities

3. Locate fund entities: Search "jump" to find "Jump Trading" and related entities

Example Usage:

{
  "search_query": "vitalik"
}

Response:

{
  "data": [
    {"entity_name": "Vitalik Buterin"},
    {"entity_name": "Vitalik Buterin: Charity"}
  ]
}

Note: This endpoint does not support pagination as results are capped at 100 items.

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for entity name search endpoint.

This endpoint helps users find the correct entity_name to use in other v1 endpoints that accept entity_name as a parameter.

search_querystring · min: 2 · max: 100Required

Search query for entity names (minimum 2 characters). Search is case-insensitive and matches anywhere in the entity name.

Example: vitalik

Responses

200

List of matching entity names

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post/api/v1/search/entity-name

HTTPcURLJavaScriptPython

POST /api/v1/search/entity-name HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "search_query": "vitalik"
}

{
  "data": [
    {
      "entity_name": "text"
    }
  ]
}

Get Available Token Sectors

get

Get all available token sectors that can be used to filter tokens in the token-screener and other endpoints.

This endpoint returns the list of valid sector values that can be used in the token_sector filter parameter. Sectors are categories that describe a token's primary use case or market segment (e.g., "Artificial Intelligence", "DeFi Lending", "Memecoin").

Key Features:

• Returns all sectors with 50+ tokens (filters out niche/one-off AI-generated sectors)

• Results are ordered alphabetically

• No parameters required

• Free endpoint (0 credits)

Example Response:

{
  "data": [
    {"sector": "AI Agents"},
    {"sector": "Artificial Intelligence"},
    {"sector": "DeFi Lending (Money Markets)"},
    {"sector": "GameFi"},
    {"sector": "Memecoin"}
  ]
}

Use Cases:

1. Discover filter options: Get valid sector values before calling token-screener

2. Build UI filters: Populate dropdown menus with available sectors

3. Validate input: Check if a sector value is valid before making API calls

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Responses

200

List of available token sectors

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

get/api/v1/search/token-sectors

HTTPcURLJavaScriptPython

GET /api/v1/search/token-sectors HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "sector": "text"
    }
  ]
}