API — Alerts

Alert rules define the conditions that trigger notifications. Alert events are the individual matches that occur when a rule fires.

List rules

bash

GET /api/alerts/rules

curl https://api.opsion.xyz/api/alerts/rules \
  -H "Authorization: Bearer opsk_your_key_here"

Create a rule

bash

POST /api/alerts/rules

curl -X POST https://api.opsion.xyz/api/alerts/rules \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Large outbound transfer",
    "ruleType": "large_transfer",
    "severity": "critical",
    "walletIds": ["550e8400-e29b-41d4-a716-446655440000"],
    "conditions": {
      "direction": "outbound",
      "value_usd": { "gte": 50000 }
    },
    "notifyEmail": true,
    "cooldownMinutes": 5
  }'

Field	Type	Required	Description
`name`	`string`	Yes	Rule name (max 64 chars)
`ruleType`	`string`	Yes	See rule types below
`severity`	`string`	No	info \| warning \| critical (default: warning)
`walletIds`	`uuid[]`	No	Target wallets (omit for all wallets)
`conditions`	`object`	No	Rule-type-specific condition parameters
`notifyEmail`	`boolean`	No	Send email alert (default: true)
`notifySlack`	`boolean`	No	Send Slack alert (default: false)
`notifyWebhook`	`boolean`	No	Trigger custom webhook (default: false)
`customWebhookUrl`	`string`	No	Public HTTPS URL for webhook delivery
`cooldownMinutes`	`number`	No	Suppress repeat alerts, 0–1440 min (default: 5)

Rule types

Type	Description
`any_transfer`	Fires on any transfer involving the wallet
`large_transfer`	Fires when transfer value exceeds a USD threshold
`token_transfer`	Fires on transfers of a specific token
`inbound_only`	Fires only on incoming transfers
`outbound_only`	Fires only on outgoing transfers
`contract_call`	Fires on any contract interaction
`method_call`	Fires when a specific method signature is called
`address_blacklist`	Fires when a transaction involves a flagged address
`gas_spike`	Fires when gas price exceeds a threshold
`frequency`	Fires when transaction frequency exceeds a threshold

Update / toggle a rule

bash

PATCH /api/alerts/rules/:id

# Disable a rule
curl -X PATCH https://api.opsion.xyz/api/alerts/rules/rule-id-here \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

# Delete a rule
curl -X DELETE https://api.opsion.xyz/api/alerts/rules/rule-id-here \
  -H "Authorization: Bearer opsk_your_key_here"

Alert events

Events are immutable records created each time a rule fires.

bash

GET /api/alerts/events

# Filter by status: open | acknowledged | resolved
curl "https://api.opsion.xyz/api/alerts/events?status=open" \
  -H "Authorization: Bearer opsk_your_key_here"

Acknowledge / resolve

bash

# Acknowledge a single event
curl -X PATCH https://api.opsion.xyz/api/alerts/events/:id/acknowledge \
  -H "Authorization: Bearer opsk_your_key_here"

# Resolve a single event with a note
curl -X PATCH https://api.opsion.xyz/api/alerts/events/:id/resolve \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Confirmed legitimate transaction" }'

# Bulk acknowledge (up to 100 events)
curl -X PATCH https://api.opsion.xyz/api/alerts/events/bulk-acknowledge \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["event-id-1", "event-id-2"] }'

# Bulk resolve
curl -X PATCH https://api.opsion.xyz/api/alerts/events/bulk-resolve \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["event-id-1", "event-id-2"], "note": "Reviewed by compliance team" }'