Event schemas

Each event delivery is a POST with a JSON body shaped per event_type. All bodies are wrapped in a stable envelope; the event-specific fields live under payload.

Envelope

{
  "schema_version": 1,
  "event_type":     "tx.policy.alert.triggered",
  "delivery_id":    "11111111-2222-3333-4444-555555555555",
  "attempt":        1,
  "occurred_at":    "2026-05-20T09:14:01.234Z",
  "payload":        { /* event-specific, see below */ }
}

Same envelope mirrored in headers:

Header	Mirror of
`X-Aegis-Event`	`event_type`
`X-Aegis-Delivery-Id`	`delivery_id`
`X-Aegis-Attempt`	`attempt`

delivery_id is stable across retries — use it as your idempotency key.

`tx.policy.alert.triggered`

Fires from the KYT pipeline when /check-transfer (x402) or /v1/aegis/tx (internal) finds at least one alert above your configured alert_min_level (default Medium).

{
  "check_id":     "1c34db13-bb5a-4f1f-91b6-3c93b40c7f99",
  "tx_hash":      "0x52e8e15b…",
  "chain":        "ETH",
  "subgroup_id":  "00000000-…-system-default",
  "worst_level":  "Severe",
  "alerts": [
    {
      "category":       "Mixer",
      "riskLevel":      "Severe",
      "ruleType":       "Origin of funds / Indirect",
      "actualShare":    52.1,
      "thresholdShare": 1,
      "thresholdValue": 100,
      "entityName":     "Sender 0xab…ef01 (exposed to mixer)",
      "entityAddress":  "0xabcdef…",
      "direction":      "incoming",
      "entityScore":    0
    }
  ]
}

Field	Type	Notes
`check_id`	uuid	Correlates to `tx_checks.id`; pass to `/check-transfer-result/{check_id}` for the full body
`tx_hash`	string	32-byte hex with `0x` prefix
`chain`	string	`ETH`, `BSC`, `POLYGON`, `BASE`, `ARBITRUM`, `TRON`
`subgroup_id`	uuid	The subgroup that owns the policy + alert config used
`worst_level`	string	`Low`, `Medium`, `High`, `Severe` — highest level across `alerts[]`
`alerts`	array	Filtered subset above `alert_min_level`. Each alert mirrors the policy-engine shape, see tx-policy-alert detail

Alert fields

Field	Type	Notes
`category`	string	Display name of the BitOK risk category
`riskLevel`	string	`Low`, `Medium`, `High`, `Severe`
`ruleType`	string	One of `Direct exposure`, `Origin of funds / Indirect`, `Pattern`, etc.
`actualShare`	number	% of USD-weighted composite that falls in this category
`thresholdShare`	number	The rule’s trigger threshold (% share)
`thresholdValue`	number	The rule’s trigger threshold (absolute USD)
`entityName`	string \| null	Top-USD sender label; for indirect rules, prefixed `Sender ... (exposed to ...)`. See sender attribution semantics
`entityAddress`	string \| null	Anchor sender address — lowercase EVM, base58 TRON
`direction`	string	Always `incoming` in V1 (we only analyse senders, not receivers)
`entityScore`	number	0 by default; reserved for future per-entity sub-scoring

Synthetic test payload

When fired by POST /v1/webhooks/{id}/test, the body has the same shape with an additional top-level synthetic: true and sentinel ids:

{
  "check_id":     "00000000-0000-0000-0000-000000000000",
  "tx_hash":      "0x0000000000000000000000000000000000000000000000000000000000000000",
  "chain":        "ETH",
  "subgroup_id":  "00000000-0000-0000-0000-000000000000",
  "worst_level":  "Severe",
  "alerts":       [{"category": "Synthetic Test", "riskLevel": "Severe", "ruleType": "Test", "actualShare": 100, "thresholdShare": 0, "direction": "incoming"}],
  "synthetic":    true
}

Receivers MAY short-circuit on synthetic === true to avoid flooding case-review queues with test rows.

`aegis.bfs.completed`

Fires when an async Tier-4 exposure job (POST /explore) completes successfully. Used for batch / pre-screening flows that can’t tie up a synchronous HTTP request.

{
  "job_id":   "9f0a3a07-37bb-4f99-91b5-…",
  "address":  "0xrecipient…",
  "network":  "ETH",
  "report_id": "f8e9d2…",
  "categories": [
    {"slug": "exchange", "severity": 10, "contribution": 84.3},
    {"slug": "mixer",    "severity": 100, "contribution":  3.1}
  ],
  "complete": true
}

Field	Type	Notes
`job_id`	uuid	The `exposure_jobs.id` of the completed job
`address`	string	Anchor address the BFS started from
`network`	string	Same chain set as the rest of the API
`report_id`	uuid	`exposure_reports.id` — fetch via `GET /explore/{job_id}/result` for the full row
`categories`	array	USD-weighted contribution per slug, sorted by severity
`complete`	boolean	`true` if BFS exhausted within budget, `false` if budget-capped

`aegis.bfs.failed`

Same shape minus report_id + categories, plus an error string. Fires after the job exhausts its retry budget.

{
  "job_id":   "9f0a3a07-37bb-…",
  "address":  "0xrecipient…",
  "network":  "ETH",
  "error":    "etherscan rate-limit after 3 retries"
}

`aegis.check.high_risk`

Fires from /v1/aegis/check when the verdict is risk_level: high or severe (Tier 0/1/2/3/4 — any tier can trigger).

{
  "check_id":   "3b2c1d…",
  "address":    "0xrecipient…",
  "network":    "ETH",
  "risk_level": "high",
  "risk_score": 90,
  "tier_hit":   "tier_2",
  "categories": ["mixer", "darknet_market"]
}

Field	Type	Notes
`risk_level`	string	`high` or `severe` (this event won’t fire below `high`)
`risk_score`	number	0..100, inverted from category severity
`tier_hit`	string	The first tier that escalated the verdict
`categories`	array	Slugs of contributing risk categories

Get started

Authentication

x402 Endpoints (USDC pay-per-call)

V2 Public API

Webhooks (push events)

Methodology

Reference

Other

Envelope

`tx.policy.alert.triggered`

Alert fields

Synthetic test payload

`aegis.bfs.completed`

`aegis.bfs.failed`

`aegis.check.high_risk`

​Envelope

​tx.policy.alert.triggered

​Alert fields

​Synthetic test payload

​aegis.bfs.completed

​aegis.bfs.failed

​aegis.check.high_risk

Envelope

`tx.policy.alert.triggered`

Alert fields

Synthetic test payload

`aegis.bfs.completed`

`aegis.bfs.failed`

`aegis.check.high_risk`