> For the complete documentation index, see [llms.txt](https://docs.nansen.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nansen.ai/api/smart-alerts.md). # Smart Alerts Smart Alerts notify you when on-chain conditions are met — for example, when smart money netflow on a token exceeds a threshold. Alerts are delivered via Telegram, Slack, Discord, or a custom webhook. Each alert has four parts: a `type` that determines what it watches, a `timeWindow` that controls how often it is evaluated, one or more delivery `channels`, and a type-specific `data` object that holds the filters. ## Alert types Choose one `type` per alert. The fields accepted inside `data` depend on it. | `type` | What it watches | Key `data` fields | | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `common-token-transfer` | Token transfers (buy / sell / swap / send / receive) matching subjects and value thresholds | `subjects`, `events`, `usdValue`, `tokenAmount`, `counterparties` | | `sm-token-flows` | Smart-money net inflow / outflow crossing a threshold over the time window | `inflow_*`, `outflow_*`, `netflow_*` | | `smart-contract-call` | Calls to a contract, optionally filtered by method signature and caller | `signatureHash`, `inclusion.caller`, `inclusion.smartContract` | ## Channels Every alert needs at least one channel. The `type` selects which `data` shape is required. | `type` | Delivery | Required `data` | | ---------- | ------------------------------------ | ----------------------------------------------------------- | | `telegram` | Message to a Telegram chat | `chatId` (prefix with `-` for groups) | | `slack` | Message via a Slack incoming webhook | `webhookUrl` (https only) | | `discord` | Message via a Discord webhook | `webhookUrl` (https only) | | `webhook` | HTTP POST to your own endpoint | `webhookUrl` (https only); optional `secret` (16–512 chars) | When a webhook `secret` is set, delivered payloads include an HMAC-SHA256 signature header so you can verify they came from Nansen. ## Create Alert ## Create a smart alert > Create a smart alert that watches on-chain activity and notifies the configured channels. Choose a \`type\` (common-token-transfer, sm-token-flows, or smart-contract-call), an evaluation \`timeWindow\`, one or more delivery \`channels\`, and the type-specific \`data\` filters. If \`createdBy\` is omitted it defaults to \`agent\`. ```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":{"CreateAlertRequest":{"properties":{"name":{"type":"string","title":"Name","description":"Human-readable name for the alert."},"type":{"type":"string","enum":["common-token-transfer","sm-token-flows","smart-contract-call"],"title":"Type","description":"The kind of activity to watch."},"timeWindow":{"type":"string","enum":["realtime","1m","5m","10m","30m","1h","4h","12h","1d","1w"],"title":"Timewindow","description":"Evaluation window. Use `realtime` to fire per matching event."},"channels":{"items":{"oneOf":[{"$ref":"#/components/schemas/TelegramChannel"},{"$ref":"#/components/schemas/SlackChannel"},{"$ref":"#/components/schemas/DiscordChannel"},{"$ref":"#/components/schemas/WebhookChannel"}],"discriminator":{"propertyName":"type","mapping":{"discord":"#/components/schemas/DiscordChannel","slack":"#/components/schemas/SlackChannel","telegram":"#/components/schemas/TelegramChannel","webhook":"#/components/schemas/WebhookChannel"}}},"type":"array","title":"Channels","description":"One or more destinations that receive alert notifications."},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Type-specific filter configuration. The accepted fields depend on `type` (see the API reference and the worked examples on this endpoint). Common keys include `chains`, `events`, `inclusion` and `exclusion`."},"description":{"anyOf":[{"type":"string"}],"title":"Description","description":"Optional longer description of the alert."},"isEnabled":{"type":"boolean","title":"Isenabled","description":"Whether the alert is active on creation.","default":true},"createdBy":{"anyOf":[{"type":"string"}],"title":"Createdby","description":"Origin of the alert. Defaults to `agent` when omitted."}},"type":"object","required":["name","type","timeWindow","channels","data"],"title":"CreateAlertRequest","description":"Request body for creating a smart alert."},"TelegramChannel":{"properties":{"type":{"type":"string","const":"telegram","title":"Type"},"data":{"$ref":"#/components/schemas/TelegramChannelData"}},"type":"object","required":["type","data"],"title":"TelegramChannel","description":"Deliver alerts to a Telegram chat."},"TelegramChannelData":{"properties":{"chatId":{"type":"string","title":"Chatid","description":"Telegram chat ID. Prefix with '-' for group chats."}},"type":"object","required":["chatId"],"title":"TelegramChannelData"},"SlackChannel":{"properties":{"type":{"type":"string","const":"slack","title":"Type"},"data":{"$ref":"#/components/schemas/SlackChannelData"}},"type":"object","required":["type","data"],"title":"SlackChannel","description":"Deliver alerts to a Slack channel via an incoming webhook."},"SlackChannelData":{"properties":{"webhookUrl":{"type":"string","title":"Webhookurl","description":"Slack incoming webhook URL (https only)."}},"type":"object","required":["webhookUrl"],"title":"SlackChannelData"},"DiscordChannel":{"properties":{"type":{"type":"string","const":"discord","title":"Type"},"data":{"$ref":"#/components/schemas/DiscordChannelData"}},"type":"object","required":["type","data"],"title":"DiscordChannel","description":"Deliver alerts to a Discord channel via a webhook."},"DiscordChannelData":{"properties":{"webhookUrl":{"type":"string","title":"Webhookurl","description":"Discord webhook URL (https only)."}},"type":"object","required":["webhookUrl"],"title":"DiscordChannelData"},"WebhookChannel":{"properties":{"type":{"type":"string","const":"webhook","title":"Type"},"data":{"$ref":"#/components/schemas/WebhookChannelData"}},"type":"object","required":["type","data"],"title":"WebhookChannel","description":"Deliver alerts as an HTTP POST to your own HTTPS endpoint."},"WebhookChannelData":{"properties":{"webhookUrl":{"type":"string","title":"Webhookurl","description":"HTTPS endpoint to receive alert payloads."},"secret":{"anyOf":[{"type":"string"}],"title":"Secret","description":"Optional signing secret (16–512 characters). When set, alert payloads include an HMAC-SHA256 signature header."}},"type":"object","required":["webhookUrl"],"title":"WebhookChannelData"}},"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"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","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"}}}}}},"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/smart-alert":{"post":{"tags":["Smart Alerts"],"summary":"Create a smart alert","description":"Create a smart alert that watches on-chain activity and notifies the configured channels. Choose a `type` (common-token-transfer, sm-token-flows, or smart-contract-call), an evaluation `timeWindow`, one or more delivery `channels`, and the type-specific `data` filters. If `createdBy` is omitted it defaults to `agent`.","operationId":"smart_alert_create_api_v1_smart_alert_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAlertRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"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"},"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"}}}}}} ``` ### `data` field reference The `data` object depends on the alert `type` — select a tab below. Shared helper shapes: * **MinMax** — `{ "min": number, "max": number }`; either bound is optional. * **Target** — `{ "type": "address" | "entity" | "label" | "custom-label" | "watchlist", "value": "..." }`. * **Token** — `{ "chain": "ethereum", "address": "0x..." }`. {% tabs %} {% tab title="common-token-transfer" %} | Field | Type | Description | | ---------------- | ------------------------------------------------------ | ------------------------------------------- | | `chains` | `string[]` | Chains to monitor, e.g. `["ethereum"]`. | | `subjects` | `Target[]` | Who must be involved in the transfer. | | `events` | `("buy" \| "sell" \| "swap" \| "send" \| "receive")[]` | Transfer directions to match. | | `counterparties` | `Target[]` | Optional counterparties on the other side. | | `usdValue` | `MinMax` | Transfer USD value bounds. | | `tokenAmount` | `MinMax` | Token amount bounds. | | `inclusion` | `{ tokens?, tokenSectors?, tokenAge?, marketCap? }` | Only match these tokens / sectors / ranges. | | `exclusion` | `{ tokens?, tokenSectors?, tokenAge?, marketCap? }` | Exclude these tokens / sectors / ranges. | | {% endtab %} | | | {% tab title="sm-token-flows" %} | Field | Type | Description | | -------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | | `chains` | `string[]` | Chains to monitor. | | `events` | `["sm-token-flows"]` | Fixed event tag for this alert type. | | `inflow_15m` / `inflow_30m` / `inflow_1h` / `inflow_1d` / `inflow_7d` | `MinMax` | Smart-money inflow bounds over the window. | | `outflow_15m` / `outflow_30m` / `outflow_1h` / `outflow_1d` / `outflow_7d` | `MinMax` | Smart-money outflow bounds over the window. | | `netflow_15m` / `netflow_30m` / `netflow_1h` / `netflow_1d` / `netflow_7d` | `MinMax` | Net (inflow − outflow) bounds over the window. | | `inclusion` | `{ tokens?, tokenSectors?, tokenAge?, marketCap?, fdvUsd? }` | Only match these. | | `exclusion` | `{ tokens?, tokenSectors? }` | Exclude these. | | {% endtab %} | | | {% tab title="smart-contract-call" %} | Field | Type | Description | | --------------- | ----------------------------------------------- | -------------------------------------------------------- | | `chains` | `string[]` | Chains to monitor. | | `events` | `["smart-contract-call"]` | Fixed event tag for this alert type. | | `usdValue` | `MinMax` | Optional USD value bounds for the call. | | `signatureHash` | `string[]` | Optional 4-byte method selectors, e.g. `["0x128acb08"]`. | | `inclusion` | `{ caller: Target[], smartContract: Target[] }` | Only match these callers / contracts. | | `exclusion` | `{ caller: Target[], smartContract: Target[] }` | Exclude these callers / contracts. | | {% endtab %} | | | | {% endtabs %} | | | ### Examples Each example maps to one alert `type` — select a tab. {% tabs %} {% tab title="common-token-transfer" %} Track large ETH transfers by smart money and notify a Telegram group: ```bash curl -X POST https://api.nansen.ai/api/v1/smart-alert \ -H "apiKey: $NANSEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Large ETH Smart Money Transfer", "type": "common-token-transfer", "timeWindow": "realtime", "channels": [{"type": "telegram", "data": {"chatId": "-1001234567890"}}], "data": { "chains": ["ethereum"], "subjects": [{"type": "label", "value": "smart_money"}], "events": ["send", "receive"], "usdValue": {"min": 100000}, "inclusion": {}, "exclusion": {} } }' ``` {% endtab %} {% tab title="sm-token-flows" %} Alert when smart-money net inflow exceeds $500K in 24h: ```bash curl -X POST https://api.nansen.ai/api/v1/smart-alert \ -H "apiKey: $NANSEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "ETH Smart Money Netflow > $500K", "type": "sm-token-flows", "timeWindow": "1d", "channels": [{"type": "telegram", "data": {"chatId": "-1001234567890"}}], "data": { "chains": ["ethereum"], "events": ["sm-token-flows"], "netflow_1d": {"min": 500000}, "inclusion": {}, "exclusion": {} } }' ``` {% endtab %} {% tab title="smart-contract-call" %} Alert on Uniswap V3 swap calls and deliver to a signed webhook: ```bash curl -X POST https://api.nansen.ai/api/v1/smart-alert \ -H "apiKey: $NANSEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Uniswap V3 Swap Monitor", "type": "smart-contract-call", "timeWindow": "realtime", "channels": [{ "type": "webhook", "data": {"webhookUrl": "https://your-server.com/alerts", "secret": "your-signing-secret"} }], "data": { "chains": ["ethereum"], "events": ["smart-contract-call"], "signatureHash": ["0x128acb08"], "inclusion": {"smartContract": [{"type": "label", "value": "uniswap_v3"}]}, "exclusion": {} } }' ``` {% endtab %} {% endtabs %} To update an alert later, send only the fields you want to change along with the alert `id` (see below). ## Update Alert ## Update a smart alert > Update an existing smart alert. Provide the alert \`id\` plus any fields you want to change; omitted fields are left unchanged. ```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":{"UpdateAlertRequest":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the alert to update."},"name":{"anyOf":[{"type":"string"}],"title":"Name","description":"New name for the alert."},"type":{"anyOf":[{"type":"string","enum":["common-token-transfer","sm-token-flows","smart-contract-call"]}],"title":"Type","description":"New activity type to watch."},"timeWindow":{"anyOf":[{"type":"string","enum":["realtime","1m","5m","10m","30m","1h","4h","12h","1d","1w"]}],"title":"Timewindow","description":"New evaluation window."},"channels":{"anyOf":[{"items":{"oneOf":[{"$ref":"#/components/schemas/TelegramChannel"},{"$ref":"#/components/schemas/SlackChannel"},{"$ref":"#/components/schemas/DiscordChannel"},{"$ref":"#/components/schemas/WebhookChannel"}],"discriminator":{"propertyName":"type","mapping":{"discord":"#/components/schemas/DiscordChannel","slack":"#/components/schemas/SlackChannel","telegram":"#/components/schemas/TelegramChannel","webhook":"#/components/schemas/WebhookChannel"}}},"type":"array"}],"title":"Channels","description":"Replacement set of delivery destinations."},"data":{"anyOf":[{"additionalProperties":true,"type":"object"}],"title":"Data","description":"Type-specific filter configuration. The accepted fields depend on `type` (see the API reference and the worked examples on this endpoint). Common keys include `chains`, `events`, `inclusion` and `exclusion`."},"description":{"anyOf":[{"type":"string"}],"title":"Description","description":"New description for the alert."},"isEnabled":{"anyOf":[{"type":"boolean"}],"title":"Isenabled","description":"Enable or disable the alert."}},"type":"object","required":["id"],"title":"UpdateAlertRequest","description":"Request body for updating an existing smart alert.\n\nOnly `id` is required; any other field provided replaces its current value."},"TelegramChannel":{"properties":{"type":{"type":"string","const":"telegram","title":"Type"},"data":{"$ref":"#/components/schemas/TelegramChannelData"}},"type":"object","required":["type","data"],"title":"TelegramChannel","description":"Deliver alerts to a Telegram chat."},"TelegramChannelData":{"properties":{"chatId":{"type":"string","title":"Chatid","description":"Telegram chat ID. Prefix with '-' for group chats."}},"type":"object","required":["chatId"],"title":"TelegramChannelData"},"SlackChannel":{"properties":{"type":{"type":"string","const":"slack","title":"Type"},"data":{"$ref":"#/components/schemas/SlackChannelData"}},"type":"object","required":["type","data"],"title":"SlackChannel","description":"Deliver alerts to a Slack channel via an incoming webhook."},"SlackChannelData":{"properties":{"webhookUrl":{"type":"string","title":"Webhookurl","description":"Slack incoming webhook URL (https only)."}},"type":"object","required":["webhookUrl"],"title":"SlackChannelData"},"DiscordChannel":{"properties":{"type":{"type":"string","const":"discord","title":"Type"},"data":{"$ref":"#/components/schemas/DiscordChannelData"}},"type":"object","required":["type","data"],"title":"DiscordChannel","description":"Deliver alerts to a Discord channel via a webhook."},"DiscordChannelData":{"properties":{"webhookUrl":{"type":"string","title":"Webhookurl","description":"Discord webhook URL (https only)."}},"type":"object","required":["webhookUrl"],"title":"DiscordChannelData"},"WebhookChannel":{"properties":{"type":{"type":"string","const":"webhook","title":"Type"},"data":{"$ref":"#/components/schemas/WebhookChannelData"}},"type":"object","required":["type","data"],"title":"WebhookChannel","description":"Deliver alerts as an HTTP POST to your own HTTPS endpoint."},"WebhookChannelData":{"properties":{"webhookUrl":{"type":"string","title":"Webhookurl","description":"HTTPS endpoint to receive alert payloads."},"secret":{"anyOf":[{"type":"string"}],"title":"Secret","description":"Optional signing secret (16–512 characters). When set, alert payloads include an HMAC-SHA256 signature header."}},"type":"object","required":["webhookUrl"],"title":"WebhookChannelData"}},"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"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","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"}}}}}},"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/smart-alert":{"patch":{"tags":["Smart Alerts"],"summary":"Update a smart alert","description":"Update an existing smart alert. Provide the alert `id` plus any fields you want to change; omitted fields are left unchanged.","operationId":"smart_alert_update_api_v1_smart_alert_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAlertRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"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"},"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"}}}}}} ``` ## List Alerts ## List smart alerts > Return every smart alert belonging to the authenticated user. ```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"}},"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"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","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"}}}}}},"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/smart-alert/list":{"get":{"tags":["Smart Alerts"],"summary":"List smart alerts","description":"Return every smart alert belonging to the authenticated user.","operationId":"smart_alert_list_api_v1_smart_alert_list_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"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"},"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"}}}}}} ``` ## Toggle Alert ## Enable or disable a smart alert > Toggle an alert on or off without changing its configuration. Set \`isEnabled\` to \`true\` to resume notifications or \`false\` to pause them. ```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":{"ToggleAlertRequest":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the alert to toggle."},"isEnabled":{"type":"boolean","title":"Isenabled","description":"`true` to enable, `false` to disable."}},"type":"object","required":["id","isEnabled"],"title":"ToggleAlertRequest","description":"Request body for enabling or disabling an existing smart alert."}},"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"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","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"}}}}}},"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/smart-alert/toggle":{"patch":{"tags":["Smart Alerts"],"summary":"Enable or disable a smart alert","description":"Toggle an alert on or off without changing its configuration. Set `isEnabled` to `true` to resume notifications or `false` to pause them.","operationId":"smart_alert_toggle_api_v1_smart_alert_toggle_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleAlertRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"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"},"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"}}}}}} ``` ## Delete Alert ## Delete a smart alert > Permanently delete a smart alert by its ID. ```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"}},"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"}},"PaymentReceipt":{"description":"Base64url-encoded MPP receipt returned on successful paid requests via Authorization: Payment","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"}}}}}},"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/smart-alert/{alert_id}":{"delete":{"tags":["Smart Alerts"],"summary":"Delete a smart alert","description":"Permanently delete a smart alert by its ID.","operationId":"smart_alert_delete_api_v1_smart_alert__alert_id__delete","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"string","title":"Alert Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"Payment-Receipt":{"$ref":"#/components/headers/PaymentReceipt"},"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":{"$ref":"#/components/responses/BadRequestError","description":"Bad Request"},"401":{"$ref":"#/components/responses/UnauthorizedError","description":"Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenError","description":"Forbidden"},"404":{"$ref":"#/components/responses/NotFoundError","description":"Not Found"},"422":{"$ref":"#/components/responses/ValidationError","description":"Unprocessable Content"},"429":{"$ref":"#/components/responses/TooManyRequestsError","description":"Too Many Requests"},"500":{"$ref":"#/components/responses/InternalServerError","description":"Internal Server Error"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nansen.ai/api/smart-alerts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.