Creating a Dynamic Client

Important: All other methods in the JavaScript SDK require a Dynamic client to be created first.

Installation

npm install @dynamic-labs-sdk/client

Usage

Create the client in a module that loads once (for example dynamicClient.ts in a React app) and share that instance across your app. The API is the same in React and plain JavaScript.

Web
React Native

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

const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  metadata: {
    name: 'YOUR_APP_NAME',
    universalLink: 'https://yourapp.com',
    iconUrl: 'YOUR_APP_ICON_URL',
  },
});

On React Native, set both nativeLink and universalLink. universalLink is required for passkeys and matches the window.location polyfill; nativeLink must match the deep link scheme you register in your native projects. Set up polyfills and native configuration first — see React Native Setup.

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

const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  metadata: {
    name: 'YOUR_APP_NAME',
    nativeLink: 'myapp://', // Must match the scheme registered in Info.plist / AndroidManifest.xml
    universalLink: 'https://yourapp.com', // Required for passkeys; same value as the window.location polyfill
    iconUrl: 'YOUR_APP_ICON_URL',
  },
});

You can get your environment ID from the Dynamic Console.

Configuration Options

Basic Options

environmentId (required): Your Dynamic environment ID
autoInitialize (optional): Whether to automatically initialize the client (default: true)
metadata (optional): Your app’s metadata
- name: The name of your app
- universalLink: The official domain/URL of your app (e.g., https://yourapp.com). Used for deep link redirects and as the domain in sign-in message signatures.
- iconUrl: The URL of the icon of your app
- nativeLink: Native deep link for your app (e.g., myapp://). Used for app-to-app communication on mobile devices.
logLevel (optional): Logging level for the SDK

Core configuration

Use coreConfig to override low-level SDK behavior such as the API base URL, custom fetch implementation, and platform-specific handlers. Most apps only need this for the apiBaseUrl used by cookie-based authentication.

import { createDynamicClient } from '@dynamic-labs-sdk/client';
const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  coreConfig: {
    apiBaseUrl: 'https://auth.example.io/api/v0',
  },
});

apiBaseUrl (optional): Override the Dynamic API base URL. Required when using cookie-based authentication with a custom hostname.

Advanced Options

Transformers

Customize SDK data before it’s used throughout your application:

import { createDynamicClient } from '@dynamic-labs-sdk/client';
const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  transformers: {
    networksData: (networksData) =>
      networksData.map((network) => {
        // Override RPC URLs
        if (network.networkId === '1') {
          return {
            ...network,
            rpcUrls: {
              http: ['https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY'],
            },
          };
        }
        return network;
      }),
  },
});

See Network Transformers for more details.

WaaS Options

The waas object tunes the embedded wallet (MPC / Wallet-as-a-Service) behavior. Every option is optional.

import { createDynamicClient } from '@dynamic-labs-sdk/client';
const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  waas: {
    loadTimeoutMs: 5000,
    maxLoadRetries: 0,
  },
});

loadTimeoutMs (optional, default 20000): Per-attempt timeout, in milliseconds, for loading the embedded wallet’s secure container. Must be a number between 1000 and 60000; values outside that range are rejected with an InvalidParamError at client creation.
maxLoadRetries (optional, default 1): Extra load attempts (after the first) before the wallet gives up and embedded wallet operations reject with WaasLoadFailedError. Must be an integer between 0 and 10; values outside that range are rejected with an InvalidParamError at client creation.
additionalTrustedOrigins (optional): Extra origins allowed when the WaaS iframe validates postMessage sources — for example, when your app is embedded in another trusted origin.

Lower loadTimeoutMs and maxLoadRetries together to fail fast and drive your own retry cadence on a caught WaasLoadFailedError. The worst-case time until that error is (maxLoadRetries + 1) * loadTimeoutMs + maxLoadRetries * 1000 for the first load cycle.

This tuning applies process-wide. All chains — and all Dynamic clients on the same page — share one embedded wallet container, and the values are written to shared state whenever a client with an explicit override is constructed. A later client without an override inherits the last explicitly-set values, not the defaults. After an exhausted load cycle, the effective timeout doubles for subsequent cycles (capped at 60000 ms) and never resets for the page’s lifetime.

React Native options

The reactNative object holds options that apply only when the client runs in React Native. Every option is optional, and the web ignores the object.

import { createDynamicClient } from '@dynamic-labs-sdk/client';
const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  reactNative: {
    android: {
      strongBox: true,
    },
  },
});

android.strongBox (optional, default false): Whether the device and session signing keys on Android are backed by the StrongBox secure element instead of the device’s TEE. When StrongBox is unavailable, the SDK creates a TEE-backed key instead. iOS ignores the option. Requires @dynamic-labs-sdk/client version 1.49.1 or later, and a rebuilt native app. See Device key storage for the trade-offs.

Learn

Build with

Creating a Dynamic Client

Installation

Usage

Configuration Options

Basic Options

Core configuration

Advanced Options

Transformers

WaaS Options

React Native options

​Installation

​Usage

​Configuration Options

​Basic Options

​Core configuration

​Advanced Options

​Transformers

​WaaS Options

​React Native options

Installation

Usage

Configuration Options

Basic Options

Core configuration

Advanced Options

Transformers

WaaS Options

React Native options