Rule types

A rule describes what triggers an alert: a kind, a chain, one to twenty watched addresses, a severity and the channels to notify. The API creates three kinds of rules; the other kinds are created from the dashboard and can be read through the API.

Common parameters#

Unknown fields are rejected (422 validation_failed).

large_transfer: large transfer#

A transfer of at least threshold touches a watched address.

{
  "name": "Treasury: large USDT outflows",
  "kind": "large_transfer",
  "chain_id": 56,
  "addresses": ["0x8894e0a0c962cb723c1976a4421c95949be2d4e3"],
  "asset": "0x55d398326f99059ff775485246999027b3197955",
  "threshold": "50000",
  "direction": "outgoing",
  "severity": "critical",
  "channel_ids": ["0193a1b3-7d21-7c55-8e0a-9f1b2c3d4e5f"]
}

new_counterparty: new counterparty#

An outflow goes to an address the watched address has never exchanged with. To avoid false alerts in the first days, the rule only fires after 20 movements have been observed on the address. No specific parameter.

{
  "name": "Hot wallet: unknown recipient",
  "kind": "new_counterparty",
  "chain_id": 56,
  "addresses": ["0x8894e0a0c962cb723c1976a4421c95949be2d4e3"],
  "asset": "any",
  "severity": "warning",
  "channel_ids": ["0193a1b3-7d21-7c55-8e0a-9f1b2c3d4e5f"]
}

burst: burst of outflows#

At least count outflows within window_minutes minutes from a watched address. The alert fires once, when the threshold is crossed.

{
  "name": "Treasury: burst of outflows",
  "kind": "burst",
  "chain_id": 56,
  "addresses": ["0x8894e0a0c962cb723c1976a4421c95949be2d4e3"],
  "count": 5,
  "window_minutes": 10,
  "severity": "critical",
  "channel_ids": ["0193a1b3-7d21-7c55-8e0a-9f1b2c3d4e5f"]
}

Kinds created from the dashboard#

These rules appear in GET /v1/rules with their parameters (params), but cannot be created through the API:

Severity and immediate alert#

The immediate alert goes out as soon as the transaction is included in a block, before confirmations (stage unconfirmed); a second alert follows at confirmation (confirmed), or a cancellation if a reorganization removes the block (cancelled). immediate_alert: true or false forces this behaviour for critical and warning; null (default) applies the severity's default. immediate_alert: true requires a plan that includes immediate alerts (403 plan_feature_unavailable).

Response#

Rules are created active (state: "active"). The response gives the normalised parameters in params: lowercase addresses, asset as an object, amounts in raw units and in hexadecimal.

{
  "id": "0193a1b4-2e7f-7a10-9b3c-4d5e6f708192",
  "name": "Treasury: large USDT outflows",
  "kind": "large_transfer",
  "chain_ids": [56],
  "params": {
    "type": "large_transfer",
    "addresses": ["0x8894e0a0c962cb723c1976a4421c95949be2d4e3"],
    "direction": "outgoing",
    "asset": { "kind": "token", "address": "0x55d398326f99059ff775485246999027b3197955" },
    "threshold": "0xa968163f0a57b400000"
  },
  "severity": "critical",
  "state": "active",
  "immediate_alert": null,
  "channel_ids": ["0193a1b3-7d21-7c55-8e0a-9f1b2c3d4e5f"],
  "pending_change": null,
  "created_at": "2026-11-14T09:14:55.302Z"
}

Pause, resume and delete#

# Pause
curl -X PATCH https://aicscan.io/v1/rules/$RULE_ID \
  -H "Authorization: Bearer $AICSCAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"state":"paused"}'

# Delete
curl -X DELETE https://aicscan.io/v1/rules/$RULE_ID -H "Authorization: Bearer $AICSCAN_API_KEY"

PATCH accepts state (active or paused) and name. Deletion is soft: the rule disappears from the API, its alert history stays in /v1/matches.

Security delay for critical rules#

Pausing or deleting an active critical rule only takes effect one hour after the request. This is a safeguard: a stolen key cannot silently mute your critical alerts. The response is 202 with the rule and its pending change:

{
  "id": "0193a1b4-2e7f-7a10-9b3c-4d5e6f708192",
  "state": "active",
  "pending_change": {
    "id": "0193a1d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "action": "pause",
    "requested_at": "2026-11-14T10:00:00Z",
    "effective_at": "2026-11-14T11:00:00Z"
  }
}

Meanwhile, the rule keeps running; the workspace owners and its active channels are notified, and an owner can cancel or confirm the request from the dashboard. A second request receives 409 change_already_pending. warning and info rules are paused and deleted immediately (200 or 204).

Every pause and deletion made through the API is recorded in the workspace activity log with the key prefix ("aic_k3J9xQ2a (API)").