Alerts API

Set a rule on a token — a price move, a liquidity drop, holder concentration — and read what it fired. What each alert type means for a reader rather than an integrator is in Alerts & Notifications.

A rule is not a buy alert. A buy alert reports every trade above a floor and is delivered to a Discord channel or Telegram group. A rule watches a metric and fires once when it crosses your threshold, through your own notification channels.

Endpoints

Method	Path	Auth	Description
GET	/api/v2/alerts/rules	Session	Your rules
POST	/api/v2/alerts/rules	Session	Create a rule on one token
PUT	/api/v2/alerts/rules/{id}	Session	Change a rule
DELETE	/api/v2/alerts/rules/{id}	Session	Delete a rule
POST	/api/v2/alerts/rules/{id}/toggle	Session	Turn a rule on or off
GET	/api/v2/alerts/active	Session	Alerts currently firing
GET	/api/v2/alerts/history	Session	Past alerts, paginated
GET	/api/v2/alerts/summary	Session	Counts by status
POST	/api/v2/alerts/{id}/acknowledge	Session	Mark one as seen
POST	/api/v2/alerts/{id}/resolve	Session	Close one
POST	/api/v2/alerts/bulk-acknowledge	Session	Mark many as seen
POST	/api/v2/alerts/bulk-resolve	Session	Close many

Every endpoint acts on your own wallet's rules and alerts. Buy-alert feeds are a different resource: /api/v2/alerts/feeds.

When rules are evaluated

Every 15 minutes. A rule fires once per breach, clears when the metric recovers, and a data gap never clears one — if we cannot read the metric, a firing alert stays firing rather than silently resolving.

Alert types

alertType	Plan	Operators	Notes
heartbeat_score	Free	any	EVM only. Reads your crown's health score. Needs a crown on the token.
holder_count_drop	Pro	any
liquidity_drop	Pro	any
volume_anomaly	Pro	any
price_change	Pro	any
top10_concentration	Pro+	gt, pct_spike	Top ten holders' share of supply. Only evaluated against a recent holder reading, never an estimate.
copycat_detected	Pro+	any	Needs a crown on the token.

The plan requirement is a floor, not a match: Pro+ satisfies a Pro requirement.

Operators are gt, lt, pct_drop and pct_spike. A type that accepts only some of them rejects the rest and names the ones it takes.

Create a rule

curl -X POST https://api.chaindaddy.io/api/v2/alerts/rules \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "eip155:8453",
    "tokenAddress": "0xYourToken",
    "alertType": "price_change",
    "thresholdValue": 20,
    "thresholdOperator": "pct_drop",
    "timeWindowMinutes": 60
  }'

Field	Required	Notes
chainId	Yes	CAIP-2, e.g. eip155:8453
tokenAddress	Yes	The token's contract address
alertType	Yes	From the table above
thresholdValue	Yes	Must be positive
thresholdOperator	Yes	gt, lt, pct_drop, pct_spike
timeWindowMinutes	No	5 or more
cooldownMinutes	No	5 or more. Defaults to 60
enabled	No	Defaults to true

Returns 201 with the created rule.

If it is refused

A rule that could never fire is refused before the plan check, so you are never sold one that does nothing:

Status	Error	Means
400	chain_unsupported	That alert type has no data source on that chain — heartbeat_score on Solana, for instance.
400	crown_required	A crown-bound type on a token with no registered crown.
400	invalid alertType / invalid thresholdOperator	Not in the catalog, or an operator the type refuses.
403	Tier subscription required	Names the plan to buy, with an upgrade_url.
403	Free tier limited to 3 alert rules	Free accounts hold up to 3 rules.
403	Your plan is limited to 50 alert rules	Every paid plan holds up to 50. Delete one to add another — no paid plan raises it.
503	could not check this token's page	The crown lookup failed. Retry shortly.
503	could not check how many rules you have / another rule from this wallet is still being created	Your rule count could not be read, or another create from the same wallet was still in flight. Nothing was created — retry.

Read your rules

curl "https://api.chaindaddy.io/api/v2/alerts/rules?chainId=eip155:8453&tokenAddress=0xYourToken" \
  -H "Authorization: Bearer $JWT"

Pass chainId and tokenAddress together to narrow to one token, or neither for all of them. symbol is not accepted — a symbol can name more than one token, so filtering by it would quietly return every token's rules.

Read what is firing

GET /api/v2/alerts/active takes the same token filter and returns the firing alerts, each with the metric_value that breached and the threshold_value it broke:

{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "…",
        "rule_id": "…",
        "symbol": "TOKEN",
        "alert_type": "liquidity_drop",
        "status": "active",
        "severity": "high",
        "metric_value": 41.2,
        "threshold_value": 50,
        "triggered_at": "2026-09-17T10:00:00Z",
        "notification_sent": true
      }
    ]
  }
}

GET /api/v2/alerts/history is the same shape, paginated: limit defaults to 20 and caps at 100, offset caps at 100000. Both are echoed back with the results.

Acknowledge and resolve

Acknowledging records that you saw an alert; resolving closes it.

curl -X POST https://api.chaindaddy.io/api/v2/alerts/bulk-resolve \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["alert-1", "alert-2"]}'

Related

• Alerts & Notifications — what each alert means and where it lands
• Buy alerts — every trade above a floor, to Discord or Telegram
• Plans — which alert types each plan includes