SanctionsWalletBlockedEventPayload

Payload of the wallet.sanctions.blocked webhook event, and of its deprecated sanctions.wallet.blocked alias.

Scope: the sanctions floor only. A block produced by a customer's own screening policy emits wallet.addressScreening.blocked instead, which carries a reason explaining which rule matched. A block with no policy engine in play — the flag off, or a provider the engine does not evaluate — emits this event, so an environment that has authored nothing sees exactly what it saw before.

Trigger semantics:

• Fires once per user-facing BLOCKED boundary decision (the orchestrator's winning result), not per provider response — including decisions served from the screening cache, since the cache is shared across environments and flows. Each blocked action in your environment produces its own event with its own origin.
• backgroundPrefetch is the exception: the background cache-warming check emits only on a fresh discovery, never on a cache hit, so a blocked returning user does not re-emit per visit. A block discovered this way warms the cache; subsequent user-facing flows that hit that cache DO emit with their own origin.
• NOT emitted on OK, FLAGGED, REVIEW, or ERROR outcomes (v1 surfaces BLOCKED only).
• Customers opt in via the existing webhook subscription UI.

walletAddress · string · required

Lowercase, normalized address that was blocked.

chain · string · required

Chain identifier (e.g. 'ethereum', 'bitcoin', 'solana'). Canonical value recorded on the screening audit record.

Example:

"ethereum"

sanctionsProvider · enum<string> · required

Available options: trm-wallet-screening, chainalysis-address-screening, dynamic-sanctions-screening

sanctionCheckRequestId · string<uuid> · required

Forensic key into the screening audit record.

categories · string[] · required

Vendor-returned categories that triggered the block. May be empty when the decision was served from the screening cache (cached rows do not retain vendor categories).

Example:

["Sanctions", "Blocklisted"]

origin · enum<string> · required

User-flow surface that triggered the screening which produced this BLOCKED decision. signIn: user login/session verification. walletConnect: external wallet connect. checkoutDestination: a destination address in the checkout flow (checkout create/update or checkout transaction create). checkoutSource: the from-address funding a checkout transaction. flowDestination: flow create destination address. flowSource: the from-address funding a flow. api: direct wallet-sanctions API query. backgroundPrefetch: background cache-warming check (see trigger semantics above). transactionSigning: a decoded transaction destination screened before the MPC signing ceremony for an embedded wallet (hard-enforced server-side). transactionScreenApi: a decoded transaction destination screened for a connected/external wallet via the public screen API (best-effort, client-side). This enum will grow as new screening surfaces are added; consumers should handle unrecognized values gracefully.

Available options: signIn, walletConnect, checkoutDestination, checkoutSource, flowDestination, flowSource, api, backgroundPrefetch, transactionSigning, transactionScreenApi

keyOwner · enum<string> · required

Who owns the key used for the check. customerProvided if the check ran against a customer-supplied BYOK key; dynamic if it ran against a Dynamic-managed key.

Available options: dynamic, customerProvided

screenedAt · string<date-time> · required

ISO 8601 timestamp of when the screening decision landed.