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, delivered payloads include an HMAC-SHA256 signature header so you can verify they came from Nansen.

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

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.

Examples

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

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

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

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

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

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

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

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

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 24 days ago

Was this helpful?

Alert types

Channels

Create Alert

Create a smart alert

data field reference

Examples

Update Alert

Update a smart alert

List Alerts

List smart alerts

Toggle Alert

Enable or disable a smart alert

Delete Alert

Delete a smart alert

`data` field reference