# Agent

## Fast Research Agent

> Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The \*\*fast\*\* variant uses a lighter model optimised for low-latency responses.\
> \
> \*\*What it helps to answer:\*\*\
> \
> 1\. \*\*Which tokens are smart money accumulating right now?\*\*\
> 2\. \*\*What is the current narrative driving activity in DeFi?\*\*\
> 3\. \*\*Which wallets are connected to a specific address?\*\*\
> 4\. \*\*What is the on-chain story behind a recent price move?\*\*\
> \
> \*\*SSE event types:\*\*\
> \
> The response is a \`text/event-stream\` with the following JSON event types:\
> \
> \| type | payload | description |\
> \|---|---|---|\
> \| \`delta\` | \`{"type": "delta", "text": "…"}\` | Incremental text chunk of the agent's answer. |\
> \| \`tool\_call\` | \`{"type": "tool\_call", "name": "…"}\` | Emitted once per unique Nansen tool the agent invokes. |\
> \| \`finish\` | \`{"type": "finish", "conversation\_id": "…", "tool\_calls": \[...]}\` | Final event. Contains the \`conversation\_id\` for follow-up requests and the full list of tools used. |\
> \| \`error\` | \`{"type": "error", "error": "…", "status\_code": …}\` | Emitted if the upstream agent service is unavailable or times out. |\
> \
> The stream terminates with a \`data: \[DONE]\` sentinel.\
> \
> \*\*Fast vs Expert:\*\* Use \`/agent/fast\` for quick factual lookups and simple questions. Use \`/agent/expert\` when you need deeper multi-step analysis or synthesis across multiple data sources.

```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":{"AgentResearchRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Research query or question for the Nansen AI agent."},"conversation_id":{"anyOf":[{"type":"string"}],"title":"Conversation Id","description":"Optional conversation ID for multi-turn interactions. Returned in the finish event of a previous response. Omit to start a new conversation."}},"type":"object","required":["text"],"title":"AgentResearchRequest","description":"Request model for Agent Research endpoints (fast and expert)."}},"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/agent/fast":{"post":{"tags":["Agent"],"summary":"Fast Research Agent","description":"Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The **fast** variant uses a lighter model optimised for low-latency responses.\n\n**What it helps to answer:**\n\n1. **Which tokens are smart money accumulating right now?**\n2. **What is the current narrative driving activity in DeFi?**\n3. **Which wallets are connected to a specific address?**\n4. **What is the on-chain story behind a recent price move?**\n\n**SSE event types:**\n\nThe response is a `text/event-stream` with the following JSON event types:\n\n| type | payload | description |\n|---|---|---|\n| `delta` | `{\"type\": \"delta\", \"text\": \"…\"}` | Incremental text chunk of the agent's answer. |\n| `tool_call` | `{\"type\": \"tool_call\", \"name\": \"…\"}` | Emitted once per unique Nansen tool the agent invokes. |\n| `finish` | `{\"type\": \"finish\", \"conversation_id\": \"…\", \"tool_calls\": [...]}` | Final event. Contains the `conversation_id` for follow-up requests and the full list of tools used. |\n| `error` | `{\"type\": \"error\", \"error\": \"…\", \"status_code\": …}` | Emitted if the upstream agent service is unavailable or times out. |\n\nThe stream terminates with a `data: [DONE]` sentinel.\n\n**Fast vs Expert:** Use `/agent/fast` for quick factual lookups and simple questions. Use `/agent/expert` when you need deeper multi-step analysis or synthesis across multiple data sources.","operationId":"agent_fast_api_v1_agent_fast_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResearchRequest"}}},"required":true},"responses":{"200":{"description":"Server-Sent Events stream. Each event is a `data: {json}` line. See endpoint description for event schema.","content":{"application/json":{"schema":{}},"text/event-stream":{}},"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"}}}}}}
```

## Expert Research Agent

> Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The \*\*expert\*\* variant uses a more capable model for deeper, multi-step analysis.\
> \
> \*\*What it helps to answer:\*\*\
> \
> 1\. \*\*Which tokens are smart money accumulating right now?\*\*\
> 2\. \*\*What is the current narrative driving activity in DeFi?\*\*\
> 3\. \*\*Which wallets are connected to a specific address?\*\*\
> 4\. \*\*What is the on-chain story behind a recent price move?\*\*\
> \
> \*\*SSE event types:\*\*\
> \
> The response is a \`text/event-stream\` with the following JSON event types:\
> \
> \| type | payload | description |\
> \|---|---|---|\
> \| \`delta\` | \`{"type": "delta", "text": "…"}\` | Incremental text chunk of the agent's answer. |\
> \| \`tool\_call\` | \`{"type": "tool\_call", "name": "…"}\` | Emitted once per unique Nansen tool the agent invokes. |\
> \| \`finish\` | \`{"type": "finish", "conversation\_id": "…", "tool\_calls": \[...]}\` | Final event. Contains the \`conversation\_id\` for follow-up requests and the full list of tools used. |\
> \| \`error\` | \`{"type": "error", "error": "…", "status\_code": …}\` | Emitted if the upstream agent service is unavailable or times out. |\
> \
> The stream terminates with a \`data: \[DONE]\` sentinel.\
> \
> \*\*Fast vs Expert:\*\* Use \`/agent/fast\` for quick factual lookups and simple questions. Use \`/agent/expert\` when you need deeper multi-step analysis or synthesis across multiple data sources.

```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":{"AgentResearchRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Research query or question for the Nansen AI agent."},"conversation_id":{"anyOf":[{"type":"string"}],"title":"Conversation Id","description":"Optional conversation ID for multi-turn interactions. Returned in the finish event of a previous response. Omit to start a new conversation."}},"type":"object","required":["text"],"title":"AgentResearchRequest","description":"Request model for Agent Research endpoints (fast and expert)."}},"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/agent/expert":{"post":{"tags":["Agent"],"summary":"Expert Research Agent","description":"Ask the Nansen AI agent a research question and receive a streamed answer backed by on-chain data. The **expert** variant uses a more capable model for deeper, multi-step analysis.\n\n**What it helps to answer:**\n\n1. **Which tokens are smart money accumulating right now?**\n2. **What is the current narrative driving activity in DeFi?**\n3. **Which wallets are connected to a specific address?**\n4. **What is the on-chain story behind a recent price move?**\n\n**SSE event types:**\n\nThe response is a `text/event-stream` with the following JSON event types:\n\n| type | payload | description |\n|---|---|---|\n| `delta` | `{\"type\": \"delta\", \"text\": \"…\"}` | Incremental text chunk of the agent's answer. |\n| `tool_call` | `{\"type\": \"tool_call\", \"name\": \"…\"}` | Emitted once per unique Nansen tool the agent invokes. |\n| `finish` | `{\"type\": \"finish\", \"conversation_id\": \"…\", \"tool_calls\": [...]}` | Final event. Contains the `conversation_id` for follow-up requests and the full list of tools used. |\n| `error` | `{\"type\": \"error\", \"error\": \"…\", \"status_code\": …}` | Emitted if the upstream agent service is unavailable or times out. |\n\nThe stream terminates with a `data: [DONE]` sentinel.\n\n**Fast vs Expert:** Use `/agent/fast` for quick factual lookups and simple questions. Use `/agent/expert` when you need deeper multi-step analysis or synthesis across multiple data sources.","operationId":"agent_expert_api_v1_agent_expert_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResearchRequest"}}},"required":true},"responses":{"200":{"description":"Server-Sent Events stream. Each event is a `data: {json}` line. See endpoint description for event schema.","content":{"application/json":{"schema":{}},"text/event-stream":{}},"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"}}}}}}
```