Types de règles

Une règle décrit ce qui doit déclencher une alerte : un type, une chaîne, une à vingt adresses surveillées, une gravité et les canaux à prévenir. L’API crée trois types de règles ; les autres types se créent depuis le tableau de bord et sont lisibles par l’API.

Paramètres communs#

Les champs inconnus sont refusés (422 validation_failed).

large_transfer : gros transfert#

Un transfert d’au moins threshold touche une adresse surveillée.

{
  "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 : nouvelle contrepartie#

Une sortie part vers une adresse avec laquelle l’adresse surveillée n’a jamais échangé. Pour éviter les fausses alertes des premiers jours, la règle ne se déclenche qu’après 20 mouvements observés sur l’adresse. Aucun paramètre propre.

{
  "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 : rafale de sorties#

Au moins count sorties en window_minutes minutes depuis une adresse surveillée. L’alerte part une fois, quand le seuil est franchi.

{
  "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"]
}

Types créés depuis le tableau de bord#

Ces règles apparaissent dans GET /v1/rules avec leurs paramètres (params), mais ne se créent pas par l’API :

Gravité et alerte immédiate#

L’alerte immédiate part dès que la transaction est incluse dans un bloc, avant les confirmations (étape unconfirmed) ; une seconde alerte suit à la confirmation (confirmed), ou une alerte d’annulation si une réorganisation retire le bloc (cancelled). immediate_alert: true ou false force ce comportement pour critical et warning ; null (par défaut) applique la valeur de la gravité. immediate_alert: true exige une offre qui comprend l’alerte immédiate (403 plan_feature_unavailable).

Réponse#

Les règles sont créées actives (state: "active"). La réponse donne les paramètres normalisés dans params : adresses en minuscules, actif sous forme d’objet, montants en unités brutes et en hexadécimal.

{
  "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, reprise et suppression#

# 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"}'

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

PATCH accepte state (active ou paused) et name. La suppression est logique : la règle disparaît de l’API, son historique d’alertes reste dans /v1/matches.

Délai de sécurité des règles critiques#

Mettre en pause ou supprimer une règle critique active ne prend effet qu’une heure après la demande. C’est une protection : une clé volée ne peut pas faire taire vos alertes critiques en silence. La réponse est 202 avec la règle et son changement en attente :

{
  "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"
  }
}

D’ici là, la règle continue de fonctionner ; les propriétaires de l’espace et ses canaux actifs sont prévenus, et un propriétaire peut annuler ou confirmer la demande depuis le tableau de bord. Une seconde demande reçoit 409 change_already_pending. Les règles warning et info se mettent en pause et se suppriment immédiatement (200 ou 204).

Chaque pause et chaque suppression faite par l’API est inscrite au journal d’activité de l’espace avec le préfixe de la clé (« aic_k3J9xQ2a (API) »).