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 (see GET /api/v2/alerts/active) and is delivered on your notification channels; it will not fire again for cooldownMinutes (default 60).
Pick alertType, then thresholdOperator + thresholdValue: 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.
Common mistakes: naming the token by ticker (send chainId + tokenAddress; a ticker is not accepted); asking for a type above your plan (403 naming the plan to buy, with upgrade_url); asking for a token-page type on a token with no page (400 crown_required). Calling this twice creates two rules — list first.
| Reads or changes | Changes data |
| Sign-in | Yes |
| Scope | api:write |
| Calls | POST /api/v2/alerts/rules (API Explorer) |
Input
JSON Schema, as the server serves it.
{
"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"
},
"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:
{
"name": "create_alert_rule",
"arguments": {
"alertType": "heartbeat_score",
"chainId": "base",
"thresholdOperator": "gt",
"thresholdValue": 1,
"tokenAddress": "value"
}
}