Address Screening

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Dynamic screens every wallet address that signs in to your environment against sanctions data, and blocks matches. Screening runs server-side during wallet verification, is always on, and needs no setup in the SDK. For what screening checks and how to run it on your own Chainalysis or TRM Labs key, see Address Screening. This page covers what your React app shows when an address is blocked.

What the user sees

When verification returns a screening block, the SDK disconnects the wallet and renders its access-denied view inside the widget:

Title: “This address seems corrupted.”
Body: “This wallet has been correlated to illicit activity and cannot access this site.”
Action: “Try another method”, which returns the user to the wallet list.

You do not need to catch an error or render a fallback. The view is part of the auth flow.

Keep any copy you write here neutral and final. The user usually cannot change a screening result, so offer a different wallet rather than a retry that will fail again.

Changing the copy

Override the dyn_no_access.chainalysis keys through the locale prop on DynamicContextProvider:

import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';

<DynamicContextProvider
  settings={{
    environmentId: 'YOUR_ENVIRONMENT_ID',
    walletConnectors: [EthereumWalletConnectors],
  }}
  locale={{
    en: {
      dyn_no_access: {
        chainalysis: {
          title: "This wallet can't be used here",
          description:
            'Contact support@yourcompany.com if you believe this is a mistake.',
          button_text: 'Try another wallet',
          social_media_link_text: 'Why am I seeing this?',
          social_media_link_url: 'https://yourcompany.com/help/screening',
        },
      },
    },
  }}
>
  <App />
</DynamicContextProvider>

The chainalysis key name is historical. These keys drive the access-denied view for every screening provider. For the full locale object and how to add other languages, see Adapt Copy With Translations.

Reacting in your own code

To act on a block outside the widget (clear app state, log it, or route the user elsewhere), check the reason passed to onAuthFailure for a ChainalysisError:

import {
  ChainalysisError,
  DynamicContextProvider,
} from '@dynamic-labs/sdk-react-core';
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';

<DynamicContextProvider
  settings={{
    environmentId: 'YOUR_ENVIRONMENT_ID',
    walletConnectors: [EthereumWalletConnectors],
    events: {
      onAuthFailure: (method, reason) => {
        const error = typeof reason === 'object' ? reason.error : undefined;

        if (error instanceof ChainalysisError) {
          // recordScreeningBlock is your implementation.
          recordScreeningBlock(error.walletPublicKey);
        }
      },
    },
  }}
>
  <App />
</DynamicContextProvider>

ChainalysisError is the error class for every screening block, whichever provider produced the match. Its walletPublicKey holds the blocked address. Server-side, subscribe to the wallet.sanctions.blocked webhook event to record blocks. The webhook fires whether or not the user is still on the page.

Implementation Guides

SDK Reference

Address Screening

Recommended: JavaScript SDK with React Hooks

What the user sees

Changing the copy

Reacting in your own code

See also

Recommended: JavaScript SDK with React Hooks

​What the user sees

​Changing the copy

​Reacting in your own code

​See also

What the user sees

Changing the copy

Reacting in your own code

See also