Attack WebSocket Message

This document describes the JSON structure of WebSocket messages delivered to clients when an on-chain attack is detected.

Messages are delivered on two feeds:

• /ws/attacks — every detected attack, delivered immediately. This is the feed described in the bulk of this document.
• /ws/confirmed_attacks — a curated, lower-noise stream of attacks that have been post-processed and confirmed as genuine exploits by an LLM pipeline. See Confirmed-attack feed. A single client may subscribe to both feeds at the same time.

Each message is a single JSON object. There are two variants of the payload:

• Standard attack — the attack does not touch a known protected address.
• Protected-address attack — the attack touches an address the recipient has registered for protection. The payload carries three extra fields (victim_protocol_id, victim_protocol, victim_label).

Top-level schema

The last three fields (victim_protocol_id, victim_protocol, victim_label) are present only in the protected-address variant. For a standard attack they are absent from the JSON document.

Field reference

Field	Type	Description / example values
network	string	Source chain. One of mainnet, bsc, arbitrum, polygon, optimism, base, avax, hyperliquid.
severity	string | null	Risk level. Typical values: "HIGH", "MEDIUM", "LOW", "CRITICAL". May be null when severity could not be computed.
attack_type	string	Type of detection that fired. See Attack types.
transaction_hash	string (0x + 64 hex)	The transaction the alert is bound to.
exploit_address	string (0x + 40 hex)	Contract being interacted with (the suspected exploit / target).
block_number	int	Block height containing the transaction.
block_timestamp	int	Unix epoch seconds, e.g. 1731609600.
proc_time	string	UTC timestamp of when the alert was generated, e.g. "2026-05-13 09:42:11.503127".
attacker_address	string (0x + 40 hex)	EOA / contract that initiated the suspected attack.
input	string	Raw transaction calldata, e.g. "0xa9059cbb0000...".
balance_change	float | null	Net USD value moved by the attacker for this transaction, e.g. 248173.42. Can be 0.0 or negative; null when not computed.
matched_traces	string	Comma-separated trace identifiers that matched the detection rules. Often "".
matched_logs	string	Comma-separated log identifiers that matched. Often "".
matched_selectors	string	Comma-separated 4-byte selectors that matched, e.g. "0xa9059cbb,0x23b872dd". Often "".
victim_address	string | null	Address suffering the largest loss in USD; may be null for attack types without a single identifiable victim.
protocols	object | null	Enrichment payload — see Enriched data.
victim_protocol_id	int (protected-address variant only)	Protocol ID of the matched protected address, e.g. 42.
victim_protocol	string (protected-address variant only)	Human-readable protocol name, e.g. "Aave V3".
victim_label	string (protected-address variant only)	Label associated with the protected address, e.g. "Aave V3 Pool".

Attack types

Possible values of attack_type for network-wide exploit monitoring (i.e. alerts that are not scoped to a specific protected address), subscribe to the following set of attack_type values:

• suspicious_contract_call_with_profit
• highly_complex_transaction_with_profit
• mev_tx_with_unusual_profit
• exploit_in_initcode
• abnormal_token_minting
• suspicious_large_transfer
• access_transfer_to_suspicious_address
• access_transfer_to_suspicious_address_with_profit

Enriched data (protocols)

The protocols field carries enrichment about the victim and the addresses involved in the transaction. Three shapes are possible:

1. null

No enrichment was attached to this alert. The field is emitted as JSON null.

2. Lightweight enrichment

Returned when only victim information is available:

3. Full enrichment

Returned for high-impact alerts and contains, in addition to victim_info, the full set of address-level balance changes for the transaction:

victim_info fields

Field	Type	Example
is_eoa	bool	false
address	string	"0x3333...3333"
name	string | null	"Aave V3", "Unverified contract", or null
symbol	string | null	"aUSDC", "USDC", or null
tvl	number | null	USD TVL when known; null otherwise.
is_coingecko_pool	bool	true when the address was classified as a CoinGecko-tracked liquidity pool.
is_protocol	bool	true for known protocols.
site_url	string | null	Protocol site URL, e.g. "https://aave.com".
protocol_id	int | null	Numeric protocol id, e.g. 42.

balance_changes[] entry fields

Each entry always includes address, balance_change_usd, and is_eoa. The remaining fields depend on how the address was classified (known protocol, CoinGecko pool, verified contract, or unresolved):

Field	Type	When present
address	string	Always (may be "" for synthetic protocol-summary rows).
balance_change_usd	number	Always. Negative = loss, positive = gain. Synthetic protocol-summary rows use 1 as a sentinel.
is_eoa	bool	Always.
name	string | null	Set unless the address is an EOA. "Unverified contract" for unresolved contracts.
symbol	string | null	Token symbol when known.
tvl	number | null	Protocol/pool TVL when known.
site_url	string	Known protocols only.
protocol_id	int	Known-protocol matches only.
is_protocol	bool	Non-EOA entries.
is_coingecko_pool	bool	Set to true only on CoinGecko pool matches.

raw_token_balances

Maps owner_address → { token_address: signed_amount_as_string }. Amounts are raw on-chain integers (un-decimalled) and may be negative strings.

token_prices.token_data

Maps "{network}:{token_address_lower}" to { price, decimals, symbol }, where price and decimals are strings.

End-to-end example

WebSocket payload for an attack on a tracked protected address with full enrichment:

Confirmed-attack feed

Attacks of certain types are additionally post-processed by an LLM pipeline (the /explain-hack command). When that pipeline confirms a transaction is a genuine exploit (as opposed to a false positive such as legitimate MEV / arbitrage or normal protocol activity), the service emits a confirmed attack on a separate feed:

• Endpoint: /ws/confirmed_attacks (same API-key authentication as /ws/attacks).
• Subscription: to receive these over Telegram or to filter by them, use the alert type confirmed_attack in your subscription alerts list. This is independent of the underlying detection type, so you can subscribe to the curated confirmed stream without subscribing to the raw attack types.
• Timing: confirmed attacks arrive after the regular alert (the LLM round-trip takes from a few seconds up to a couple of minutes). Not every attack produces a confirmed attack — false positives are dropped.

Payload

The confirmed-attack payload is a strict superset of the standard attack payload — every field documented above is present with the same name and type, so existing /ws/attacks consumers can parse a confirmed-attack message with their current parser and ignore the extra fields. The confirmed payload adds:

Field	Type	Description
llm_explanation	string	LLM-generated, Telegram-ready report describing the exploit: affected protocol, loss amount, token/price, vulnerability type, a short description, and TX / victim links. Always present.
victim_protocol_id	int | null	Protocol ID of the matched protected address, or null.
victim_protocol	string | null	Human-readable protocol name, or null.
victim_label	string | null	Label of the protected address, or null.

Note the difference from the /ws/attacks feed: there, the three victim_protocol_* fields are omitted for standard attacks and only appear in the protected-address variant. On /ws/confirmed_attacks they are always present, defaulting to null when the attack does not touch a protected address — so the confirmed feed has a single, uniform shape. Detect a protected-address confirmed attack with a null check (victim_protocol_id != null) rather than key presence.

The attack_type field retains the underlying detection type (e.g. suspicious_contract_call_with_profit); the confirmed_attack label is used only for subscription/feed routing, not as the value of attack_type.