# Nansen General Search

> Nansen General Search is a free API for AI agents from Nansen at api.nansen.ai, Free, status unknown (last checked 2026-10-11).

Search for crypto tokens and on-chain entities by name, symbol, contract address, or entity name across all Nansen data

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/search/general?utm_source=zero.xyz
- Price: Free
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-general-107285db
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_vsdkWD_1JwcLZjSuSOy_R

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nansen-general-107285db -d '<json body>'
```

Example prompt: Can you look up the contract address and price for AAVE on Ethereum using Nansen's search? Search for token type only.

## When to prefer this

Use this endpoint when you need to resolve a token name or symbol to its contract address, identify an entity by name, or discover metadata about tokens before calling more specific Nansen endpoints like DEX trades or wallet profiling. Prefer this over chain-specific lookups when you don't know which chain a token is on. It's the right starting point for any workflow that needs to map human-readable names to on-chain identifiers.

## Known failure modes

- Empty results if the search query matches no known tokens or entities
- Chain filter mismatch returns no tokens if the token doesn't exist on the specified chain
- Overly broad queries may return up to 50 results requiring further filtering
- Contract address typos result in zero matches
- Prices may be delayed or missing for low-liquidity tokens
- Request fails with validation error if search_query is empty or exceeds 200 characters
- Limit parameter out of range (below 1 or above 50) returns validation error

## How this service works

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:**
```json
{
  "search_query": "AAVE",
  "result_type": "token",
  "chain": "ethereum"
}
```

**Example Response:**
```json
{
  "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

## Output

Returns two lists — matched tokens (with name, symbol, chain, contract address, price, 24h volume, market cap, and rank) and matched entities (with name, rank, and category tags) — plus a total result count. Results are ordered by relevance and popularity rank.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "GeneralSearchRequest",
 "required": [
  "search_query"
 ],
 "properties": {
  "chain": {
   "anyOf": [
    {
     "type": "string"
    }
   ],
   "title": "Chain",
   "examples": [
    "ethereum",
    "solana",
    "base",
    "bnb",
    "polygon"
   ],
   "description": "Optional chain filter to narrow down token results (e.g., 'ethereum', 'solana', 'base')."
  },
  "limit": {
   "type": "integer",
   "title": "Limit",
   "default": 25,
   "maximum": 50,
   "minimum": 1,
   "description": "Maximum number of results to return (default: 25, max: 50)."
  },
  "result_type": {
   "enum": [
    "token",
    "entity",
    "any"
   ],
   "type": "string",
   "title": "Result Type",
   "default": "any",
   "description": "Type filter - 'token' for tokens only, 'entity' for entities only, 'any' for both."
  },
  "search_query": {
   "type": "string",
   "title": "Search Query",
   "examples": [
    "AAVE",
    "vitalik",
    "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"
   ],
   "maxLength": 200,
   "minLength": 1,
   "description": "Search query - token name, symbol, contract address, or entity name."
  }
 },
 "description": "Request model for general search endpoint.\n\nThis endpoint searches for tokens and entities by name, symbol, or address.",
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "GeneralSearchResponse",
 "required": [
  "total_results"
 ],
 "properties": {
  "tokens": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TokenSearchResult",
    "required": [
     "name",
     "symbol",
     "chain",
     "address"
    ],
    "properties": {
     "name": {
      "type": "string",
      "title": "Name",
      "description": "Token name"
     },
     "rank": {
      "anyOf": [
       {
        "type": "integer"
       }
      ],
      "title": "Rank",
      "description": "Popularity/relevance rank (lower is better)"
     },
     "chain": {
      "type": "string",
      "title": "Chain",
      "description": "Blockchain the token is deployed on"
     },
     "price": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Price",
      "description": "Current price in USD (may be delayed)"
     },
     "symbol": {
      "type": "string",
      "title": "Symbol",
      "description": "Token symbol (ticker)"
     },
     "address": {
      "type": "string",
      "title": "Address",
      "description": "Contract address of the token"
     },
     "market_cap": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Market Cap",
      "description": "Market capitalization in USD"
     },
     "volume_24h": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Volume 24H",
      "description": "24-hour trading volume in USD"
     }
    },
    "description": "A token result from general search."
   },
   "title": "Tokens",
   "default": [],
   "description": "List of matching tokens"
  },
  "entities": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "EntitySearchResult",
    "required": [
     "name"
    ],
    "properties": {
     "name": {
      "type": "string",
      "title": "Name",
      "description": "Entity name"
     },
     "rank": {
      "anyOf": [
       {
        "type": "integer"
       }
      ],
      "title": "Rank",
      "description": "Popularity/relevance rank (lower is better)"
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "title": "Tags",
      "default": [],
      "description": "Category tags for the entity"
     }
    },
    "description": "An entity result from general search."
   },
   "title": "Entities",
   "default": [],
   "description": "List of matching entities"
  },
  "total_result
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-general-107285db/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)