Basic setup

This page covers the foundational changes: how you create and provide the SDK, how you read state, and the shift from an event-driven model to an imperative one. Read the migration overview first if you haven’t.

Provider and client

In the React SDK a single DynamicContextProvider created the SDK, held configuration, and exposed everything through useDynamicContext(). In the JavaScript SDK you create the client yourself with createDynamicClient() and, in React, pass it to a thin DynamicProvider. State is read through focused hooks instead of one context object. Create the client once in a module that loads at startup and register your chain extensions. The client initializes itself automatically.

TypeScript
React

// dynamicClient.ts
import { createDynamicClient } from '@dynamic-labs-sdk/client';
import { addEvmExtension } from '@dynamic-labs-sdk/evm';

export const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  metadata: {
    name: 'My App',
    universalLink: window.location.origin,
  },
});

addEvmExtension();

// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { DynamicProvider } from '@dynamic-labs-sdk/react-hooks';

import { App } from './App';
import { dynamicClient } from './dynamicClient';

const queryClient = new QueryClient();

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <DynamicProvider client={dynamicClient}>
        <App />
      </DynamicProvider>
    </QueryClientProvider>
  </StrictMode>,
);

In React, @dynamic-labs-sdk/react-hooks is built on TanStack Query, so a QueryClientProvider must wrap DynamicProvider. See the React Quickstart for the full setup.

Reading state

useDynamicContext() no longer exists. Instead, import the specific hook (React) or read the equivalent property/function on the client instance (vanilla) for the state you need.

React SDK	JavaScript SDK
`useDynamicContext().user`	`useUser()` / `dynamicClient.user`
`useDynamicContext()`’s tracked wallet	`useGetWalletAccounts()` / `getWalletAccounts()` — pass the specific account you mean
`useDynamicContext().network`	`getActiveNetworkData()`
`useReinitialize()`	`initializeClient()`
`useDynamicEvents()`	`useOnEvent()` / `useOnceEvent()` (or `onEvent()` / `offEvent()`)

Waiting for initialization

The React SDK gated your app behind its own loading state. Now you decide when the client is ready — either await a helper (vanilla) or render off the init status (React).

TypeScript
React

import { waitForClientInitialized } from '@dynamic-labs-sdk/client';

await waitForClientInitialized();
// The client is ready — safe to call other SDK functions.

import { useInitStatus } from '@dynamic-labs-sdk/react-hooks';

export function App() {
  const { data: initStatus } = useInitStatus();

  if (initStatus === 'uninitialized' || initStatus === 'in-progress') {
    return <LoadingState />;
  }

  if (initStatus === 'failed') {
    return <ErrorState />;
  }

  return <YourApp />;
}

From events to promises

This is the most important shift. The React SDK was reactive: you subscribed to events (onAuthSuccess, onWalletAdded, …) and the SDK told you when things happened. The JavaScript SDK is imperative: you call a function, and you get the result back directly — from the resolved promise (vanilla) or the hook’s onSuccess/onError callbacks (React). You already know when a flow starts and finishes because you started it. Events still exist for genuinely ambient state changes (a wallet added, a session expiring), but they’re no longer how you observe the outcome of an action you triggered.

React SDK event	JavaScript SDK equivalent
`onAuthInit`	You call the auth function — you know when it starts
`onAuthSuccess`	The auth call’s promise resolves (or hook `onSuccess`)
`onAuthFailure`	`try/catch` around the call (or hook `onError`)
`onAuthFlowCancel` / `onAuthFlowClose` / `onAuthFlowOpen`	You own the auth UI lifecycle directly
`onLogout`	`onEvent({ event: 'logout' })`, or handle inline after `logout()`
`onUserProfileUpdate`	`useUser()` reactivity / refresh after update
`onOtpVerificationResult`	`verifyOTP()` resolves or rejects
`onSignedMessage`	`signMessage()` resolves with the signature
`onWalletAdded` / `onWalletRemoved`	`onEvent({ event: 'walletAccountsChanged' })`
`onWalletConnectionFailed`	`connectWithWalletProvider()` promise rejects

Subscribing to the events that remain

When you do want to react to ambient state changes, subscribe with onEvent (vanilla) or useOnEvent (React), which handles cleanup for you.

TypeScript
React

import { onEvent } from '@dynamic-labs-sdk/client';

const unsubscribe = onEvent({
  event: 'walletAccountsChanged',
  listener: ({ walletAccounts }) => {
    renderWallets(walletAccounts);
  },
});

// Call unsubscribe() when you no longer need the listener.

import { useOnEvent } from '@dynamic-labs-sdk/react-hooks';

function useWalletAccountsWatcher() {
  useOnEvent({
    event: 'walletAccountsChanged',
    listener: ({ walletAccounts }) => {
      renderWallets(walletAccounts);
    },
  });
}

The core events include initStatusChanged, initErrorChanged, userChanged, tokenChanged, sessionExpiresAtChanged, mfaTokenChanged, projectSettingsChanged, walletAccountsChanged, and logout. The client emits additional events (for example around MFA, checkout, device registration, wallet providers, and flow execution) that follow the same subscribe pattern.

RPC URL overrides

overrideNetworkRpcUrl is gone. Configure RPC URLs (and any other network overrides) with a networksData transformer when you create the client. It receives the full list of networks and returns the list the SDK should use, so you can rewrite, filter, or reorder them in one place — the first network of a chain is the default for wallets with no saved selection, so reordering also sets that default.

const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  transformers: {
    networksData: (networks) =>
      networks.map((network) =>
        network.networkId === '1'
          ? { ...network, rpcUrls: { http: ['https://your-rpc.example/eth'] } }
          : network,
      ),
  },
});

See Network transformers for the full API.

Ethers.js is not supported. Migrate wallet/provider code to viem, which the EVM extension returns directly.

Installation & Configuration

React Native

Building UI

Migrating from React

Chains & Networks

Authenticate

User & Session Management

Wallets

Flow

Swaps

Funding & Onramp

Events

Provider and client

Reading state

Waiting for initialization

From events to promises

Subscribing to the events that remain

RPC URL overrides

See also

​Provider and client

​Reading state

​Waiting for initialization

​From events to promises

​Subscribing to the events that remain

​RPC URL overrides

​See also

Provider and client

Reading state

Waiting for initialization

From events to promises

Subscribing to the events that remain

RPC URL overrides

See also