> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alterscope.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Event catalog
> Every Alterscope risk-event type, when it fires, and a representative payload.
This is the canonical list of event types Alterscope emits. The same types flow through every delivery channel — [Webhooks](/develop/realtime/webhooks), [WebSockets](/develop/realtime/websockets), and the [replay feed](/develop/realtime/webhooks#replay-missed-events) — so a `peg.depeg.start` you subscribe to over a webhook is the same event you'd see on the `risk-events` WebSocket stream.
Subscribe by exact type string. There is no wildcard matching; list each type you care about.
## Envelope
Every event shares one envelope. The `type` identifies the event, `data` carries the type-specific payload, and `meta._agentic` carries the same freshness/quality signal as REST responses (see [Response envelope](/develop/concepts/response-envelope)).
```json theme={null}
{
"event_id": "01J9Z0K3M4N5P6Q7R8S9T0V1W2",
"type": "peg.depeg.start",
"severity": "high",
"chain": "ethereum",
"protocol": "morpho",
"subject_id": "peg:ethereum:USDC",
"ts": "2026-04-27T08:32:11Z",
"data": { },
"meta": { "_agentic": { "freshness": { "status": "fresh" } } }
}
```
`severity` is one of `info`, `warn`, `high`, `critical`. `subject_id` follows a `:` shape (e.g. `oracle:ethereum:0xfeed:USDC`, `vault:base:0xpool`). When an event was computed off degraded upstream input, the envelope additionally carries `data_quality: "degraded"`. Fields shown as `omitempty` (`chain`, `protocol`, `severity`) may be absent.
The samples below show the `data` object for each type. Fields within `data` vary by event family and may evolve additively — treat unrecognized fields as forward-compatible and key your idempotency on a stable identifier (e.g. block number + subject).
## Oracle
Fires when an oracle feed backing a tracked market has not updated within its freshness threshold. Severity scales with staleness age (`warn` \< 10 min, `high` ≥ 10 min, `critical` ≥ 60 min).
```json theme={null}
{
"type": "oracle.stale",
"severity": "high",
"subject_id": "oracle:ethereum:0xfeed...:0xmarket...",
"data": {
"chain": "ethereum",
"oracle_address": "0xfeed...",
"market_id": "0xmarket...",
"stale_age_s": 742
}
}
```
Fires when the meta-oracle's classification of a feed changes — its category, provider, staleness status, risk level, or edge-case flags shift from the previously observed fingerprint.
```json theme={null}
{
"type": "oracle.classification.changed",
"severity": "warn",
"subject_id": "oracle:ethereum:0xfeed...:0xmarket...",
"data": {
"chain": "ethereum",
"oracle_address": "0xfeed...",
"market_id": "0xmarket...",
"previous": {
"category": "market_price",
"provider": "chainlink",
"staleness_status": "fresh",
"risk_level": "low",
"edge_case_flags": ""
},
"current": {
"category": "market_price",
"provider": "chainlink",
"staleness_status": "stale",
"risk_level": "elevated",
"edge_case_flags": "stale_round"
}
}
}
```
Fires when a feed returns a structurally invalid reading (e.g. a non-positive or otherwise unusable answer) rather than merely a stale one. Carries the oracle and market identifiers; data fields are feed-specific.
```json theme={null}
{
"type": "oracle.feed.invalid",
"severity": "high",
"subject_id": "oracle:ethereum:0xfeed...:0xmarket...",
"data": {
"chain": "ethereum",
"oracle_address": "0xfeed...",
"market_id": "0xmarket..."
}
}
```
## Peg
Fires when a tracked asset's observed price crosses its depeg threshold against the reference. Prices are decimal strings (never floats); `deviation_bps` is signed (negative = below reference).
```json theme={null}
{
"type": "peg.depeg.start",
"severity": "high",
"subject_id": "peg:ethereum:USDC",
"data": {
"asset_symbol": "USDC",
"chain": "ethereum",
"oracle_address": "0xfeed...",
"peg_kind": "hard_redemption",
"observed_feed": "0xaggregator...",
"deviation_bps": -87,
"reference_price": "100000000",
"observed_price": "99130000",
"block_number": 22341123,
"block_timestamp": 1745742731
}
}
```
Fires when an asset that had depegged returns inside its threshold band. Same payload shape as `peg.depeg.start`; severity is `info`.
```json theme={null}
{
"type": "peg.depeg.end",
"severity": "info",
"subject_id": "peg:ethereum:USDC",
"data": {
"asset_symbol": "USDC",
"chain": "ethereum",
"oracle_address": "0xfeed...",
"peg_kind": "hard_redemption",
"observed_feed": "0xaggregator...",
"deviation_bps": -4,
"reference_price": "100000000",
"observed_price": "99960000",
"block_number": 22341990,
"block_timestamp": 1745753140
}
}
```
A recovery signal in the peg family, distinct from `peg.depeg.end`; severity is `info`. Carries the peg identity in `subject_id`; the `data` object mirrors the peg envelope above.
```json theme={null}
{
"type": "peg.depeg.recovered",
"severity": "info",
"subject_id": "peg:ethereum:USDC",
"data": {
"asset_symbol": "USDC",
"chain": "ethereum"
}
}
```
## Vault
Vault events are derived from indexed on-chain curator/governance actions on MetaMorpho-style vaults. They share a common payload shape: the vault, the caller, the affected subject, the underlying on-chain event, and the transaction coordinates.
Fires when a vault's supply cap is changed on chain (`set_cap`). Severity is `info`.
```json theme={null}
{
"type": "vault.cap.changed",
"severity": "info",
"subject_id": "vault:ethereum:0xvault...",
"data": {
"vault_address": "0xvault...",
"caller_address": "0xcurator...",
"subject_address": "0xmarket...",
"on_chain_event": "set_cap",
"block_number": 22341500,
"tx_hash": "0xabc...",
"log_index": 12,
"timestamp": 1745749000,
"params": { }
}
}
```
Fires when a vault's performance fee is changed on chain (`set_fee`). Severity is `warn`. Same payload shape as `vault.cap.changed` with `on_chain_event: "set_fee"`.
```json theme={null}
{
"type": "vault.fee.changed",
"severity": "warn",
"subject_id": "vault:ethereum:0xvault...",
"data": {
"vault_address": "0xvault...",
"caller_address": "0xcurator...",
"subject_address": "0xcurator...",
"on_chain_event": "set_fee",
"block_number": 22341510,
"tx_hash": "0xdef...",
"log_index": 3,
"timestamp": 1745749120,
"params": { }
}
}
```
Fires when a vault's curator role is reassigned on chain (`set_curator`). Severity is `high` — a curator change is a governance-level event. Same payload shape with `on_chain_event: "set_curator"`.
```json theme={null}
{
"type": "vault.curator.changed",
"severity": "high",
"subject_id": "vault:ethereum:0xvault...",
"data": {
"vault_address": "0xvault...",
"caller_address": "0xowner...",
"subject_address": "0xnewcurator...",
"on_chain_event": "set_curator",
"block_number": 22341600,
"tx_hash": "0x111...",
"log_index": 0,
"timestamp": 1745750000,
"params": { }
}
}
```
Fires when a curator reallocates supply across markets (`reallocate_supply` / `reallocate_withdraw`). Severity is `warn`. Same payload shape with the corresponding `on_chain_event`.
```json theme={null}
{
"type": "vault.allocation.changed",
"severity": "warn",
"subject_id": "vault:ethereum:0xvault...",
"data": {
"vault_address": "0xvault...",
"caller_address": "0xallocator...",
"subject_address": "0xmarket...",
"on_chain_event": "reallocate_supply",
"block_number": 22341700,
"tx_hash": "0x222...",
"log_index": 7,
"timestamp": 1745751000,
"params": { }
}
}
```
## Curator
Fires for curator/governance actions that don't map to a more specific vault event — e.g. supply-queue updates, allocator/guardian/timelock changes, or lost-asset updates. Severity is `info`. The specific action is in `on_chain_event`.
```json theme={null}
{
"type": "curator.action",
"severity": "info",
"subject_id": "vault:ethereum:0xvault...",
"data": {
"vault_address": "0xvault...",
"caller_address": "0xcurator...",
"subject_address": "0xguardian...",
"on_chain_event": "set_guardian",
"block_number": 22341800,
"tx_hash": "0x333...",
"log_index": 1,
"timestamp": 1745752000,
"params": { }
}
}
```
Marks the start of a curator's tenure over a vault. Severity is `info`. Carries the vault/curator identity in `subject_id`; `data` is tenure-specific.
```json theme={null}
{
"type": "curator.tenure.start",
"severity": "info",
"subject_id": "vault:ethereum:0xvault...",
"data": {
"vault_address": "0xvault...",
"curator_address": "0xcurator..."
}
}
```
Marks the end of a curator's tenure over a vault. Severity is `info`. Same shape as `curator.tenure.start`.
```json theme={null}
{
"type": "curator.tenure.end",
"severity": "info",
"subject_id": "vault:ethereum:0xvault...",
"data": {
"vault_address": "0xvault...",
"curator_address": "0xcurator..."
}
}
```
## Liquidity
Fires when a market's utilization crosses a configured threshold. Severity is `high`.
```json theme={null}
{
"type": "liquidity.utilization.spike",
"severity": "high",
"subject_id": "liquidity:ethereum:0xmarket...",
"data": {
"chain": "ethereum",
"market_id": "0xmarket...",
"utilization": 0.97,
"threshold": 0.95,
"detected_at": "2026-04-27T08:32:11Z"
}
}
```
Fires when available exit depth for a position collapses sharply. Severity is `critical` — the most actionable liquidity signal. Carries the affected market in `subject_id`; `data` fields are market-specific.
```json theme={null}
{
"type": "liquidity.depth.collapse",
"severity": "critical",
"subject_id": "liquidity:ethereum:0xmarket...",
"data": {
"chain": "ethereum",
"market_id": "0xmarket..."
}
}
```
## Risk
Fires when the graph anomaly detector flags a non-MEV anomaly (TVL drop/spike, concentration, flow anomaly, whale movement). Severity derives from the detector's own grade.
```json theme={null}
{
"type": "risk.anomaly",
"severity": "high",
"subject_id": "vault:ethereum:0xpool...",
"data": {
"anomaly_id": "anom_01J9Z...",
"anomaly_type": "tvl_drop",
"severity": "high",
"pool_id": "0xpool...",
"chain": "ethereum",
"protocol": "morpho",
"wallet_id": "",
"entity_id": "",
"description": "TVL fell 38% in 3 blocks",
"score": 0.81,
"metric_value": 6200000,
"baseline_value": 10000000,
"deviation_pct": -38.0,
"detected_at": "2026-04-27T08:32:11Z"
}
}
```
Fires when a yield opportunity's risk-factor category score drops past a threshold between snapshots. Severity is supplied by the breach (defaults to `warn`).
```json theme={null}
{
"type": "risk.factor.breach",
"severity": "warn",
"subject_id": "risk:opp_abc123:liquidity",
"data": {
"opportunity_id": "opp_abc123",
"category": "liquidity",
"old_score": 72.0,
"new_score": 41.0,
"delta": -31.0,
"threshold": 50.0,
"chain": "ethereum",
"protocol": "morpho",
"detected_at": "2026-04-27T08:00:00Z"
}
}
```
## Regime
Fires when the market-regime detector transitions to a new regime. Emitted against the `vault:global` subject. Severity is `warn`.
```json theme={null}
{
"type": "regime.shift",
"severity": "warn",
"subject_id": "vault:global",
"data": {
"regime_id": "regime_01J9Z...",
"regime_type": "risk_off",
"confidence": 0.74,
"started_at": "2026-04-27T07:55:00Z",
"signals": ["vol_spike", "correlation_break"],
"detected_at": "2026-04-27T08:32:11Z"
}
}
```
## MEV
Fires when the anomaly detector flags an MEV-extraction spike. Shares the anomaly payload shape with `anomaly_type: "mev_spike"`. Severity is `high`.
```json theme={null}
{
"type": "mev.spike",
"severity": "high",
"subject_id": "vault:ethereum:0xpool...",
"data": {
"anomaly_id": "anom_01J9Z...",
"anomaly_type": "mev_spike",
"severity": "high",
"pool_id": "0xpool...",
"chain": "ethereum",
"protocol": "morpho",
"description": "MEV extraction 4.2x baseline",
"score": 0.88,
"metric_value": 42000,
"baseline_value": 10000,
"deviation_pct": 320.0,
"detected_at": "2026-04-27T08:32:11Z"
}
}
```
Fires when a large sandwich attack is detected. Severity is `high`. Carries the affected pool in `subject_id`; `data` fields are sandwich-specific.
```json theme={null}
{
"type": "mev.sandwich.large",
"severity": "high",
"subject_id": "vault:ethereum:0xpool...",
"data": {
"chain": "ethereum",
"pool_id": "0xpool..."
}
}
```
## Subscribe to these events
```bash curl theme={null}
curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-X POST -d '{
"url": "https://your.app/alterscope-webhook",
"events": ["peg.depeg.start", "oracle.stale", "vault.curator.changed"]
}' \
"https://api.alterscope.org/v2/webhooks"
```
```javascript websocket theme={null}
const ws = new WebSocket(
`wss://api.alterscope.org/v2/ws/risk-events?token=${process.env.ALTERSCOPE_API_KEY}` +
`&types=peg.depeg.start,oracle.stale&severity=high`,
);
ws.onmessage = (e) => console.log(JSON.parse(e.data));
```
WebSocket streaming requires the **Analyst tier or higher**; signed webhooks require the **Team tier or higher**. See [Webhooks](/develop/realtime/webhooks) for signature verification and [WebSockets](/develop/realtime/websockets) for stream filters and per-tier connection limits.