Handling blocked wallets

Detect a wallet rejected by compliance screening and show a clear access-denied experience.

Prerequisites

Before this page: a wallet connection flow (see Connecting external wallets).

What you’ll build

When your project enables compliance screening, a wallet that fails (for example, one on a sanctions list) is rejected during verification with a typed WalletScreeningBlockedError. You’ll catch it and show a clear access-denied state instead of a generic failure.

Screening runs server-side during connect + verify — you don’t call it yourself. Your job is to branch on the specific error.

Catching the blocked error

TypeScript

import {
  connectAndVerifyWithWalletProvider,
  WalletScreeningBlockedError,
} from '@dynamic-labs-sdk/client';

async function connect(walletProviderKey: string) {
  try {
    const walletAccount = await connectAndVerifyWithWalletProvider({
      walletProviderKey,
    });
    // showConnected is your implementation.
    showConnected(walletAccount);
  } catch (error) {
    if (error instanceof WalletScreeningBlockedError) {
      // showAccessDenied is your implementation.
      showAccessDenied("This wallet can't be used here.");
      return;
    }
    throw error;
  }
}

React

import { WalletScreeningBlockedError } from '@dynamic-labs-sdk/client';
import { useConnectAndVerifyWithWalletProvider } from '@dynamic-labs-sdk/react-hooks';

function ConnectButton({ walletProviderKey }: { walletProviderKey: string }) {
  const { mutate: connectAndVerify, isPending, error } =
    useConnectAndVerifyWithWalletProvider();

  const isBlocked = error instanceof WalletScreeningBlockedError;

  return (
    <>
      {isBlocked ? (
        <p role="alert">This wallet can't be used here.</p>
      ) : null}
      <button
        type="button"
        onClick={() => connectAndVerify({ walletProviderKey })}
        disabled={isPending}
      >
        Connect wallet
      </button>
    </>
  );
}

Keep the access-denied copy neutral — the user usually can’t fix a screening result. Offer a way to connect a different wallet or contact support rather than a retry that will fail again.

Handling errors

Error	Cause	What to do
WalletScreeningBlockedError	The wallet failed compliance screening	Show an access-denied state; offer a different wallet or support.
Other verification errors	Connection or signature issues	Handle as in Connecting external wallets (retryable).

See also

• Connecting external wallets — the connect + verify flow that runs screening
• Connected wallets management — manage wallets that passed screening