---
title: "Create a smart alert"
method: POST
path: "/api/v1/smart-alert"
tags: ["Smart Alerts"]
---

# Create a smart alert

`POST /api/v1/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`.

## Request body

- CreateAlertRequest — Request body for creating a smart alert.
  - `name` string, required — Human-readable name for the alert.
  - `type` 'common-token-transfer' | 'sm-token-flows' | 'smart-contract-call', required — The kind of activity to watch.
  - `timeWindow` 'realtime' | '1m' | '5m' | '10m' | '30m' | '1h' | '4h' | '12h' | '1d' | '1w', required — Evaluation window. Use `realtime` to fire per matching event.
  - `channels` union[], required — One or more destinations that receive alert notifications.
    - union
      - TelegramChannel — Deliver alerts to a Telegram chat.
        - `type` 'telegram', required
        - `data` TelegramChannelData, required
          - `chatId` string, required — Telegram chat ID. Prefix with '-' for group chats.
      - SlackChannel — Deliver alerts to a Slack channel via an incoming webhook.
        - `type` 'slack', required
        - `data` SlackChannelData, required
          - `webhookUrl` string, required — Slack incoming webhook URL (https only).
      - DiscordChannel — Deliver alerts to a Discord channel via a webhook.
        - `type` 'discord', required
        - `data` DiscordChannelData, required
          - `webhookUrl` string, required — Discord webhook URL (https only).
      - WebhookChannel — Deliver alerts as an HTTP POST to your own HTTPS endpoint.
        - `type` 'webhook', required
        - `data` WebhookChannelData, required
          - `webhookUrl` string, required — HTTPS endpoint to receive alert payloads.
          - `secret` string — Optional signing secret (16–512 characters). When set, alert payloads include an HMAC-SHA256 signature header.
  - `data` object, required — 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` string — Optional longer description of the alert.
  - `isEnabled` boolean — Whether the alert is active on creation.
  - `createdBy` string — Origin of the alert. Defaults to `agent` when omitted.

## Response `200`

Successful Response

- unknown

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)