Address Screening

How Dynamic screens wallet addresses against sanctions data, and how to run screening on your own Chainalysis or TRM Labs API key.

Address screening checks a wallet address against sanctions data before that address is allowed to authenticate, and before a transaction is signed.

Screening runs server-side. Dynamic runs it for you on every surface listed below.

The sanctions baseline

Every environment gets the sanctions baseline. It is the layer you cannot disable, edit, or weaken.

• The baseline runs on every screen.
• Which dataset backs the baseline depends on which provider answered. Dynamic-managed screening matches Dynamic’s own sanctions data, compiled from government sanctions lists including the OFAC Specially Designated Nationals (SDN) list. Your own screening provider key matches that provider’s sanctions determination inside its own response.
• The baseline cannot be disabled. The developer console shows Block Access to Sanctioned Wallets as permanently on.
• The baseline is evaluated first, before any rule you write. No rule and no exempted address can let a sanctioned address through.
• Every wallet on the user’s account is screened on each verification: embedded, external, and smart contract wallets.
• If any wallet on the account matches, the whole sign-in is rejected. It is not enough to disconnect the matched wallet during that attempt.

An address is blocked by the baseline when screening returns a sanctions match:

• the address is on a sanctions list, or
• a screening provider attributes the address to a sanctioned entity or a sanctioned jurisdiction.

When you supply your own provider key, that provider’s determination governs every address it answers for. An address on Dynamic’s sanctions list that your provider does not categorize as sanctioned is not blocked by the baseline. That is what running screening on your own key means. Dynamic’s own data still backs every screen your provider did not answer.

What the baseline does not block

The baseline does not block on:

• a provider risk score or risk rating, at any value
• indirect or counterparty exposure to a sanctioned address
• non-sanctions provider categories, such as gambling, mining, or scam attribution

Dynamic does not apply risk-based blocking on your behalf. Dynamic blocks on sanctions signals only.

You can act on those signals yourself. A screening policy maps your provider’s own categories, scores, and exposure signals to block, alert, or allow. A policy adds to the baseline and can only make screening stricter. Screening policies require your own provider key.

Where screening runs

Screening runs at sign-in, when a wallet is linked to an existing user, on wallet connect, on checkout and Flow source and destination addresses, before a transaction is signed, and on the screening API.

Bring your own screening key

Bring your own screening key is in Beta and is enabled per environment. To enable it, contact us through Slack or email.

By default, screening uses Dynamic-managed screening. You can instead supply your own provider API key, so screening calls run against your contract with that provider and appear in that provider’s audit trail.

Two providers are supported:

• TRM Labs: the Wallet Screening API. Requires a TRM Labs contract that includes wallet screening.
• Chainalysis: the Address Screening API. Requires a Chainalysis contract that includes address screening.

Best for: compliance teams that already hold a provider contract and need screening decisions, billing, and audit logs to sit in their own provider account.

Supplying your own key changes which account the screening call bills to and which provider data backs the decision. It does not change the sanctions baseline. It does let you author a screening policy, which is the only way to block on anything other than a sanctions match.

Add a key

1. Open Fraud Protection in the developer console.
2. Under Compliance Screening, find Bring Your Own Screening Key.
3. On the TRM Labs or Chainalysis card, select Add, paste your API key, and save.

You must have the Admin role on the environment to add, update, or remove a key. Members with a lower role see the section read-only.

Dynamic validates the key against the provider before storing it. A key the provider rejects is not stored, and the developer console reports why: an invalid key, a key in the wrong format, a rate or quota limit on your provider account, or a provider that could not be reached.

How your key is used

• Keys are scoped to one environment. Sandbox and live environments hold separate keys.
• You can configure one provider or both. When both are configured, both run on every screen, unless your screening policy skips one.
• If either provider returns a sanctions match, the address is blocked.
• Dynamic-managed screening runs whenever a configured provider did not reach a verdict. That covers a provider call your policy skipped, a provider error, and a chain the provider does not support. A screen where every configured provider answered does not also call Dynamic-managed screening, because each provider evaluated the sanctions baseline against its own response.
• Keys are encrypted at rest. The developer console shows only the last three characters, and no API returns a stored key.

Rotate or remove a key

• Update replaces the stored key. Screening uses the new key on the next check.
• Remove deletes the stored key. Screening returns to Dynamic-managed screening on the next check. Your screening policy stops being evaluated, because a policy is evaluated against a provider response.

Dynamic does not notify you when your provider key stops working. Monitor your screening event volume and your provider’s own dashboard to confirm your key is still in use.

When an address is blocked

• Dynamic rejects the verification request with 403. No JWT is returned, so the user does not reach an authenticated state.
• The end user sees an access-denied view instead of completing sign-in. Dynamic’s UI renders this view; SDKs without Dynamic’s UI surface a typed screening error you handle yourself. See the address screening page for React, React Native, or JavaScript.
• Dynamic sends a webhook event. A sanctions match sends wallet.sanctions.blocked. A block from your own screening policy sends wallet.addressScreening.blocked, and an alert sends wallet.addressScreening.alerted.

An alert from your screening policy changes nothing for the end user. The request proceeds, and the wallet.addressScreening.alerted event is the only record of it.

Your responsibilities

• Dynamic screens addresses against sanctions data and blocks matches.
• You are responsible for your own compliance program, including any risk-based decisions, record keeping, and reporting obligations that sanctions screening alone does not satisfy.
• You are responsible for the rules in any screening policy you author, and for the users those rules block.
• You are responsible for keeping any provider key you supply valid and funded.