Skip to main content
Only available from v4.37.0 onwards.

​
Summary

The useWalletDelegation hook provides methods to trigger and manage the wallet delegation flow for Dynamic embedded wallets. For more information on how wallet delegation works, see the delegated access documentation. The hook needs to be initialized within a child of DynamicContextProvider.

​
Return Value

The hook returns an object with the following properties: 
{
  initDelegationProcess: (options?: { wallets?: Wallet[] }) => Promise<void>;
  shouldPromptWalletDelegation: () => boolean;
  getWalletsDelegatedStatus: () => { address: string; chain: string; status: WalletDelegationStatus }[];
  delegateKeyShares: (wallets?: { chainName: ChainEnum; accountAddress: string }[]) => Promise<void>;
  revokeDelegation: (wallets: { chainName: ChainEnum; accountAddress: string; status: WalletDelegationStatus }[]) => Promise<void>;
  denyWalletDelegation: () => void;
  dismissDelegationPrompt: () => void;
  clearDelegationSessionState: () => void;
  delegatedAccessEnabled: boolean | undefined;
  requiresDelegation: boolean | undefined;
}

​
Functions

​
initDelegationProcess

Initiates the wallet delegation flow by opening the Dynamic modal and displaying the delegation prompt to the user. Parameters:
  • options (optional): Configuration object
    • wallets (optional): Array of specific wallets to delegate. If not provided, delegates all eligible MPC wallets.
Returns: Promise<void> - Resolves when delegation completes successfully, rejects on failure. Errors:
  • Throws "No primary wallet" if the user doesn’t have a primary wallet connected
  • Throws "user_not_logged_in" if the user is not authenticated
Example: 
const { initDelegationProcess } = useWalletDelegation();

try {
  await initDelegationProcess();
  console.log('Delegation completed successfully');
} catch (error) {
  console.error('Delegation failed:', error);
}

​
shouldPromptWalletDelegation

Determines whether the user should be prompted for wallet delegation based on:
  • Delegated access settings in project configuration
  • User’s previous delegation decisions (denied or completed)
  • Existence of undelegated MPC wallets
Returns: boolean - true if the user should see the delegation prompt, false otherwise. Example: 
const { shouldPromptWalletDelegation } = useWalletDelegation();

if (shouldPromptWalletDelegation()) {
  // Show custom UI or automatically trigger delegation
}

​
getWalletsDelegatedStatus

Returns the delegation status of all MPC wallets for the current user. Returns: An array of objects containing:
  • address: string - The wallet address
  • chain: string - The chain the wallet is on
  • status: WalletDelegationStatus - The delegation status (‘delegated’, ‘pending’, or ‘not_delegated’)
Example: 
const { getWalletsDelegatedStatus } = useWalletDelegation();

const walletStatuses = getWalletsDelegatedStatus();

walletStatuses.forEach((wallet) => {
  console.log(`${wallet.address} on ${wallet.chain}: ${wallet.status}`);
});

// Filter for delegated wallets
const delegatedWallets = walletStatuses.filter(
  (wallet) => wallet.status === 'delegated'
);

​
delegateKeyShares

Delegates key shares for one or more wallets. This allows your application to act on behalf of the user’s wallet (see Delegated Access). Parameters:
  • wallets (optional): Array of wallet objects to delegate. Each wallet object should have:
    • chainName: ChainEnum - The chain the wallet is associated with
    • accountAddress: string - The address of the wallet to delegate
If wallets is not provided or is empty, the function will delegate all pending wallets eligible for delegation. Returns: Promise resolving to void. The function automatically refreshes user data after delegation completes. Example: 
import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { delegateKeyShares } = useWalletDelegation();

// Delegate a specific wallet
await delegateKeyShares([
  {
    chainName: ChainEnum.Evm,
    accountAddress: '0x123...',
  },
]);

// Delegate all pending wallets
await delegateKeyShares();
Behavior:
  • Delegates wallets sequentially (one at a time)
  • If a wallet connector is not found for a chain, it skips that wallet and continues
  • Automatically refreshes user data after all delegations complete

​
revokeDelegation

Revokes delegation for one or more wallets. This removes your application’s ability to act on behalf of the user’s wallet (see Revoking Delegation). Parameters:
  • wallets: Array of wallet objects to revoke. Each wallet object should have:
    • chainName: ChainEnum - The chain the wallet is associated with
    • accountAddress: string - The address of the wallet to revoke
    • status: WalletDelegationStatus - The delegation status of the wallet (must be ‘delegated’ for revocation to proceed)
Returns: Promise resolving to void. The function automatically refreshes user data after revocation completes. Example: 
import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { revokeDelegation, getWalletsDelegatedStatus } = useWalletDelegation();

// Get delegated wallets and revoke them
const delegatedWallets = getWalletsDelegatedStatus().filter(
  (wallet) => wallet.status === 'delegated'
);

