Skip to main content

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:
​
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.

Last modified on October 6, 2026