Skip to content

create_alert_rule ​

Write · Sign-in needed

Create an alert rule on a token

Creates one threshold alert on one token for the signed-in wallet and returns it (201). When the rule's condition is met, an alert fires and is delivered on the wallet's notification channels; it does not fire again for cooldownMinutes (default 60).

alertType picks the metric, and thresholdOperator + thresholdValue the condition: gt/lt compare the metric to the value, pct_drop/pct_spike compare its percentage change (over timeWindowMinutes when set) to the value. Types and the lowest plan that may create them: heartbeat_score (Free; EVM tokens only; needs a token page), copycat_detected (Free; needs a token page), holder_count_drop, liquidity_drop, volume_anomaly, price_change (Pro), top10_concentration (Pro+; operator gt or pct_spike only). Free accounts hold up to 3 rules, paid plans 50, Enterprise unlimited.

The token is named by chainId + tokenAddress; a ticker is not accepted. A type above the caller's plan is 403, naming the plan, with upgrade_url; a token-page type on a token with no page is 400 crown_required. Each call creates a new rule, so the same request twice makes two rules.

Reads or changesChanges data
Sign-inYes
Scopeapi:write
CallsPOST /api/v2/alerts/rules (API Explorer)

Input ​

JSON Schema, as the server serves it.

json
{
  "additionalProperties": false,
  "properties": {
    "alertType": {
      "description": "What the rule watches, and the lowest plan that may create it: `heartbeat_score` (Free, EVM only, needs a\ntoken page), `copycat_detected` (Free, needs a token page), `holder_count_drop`, `liquidity_drop`,\n`volume_anomaly`, `price_change` (Pro), `top10_concentration` (Pro+).\n",
      "enum": [
        "heartbeat_score",
        "copycat_detected",
        "holder_count_drop",
        "liquidity_drop",
        "volume_anomaly",
        "price_change",
        "top10_concentration"
      ],
      "type": "string"
    },
    "chainId": {
      "description": "Chain key (`base`), numeric id or CAIP-2 id (`eip155:8453`)",
      "examples": [
        "base"
      ],
      "type": "string"
    },
    "cooldownMinutes": {
      "default": 60,
      "minimum": 5,
      "type": "integer"
    },
    "enabled": {
      "default": true,
      "type": "boolean"
    },
    "idempotency_key": {
      "description": "Optional. A key chosen for this one change, such as a UUID. Sent again with the same key and the same arguments within 24 hours, it returns the earlier answer instead of making the change again.",
      "maxLength": 255,
      "minLength": 1,
      "type": "string"
    },
    "thresholdOperator": {
      "description": "`gt` / `lt`: the metric is above / below `thresholdValue`. `pct_drop` / `pct_spike`: the metric fell / rose by\nat least `thresholdValue` percent. `top10_concentration` accepts only `gt` and `pct_spike`.\n",
      "enum": [
        "gt",
        "lt",
        "pct_drop",
        "pct_spike"
      ],
      "type": "string"
    },
    "thresholdValue": {
      "description": "Must be greater than 0. A percentage for `pct_drop`/`pct_spike`.",
      "exclusiveMinimum": 0,
      "type": "number"
    },
    "timeWindowMinutes": {
      "minimum": 5,
      "type": "integer"
    },
    "tokenAddress": {
      "description": "0x token address on EVM; the mint address on Solana (case-sensitive)",
      "type": "string"
    }
  },
  "required": [
    "alertType",
    "chainId",
    "thresholdOperator",
    "thresholdValue",
    "tokenAddress"
  ],
  "type": "object"
}

Example ​

A tools/call request:

json
{
  "name": "create_alert_rule",
  "arguments": {
    "alertType": "heartbeat_score",
    "chainId": "base",
    "thresholdOperator": "gt",
    "thresholdValue": 1,
    "tokenAddress": "value"
  }
}

All MCP tools · Connect an AI app