await revokeDelegation(
  delegatedWallets.map((wallet) => ({
    chainName: wallet.chain as ChainEnum,
    accountAddress: wallet.address,
    status: wallet.status,
  }))
);
Behavior:
  • Revokes wallets sequentially (one at a time)
  • Only attempts to revoke wallets with status ‘delegated’ (logs a warning and skips others)
  • If a wallet connector is not found for a chain, it skips that wallet and continues
  • If revocation fails for a wallet, it logs an error but continues with other wallets
  • Automatically refreshes user data after all revocations complete

​
denyWalletDelegation

Permanently denies wallet delegation for the current user. This sets a flag that prevents the delegation prompt from appearing again, even if the user has undelegated wallets. Returns: void Example: 
const { denyWalletDelegation, shouldPromptWalletDelegation } = useWalletDelegation();

// User clicks "Don't ask again" button
const handleDenyDelegation = () => {
  denyWalletDelegation();
  // shouldPromptWalletDelegation() will now return false
};

​
dismissDelegationPrompt

Temporarily dismisses the delegation prompt for the current session. Unlike denyWalletDelegation, this does not permanently prevent the prompt from appearing - it will show again in future sessions. Returns: void Example: 
const { dismissDelegationPrompt } = useWalletDelegation();

// User clicks "Maybe later" button
const handleDismiss = () => {
  dismissDelegationPrompt();
  // Prompt won't appear again this session
};

​
clearDelegationSessionState

Clears all delegation-related session state, including any “denied” or “dismissed” flags. This resets the delegation prompt behavior, allowing it to appear again based on the user’s wallet status. Returns: void Example: 
const { clearDelegationSessionState, shouldPromptWalletDelegation } = useWalletDelegation();

// Reset delegation state (e.g., when user wants to reconsider)
const handleResetDelegationState = () => {
  clearDelegationSessionState();
  // Delegation prompt can now appear again if conditions are met
  if (shouldPromptWalletDelegation()) {
    // Show delegation prompt
  }
};

​
Properties

​
delegatedAccessEnabled

A boolean value from your project settings that indicates whether delegated access is enabled for your application. Type: boolean | undefined Example: 
const { delegatedAccessEnabled } = useWalletDelegation();

if (delegatedAccessEnabled) {
  // Delegated access feature is enabled
  // You can show delegation-related UI
}

​
requiresDelegation

A boolean value from your project settings that indicates whether wallet delegation is required for your application. Type: boolean | undefined Example: 
const { requiresDelegation } = useWalletDelegation();

if (requiresDelegation) {
  // Delegation is mandatory for this application
  // You might want to block certain actions until delegation is complete
}

​
Usage

import { useWalletDelegation } from '@dynamic-labs/sdk-react-core';

const MyComponent = () => {
  const { 
    initDelegationProcess, 
    shouldPromptWalletDelegation,
    getWalletsDelegatedStatus,
    denyWalletDelegation,
    dismissDelegationPrompt,
    delegatedAccessEnabled,
    requiresDelegation 
  } = useWalletDelegation();

  const handleDelegateWallet = async () => {
    try {
      await initDelegationProcess();
      console.log('Wallet delegation successful!');
    } catch (error) {
      console.error('Failed to delegate wallet:', error);
    }
  };

  // Automatically prompt on mount if needed
  useEffect(() => {
    if (shouldPromptWalletDelegation()) {
      initDelegationProcess();
    }
  }, []);

  // Check delegation status of wallets
  const walletStatuses = getWalletsDelegatedStatus();
  const hasDelegatedWallets = walletStatuses.some(w => w.status === 'delegated');

  return (
    <div>
      {delegatedAccessEnabled && !hasDelegatedWallets && (
        <div>
          <p>Enable delegated access for a better experience</p>
          <button onClick={handleDelegateWallet}>Delegate Wallet</button>
          <button onClick={dismissDelegationPrompt}>Maybe Later</button>
          <button onClick={denyWalletDelegation}>Don't Ask Again</button>
        </div>
      )}
      {requiresDelegation && !hasDelegatedWallets && (
        <p>This app requires wallet delegation to function</p>
      )}
    </div>
  );
};

​
Advanced Usage

Delegate specific wallets: 
import { useWalletDelegation } from '@dynamic-labs/sdk-react-core';
import { useUserWallets } from '@dynamic-labs/sdk-react-core';

const MyComponent = () => {
  const { initDelegationProcess } = useWalletDelegation();
  const { userWallets } = useUserWallets();

  const delegateSpecificWallet = async (walletId: string) => {
    const wallet = userWallets.find(w => w.id === walletId);
    
    if (wallet) {
      try {
        await initDelegationProcess({ wallets: [wallet] });
        console.log('Specific wallet delegated successfully');
      } catch (error) {
        console.error('Delegation failed:', error);
      }
    }
  };

  return (
    <div>
      {userWallets.map(wallet => (
        <button 
          key={wallet.id}
          onClick={() => delegateSpecificWallet(wallet.id)}
        >
          Delegate {wallet.address}
        </button>
      ))}
    </div>
  );
};

​
Important Notes

  • The user must be authenticated and have a primary wallet for delegation to work
  • The delegation modal is part of the Dynamic UI and handles all user interactions
  • User delegation preferences are persisted across sessions using local storage

​
Learn More