# Search

## General Search

> 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

````json
{"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apiKey","description":"API key for authentication"}},"schemas":{"GeneralSearchRequest":{"properties":{"search_query":{"type":"string","maxLength":200,"minLength":1,"title":"Search Query","description":"Search query - token name, symbol, contract address, or entity name."},"result_type":{"type":"string","enum":["token","entity","any"],"title":"Result Type","description":"Type filter - 'token' for tokens only, 'entity' for entities only, 'any' for both.","default":"any"},"chain":{"anyOf":[{"type":"string"}],"title":"Chain","description":"Optional chain filter to narrow down token results (e.g., 'ethereum', 'solana', 'base')."},"limit":{"type":"integer","maximum":50,"minimum":1,"title":"Limit","description":"Maximum number of results to return (default: 25, max: 50).","default":25}},"additionalProperties":false,"type":"object","required":["search_query"],"title":"GeneralSearchRequest","description":"Request model for general search endpoint.\n\nThis endpoint searches for tokens and entities by name, symbol, or address."},"GeneralSearchResponse":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/TokenSearchResult"},"type":"array","title":"Tokens","description":"List of matching tokens","default":[]},"entities":{"items":{"$ref":"#/components/schemas/EntitySearchResult"},"type":"array","title":"Entities","description":"List of matching entities","default":[]},"total_results":{"type":"integer","title":"Total Results","description":"Total number of results returned"}},"type":"object","required":["total_results"],"title":"GeneralSearchResponse","description":"Response model for general search endpoint.\n\nReturns separate lists for tokens and entities, allowing clients to handle\neach type appropriately."},"TokenSearchResult":{"properties":{"name":{"type":"string","title":"Name","description":"Token name"},"symbol":{"type":"string","title":"Symbol","description":"Token symbol (ticker)"},"chain":{"type":"string","title":"Chain","description":"Blockchain the token is deployed on"},"address":{"type":"string","title":"Address","description":"Contract address of the token"},"price":{"anyOf":[{"type":"number"}],"title":"Price","description":"Current price in USD (may be delayed)"},"volume_24h":{"anyOf":[{"type":"number"}],"title":"Volume 24H","description":"24-hour trading volume in USD"},"market_cap":{"anyOf":[{"type":"number"}],"title":"Market Cap","description":"Market capitalization in USD"},"rank":{"anyOf":[{"type":"integer"}],"title":"Rank","description":"Popularity/relevance rank (lower is better)"}},"type":"object","required":["name","symbol","chain","address"],"title":"TokenSearchResult","description":"A token result from general search."},"EntitySearchResult":{"properties":{"name":{"type":"string","title":"Name","description":"Entity name"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Category tags for the entity","default":[]},"rank":{"anyOf":[{"type":"integer"}],"title":"Rank","description":"Popularity/relevance rank (lower is better)"}},"type":"object","required":["name"],"title":"EntitySearchResult","description":"An entity result from general search."}},"headers":{"XNansenCreditsUsed":{"description":"Number of credits consumed by this API request","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Time in seconds until the rate limit window resets","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via the x402 protocol. The `Payment-Required` response header contains a base64-encoded JSON object describing accepted payment options (scheme, network, asset, amount, recipient). To pay, include a `Payment-Signature` header with a base64-encoded signed payment payload. See https://www.x402.org for protocol details.","headers":{"Payment-Required":{"description":"Base64-encoded JSON describing accepted payment options","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","description":"Empty object. Payment details are in the Payment-Required header."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":"string"}},"msg":{"type":"string"},"type":{"type":"string"}}}}}}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}},"paths":{"/api/v1/search/general":{"post":{"tags":["Search"],"summary":"General Search","description":"Search for tokens and entities by name, symbol, or contract address. This endpoint provides a unified search experience across all Nansen data.\n\n**Use Cases:**\n1. **Find token addresses**: Search by name or symbol to get contract addresses (e.g., \"AAVE\", \"Uniswap\")\n2. **Discover entities**: Find known entities like exchanges, funds, and public figures (e.g., \"vitalik\", \"Binance\")\n3. **Resolve addresses**: Search by contract address to identify tokens\n4. **Filter by chain**: Narrow down results to specific blockchains\n\n**Search Parameters:**\n- `search_query`: Token name, symbol, contract address, or entity name\n- `result_type`: Filter by \"token\", \"entity\", or \"any\" (default: \"any\")\n- `chain`: Optional blockchain filter (e.g., \"ethereum\", \"solana\", \"base\")\n- `limit`: Maximum results (1-50, default: 25)\n\n**Example Request:**\n```json\n{\n  \"search_query\": \"AAVE\",\n  \"result_type\": \"token\",\n  \"chain\": \"ethereum\"\n}\n```\n\n**Example Response:**\n```json\n{\n  \"tokens\": [\n    {\n      \"name\": \"Aave\",\n      \"symbol\": \"AAVE\",\n      \"chain\": \"ethereum\",\n      \"address\": \"0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9\",\n      \"price\": 123.45,\n      \"volume_24h\": 50000000,\n      \"market_cap\": 1500000000,\n      \"rank\": 25\n    }\n  ],\n  \"entities\": [],\n  \"total_results\": 1\n}\n```\n\n**Important Notes:**\n- Prices may be delayed; use token OHLCV endpoints for real-time prices\n- Results are sorted by relevance/popularity rank\n- Use the `chain` parameter (not the query string) to filter by blockchain","operationId":"general_search_api_v1_search_general_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralSearchRequest"}}},"required":true},"responses":{"200":{"description":"Search results with tokens and entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralSearchResponse"}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"}}}}}}
````