Ctrlk
x-twitteryoutube
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Smart Alerts

Configure automated on-chain alerts delivered to Telegram, Slack, or Discord.

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, each delivery includes an X-Nansen-Signature header of the form sha256=<hex>, where <hex> is the HMAC-SHA256 of the raw JSON request body, keyed by your secret (encoded as UTF-8). To verify, recompute the HMAC over the received body and compare using a constant-time check; reject the request if it does not match. Deliveries without a configured secret are unsigned.

Create Alert

Create a smart alert

post

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.

Authorizations
apikeystringRequired

API key for authentication

Body

Request body for creating a smart alert.

namestringRequired

Human-readable name for the alert.

typestring · enumRequired

The kind of activity to watch.

Possible values:
timeWindowstring · enumRequired

Evaluation window. Use realtime to fire per matching event.

Possible values:
descriptionany ofOptional

Optional longer description of the alert.

stringOptional
isEnabledbooleanOptional

Whether the alert is active on creation.

Default: true
createdByany ofOptional

Origin of the alert. Defaults to agent when omitted.

stringOptional
Responses
200

Successful Response

application/json
Responseany
post/api/v1/smart-alert
POST /api/v1/smart-alert HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 331

{
  "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": {}
  }
}
No content

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..." }.

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.

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.

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.

Examples

Each example maps to one alert type — select a tab.

Track large ETH transfers by smart money and notify a Telegram group:

Alert when smart-money net inflow exceeds $500K in 24h:

Alert on Uniswap V3 swap calls and deliver to a signed webhook:

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

patch

Update an existing smart alert. Provide the alert id plus any fields you want to change; omitted fields are left unchanged.

Authorizations
apikeystringRequired

API key for authentication

Body

Request body for updating an existing smart alert.

Only id is required; any other field provided replaces its current value.

idstringRequired

ID of the alert to update.

nameany ofOptional

New name for the alert.

stringOptional
typeany ofOptional

New activity type to watch.

string · enumOptionalPossible values:
timeWindowany ofOptional

New evaluation window.

string · enumOptionalPossible values:
channelsany ofOptional

Replacement set of delivery destinations.

dataany ofOptional

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.

descriptionany ofOptional

New description for the alert.

stringOptional
isEnabledany ofOptional

Enable or disable the alert.

booleanOptional
Responses
200

Successful Response

application/json
Responseany
patch/api/v1/smart-alert
PATCH /api/v1/smart-alert HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 220

{
  "id": "text",
  "name": "text",
  "type": "common-token-transfer",
  "timeWindow": "realtime",
  "channels": [
    {
      "type": "text",
      "data": {
        "chatId": "text"
      }
    }
  ],
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "description": "text",
  "isEnabled": true
}
No content

List Alerts

List smart alerts

get

Return every smart alert belonging to the authenticated user.

Authorizations
apikeystringRequired

API key for authentication

Responses
200

Successful Response

application/json
Responseany
get/api/v1/smart-alert/list
GET /api/v1/smart-alert/list HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Accept: */*

No content

Toggle Alert

Enable or disable a smart alert

patch

Toggle an alert on or off without changing its configuration. Set isEnabled to true to resume notifications or false to pause them.

Authorizations
apikeystringRequired

API key for authentication

Body

Request body for enabling or disabling an existing smart alert.

idstringRequired

ID of the alert to toggle.

isEnabledbooleanRequired

true to enable, false to disable.

Responses
200

Successful Response

application/json
Responseany
patch/api/v1/smart-alert/toggle
PATCH /api/v1/smart-alert/toggle HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "id": "text",
  "isEnabled": true
}
No content

Delete Alert

Delete a smart alert

delete

Permanently delete a smart alert by its ID.

Authorizations
apikeystringRequired

API key for authentication

Path parameters
alert_idstringRequired
Responses
200

Successful Response

application/json
Responseany
delete/api/v1/smart-alert/{alert_id}
DELETE /api/v1/smart-alert/{alert_id} HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Accept: */*

No content
PreviousPoints
NextAPI Changelog

Last updated

Was this helpful?