client

Recommended: JavaScript SDK for React Native

While this SDK is still supported, we recommend using newer JavaScript SDK, which is optimized for React Native, but also comes with a host of other benefits.

The base package that provides access to the Dynamic Client, which can be extended with extension packages.

Functions

createClient

createClient(params: ClientProps): BaseClient

Returns an instance of a client object, which provides an interface to read state, trigger actions and listen to events of our SDK.

Types

ClientProps type

The parameters that are acceptable by the createClient method.

Param	Type	Description
environmentId	string	The ID of the environment of your dynamic application.
apiBaseUrl	string?	Allows you to override the URL to which the SDK will make its API requests.
cssOverrides	string?	Allows you to inject CSS into our UI modules (currently out of effect)
appName	string?	How you’d like your app to be named in our copies.
appLogoUrl	string?	A URL of the logo of your app.
evmNetworks	EvmNetwork[]	The networks that are currently configured. See EvmNetwork
globalWallets	string[]?	Array of global wallet identifiers to enable. Available option: 'sei'
connectOnly	boolean?	If true, enables connect-only mode where users can connect wallets without signing a message. See Connected vs Authenticated. Defaults to false.
useMetamaskSdk	boolean?	If true, use MetaMask SDK for MetaMask connections. If false or undefined, use WalletConnect for MetaMask connections. Only applies to mobile platforms (React Native, Flutter, Swift). Defaults to false.
locale	LocaleResource?	Overrides or adds translations for the copy shown in Dynamic’s embedded UI (for example the wallet export / reveal screens). Keyed by language code, then by translation key.

BaseClient type

The base type of a client.

Since clients can be extended (and thus have their types composed with those of the extensions), this is considered the most basic kind of client: the one that is returned from the createClient method.

Besides the .extend method which is inherited from the Extendable class, it is composed of properties which we call modules.

Note that all client modules implement an event emitter interface that allows you to call on, off and once to create and destroy event listeners.

For every property that is a state, there will always be an event name with the same name plus "Changed", which will be triggered when the property changes value. We will omit these from the docs below as they are implicit.

auth module

Provides access to authentication related properties and methods of the SDK.

Property	Type	Description
token	string | null	The JWT of the currently logged in user.
authenticatedUser	UserProfile | null	The UserProfile object of the logged in user.
logout	() => Promise<void>	Allows you to log the current user out.
refreshUser	() => Promise<UserProfile | null>	Refreshes the user (available from v4.20.10).
updateUser	(userFields: UpdateUserFieldsArg) => Promise<UpdateUserReturnPayload>	Updates the current user’s profile. Returns verification requirements and response (available from v4.38.0).
verifyUserUpdateOtp	(verificationToken: string) => Promise<UpdateUserReturnPayload>	Verifies OTP for user profile update (available from v4.38.0).
signInWithExternalJwt	({ externalJwt: string; externalUserId: string }) => Promise<void>	Logs the user in with a third-party JWT. This must be enabled in dashboard first.
verifyWithExternalJwt	({ externalJwt: string; externalUserId: string }) => Promise<void>	Links the dynamic user in with a third-party JWT. This must be enabled in dashboard first.

Event name	Type	Description
authInit	(data: AuthEventPayload) => void	Emitted when the user initializes authentication, but before it either completes or fails.
authSuccess	(user: UserProfile) => void	Emitted when the user successfully logs in.
authFailed	(data: AuthEventPayload, reason: 'user-cancelled' | { error: unknown }) => void	Emitted when the user fails to log in.
loggedOut	(user: UserProfile | null) => void	Emitted when the user logs out.
userProfileUpdated	(user: UserProfile) => void	Emitted when the user’s profile is updated.
authenticatedUserChanged	(authenticatedUser: UserProfile | null) => void	State change event for the authenticatedUser variable.
tokenChanged	(token: string | null) => void	State change event for the token variable.

auth.email submodule

Provides methods to send, re-send and verify OTPs to email.

Property	Type	Description
sendOTP	(target: string) => Promise<void>	Sends an OTP token to the target email.
resendOTP	() => Promise<void>	Sends another OTP token to the same email as the last call to sendOTP.
verifyOTP	(token: string) => Promise<void>	Receives an OTP token and logs the user in if it is valid.

Event name	Type	Description
emailVerificationFinished	(params: { isSuccess: boolean; destination: string }) => void	Emitted when the email verification process is completed.

auth.sms submodule

Provides methods to send, re-send and verify OTPs to phone numbers.

Property	Type	Description
sendOTP	(target: PhoneData) => Promise<void>	Sends an OTP token to the target PhoneData.
resendOTP	() => Promise<void>	Sends another OTP token to the same phone number as the last call to sendOTP.
verifyOTP	(token: string) => Promise<void>	Receives an OTP token and logs the user in if it is valid.

Event name	Type	Description
smsVerificationFinished	(params: { isSuccess: boolean; destination: PhoneData }) => void	Emitted when the SMS verification process is completed. See PhoneData

auth.social submodule

Provides methods to connect, manage, and query social accounts.

Property	Type	Description
connect	(args: { provider: ProviderEnum }) => Promise<void>	Requests social connection to the provided SocialProvider.
getLinkedAccounts	(provider: ProviderEnum) => Promise<SocialAccountInformation[]>	Retrieves all linked social accounts for a specific provider.
getAllLinkedAccounts	() => Promise<SocialAccountInformation[]>	Retrieves all linked social accounts across all providers.
isLinked	(provider: ProviderEnum) => Promise<boolean>	Checks if the user has any linked accounts for a specific provider.
unlink	(provider: ProviderEnum, verifiedCredentialId?: string) => Promise<void>	Unlinks a social account from the user’s profile. If multiple accounts exist for a provider, specify the verifiedCredentialId.

locale module

Provides methods for managing SDK language and localization. Available from v4.38.0.

Property	Type	Description
changeLanguage	(language: string) => Promise<void>	Changes the SDK language/locale.

mfa module

Provides methods for managing Multi-Factor Authentication (MFA) devices, recovery codes, and authentication flows.

Property	Type	Description
addDevice	(type?: MFADeviceType) => Promise<{ id: string; secret: string; uri: string }>	Initiates the process of adding a new MFA device. Returns device details including QR code URI for TOTP setup.
authDevice	(code: string, type?: MFADeviceType, deviceId?: string) => Promise<boolean>	Authenticates using an MFA device with the provided code.
authenticateDevice	({ code, type, deviceId, createMfaToken }: { code: string; type?: MFADeviceType; deviceId?: string; createMfaToken?: CreateMfaToken }) => Promise<string | null>	Authenticates an MFA device and optionally creates an MFA token. Returns the token if successful.
authenticateRecoveryCode	({ code, createMfaToken }: { code: string; createMfaToken?: CreateMfaToken }) => Promise<string | null>	Authenticates using a recovery code and optionally creates an MFA token. Returns the token if successful.
authRecoveryCode	(code: string) => Promise<boolean>	Authenticates using a recovery code.
completeAcknowledgement	() => Promise<void>	Completes the acknowledgement of recovery codes after they have been displayed to the user.
deleteUserDevice	(deviceId: string, mfaAuthToken: string) => Promise<void>	Deletes an MFA device from the user’s account. Requires an MFA authentication token.
getNewRecoveryCodes	() => Promise<string[]>	Generates and returns a new set of recovery codes, invalidating the old ones.
getRecoveryCodes	(generateNewCodes?: boolean) => Promise<string[]>	Retrieves the user’s recovery codes. Optionally generates new codes if generateNewCodes is true.
getUserDevices	() => Promise<MFADevice[]>	Retrieves all MFA devices associated with the user’s account.
isPendingRecoveryCodesAcknowledgment	() => Promise<boolean>	Checks if there are recovery codes pending acknowledgement by the user.
isRequiredForAction	({ mfaAction }: { mfaAction: MFAAction }) => Promise<boolean>	Checks if MFA is required for a specific action.
updateUserDevice	(deviceId: string) => Promise<void>	Updates an MFA device’s information.
verifyDevice	(code: string, type?: MFADeviceType) => Promise<MFADevice>	Verifies an MFA device using the provided code. Returns the verified device information.

networks module

Provides access to the current network configurations.

Property	Type	Description
evm	GenericNetwork[]	Which EVM networks are currently configured. See GenericNetwork
solana	GenericNetwork[]	Which Solana networks are currently configured. See GenericNetwork
sui	GenericNetwork[]	Which Sui networks are currently configured. See GenericNetwork

Event name	Type	Description
evmChanged	(evm: GenericNetwork[]) => void	State change event for the evm variable.
solanaChanged	(solana: GenericNetwork[]) => void	State change event for the solana variable.
suiChanged	(sui: GenericNetwork[]) => void	State change event for the sui variable.

sdk module

Gives insight over the state of the SDK.

Property	Type	Description
loaded	boolean	Whether the SDK has loaded and is ready to handle requests.
loadState	SdkWebViewLoadState	Live snapshot of the webview load engine (status, phase, attempt, maxAttempts, nextRetryAt, error). See Observing the load state.
retry	() => Promise<SdkWebViewLoadState>	Starts a fresh webview load cycle from a failed (or backoff-pending) state, resolving with the next terminal load state. A no-op elsewhere. See Retrying a failed load.

Event name	Type	Description
error	(error: Error | null) => void	Emitted when an error occurs.
loadedChanged	(loaded: boolean) => void	State change event for the loaded variable.
loadStateChanged	(loadState: SdkWebViewLoadState) => void	Emitted whenever the webview loadState changes.

ui module

Provides access to Dynamic’s UI.

Property	Type	Description
auth.show	() => void	Opens up Dynamic’s authentication flow modal for your user to sign in. Automatically closes when finished.
auth.hide	() => void	Hide the Dynamic’s authentication flow modal.
userProfile.show	() => void	Opens up Dynamic’s user profile modal, allowing your user to manage their profile and wallets.
userProfile.hide	() => void	Hide the Dynamic’s user profile modal
fundingOptions.show	() => void	Opens up Dynamic’s funding options modal, allowing your user to choose one of your app’s configured funding options to fund their account.
fundingOptions.hide	() => void	Hide the Dynamic’s funding options modal
updateUser.show	(params: UpdateUserWithModalParams) => Promise<UserFields>	Opens up Dynamic’s user update modal to collect profile information. Available from v4.38.0.
wallets.revealEmbeddedWalletKey	(params: { type: "recovery-phrase" | "private-key" }) => void	Opens up Dynamic’s export embedded wallet key flow for the primary wallet.

Event name	Type	Description
authFlowCancelled	() => void	Emitted when the user cancels the authentication flow (closes it before completing it).
authFlowClosed	() => void	Emitted when the authentication flow is closed, regardless of whether it was successfully completed or not.
authFlowOpened	() => void	Emitted when the authentication flow is opened.

wallets module

Provides access to the user’s wallets.

Property	Type	Description
userWallets	BaseWallet[]	The array of all the user’s wallets.
primary	BaseWallet | undefined	The primary wallet of the user.
setPrimary	(params: { walletId: string }) => Promise<void>	Sets primary wallet of the user.
getBalance	(params: { wallet: BaseWallet }) => Promise<{ balance: string }>	Returns the balance of a wallet.
getNetwork	(params: { wallet: BaseWallet }) => Promise<{ network: string | number }>	Returns the network the wallet is connected to.
signMessage	(params: { wallet: BaseWallet; message: string }) => Promise<{ signedMessage: string }>	Signs a message with this wallet.
switchNetwork	(params: { wallet: BaseWallet; chainId: string | number }) => Promise<void>	Switches the wallet’s network.
simulateEVMTransaction	(params: { transaction: IEVMTransaction; type: 'SignTransaction' | 'SendTransaction' }) => Promise<SimulateTransactionResponse>	Simulates an EVM transaction to preview effects before sending. Uses the primary wallet.
simulateEVMTransactionAA	(params: { transaction: IEVMTransaction; type: 'SignTransaction' | 'SendTransaction' }) => Promise<SimulateTransactionResponse>	Simulates an account abstraction transaction to preview effects before sending. Uses the primary wallet.
walletOptions	WalletOptionMetadata[]	Array of available wallet options that can be connected. Each option contains metadata about the wallet connector.
connectWallet	(connectorKey: string) => Promise<BaseWallet>	Connects to a specific wallet by its connector key. Returns the connected wallet.

Event name	Type	Description
messageSigned	(params: { messageToSign: string; signedMessage: string }) => void	Emitted when a message is signed.
walletAdded	(params: { wallet: BaseWallet; userWallets: BaseWallet[] }) => void	Emitted when a wallet is added to the userWallets variable.
walletRemoved	(params: { wallet: BaseWallet; userWallets: BaseWallet[] }) => void	Emitted when a wallet is removed from the userWallets variable.
primaryChanged	(primary: BaseWallet | null) => void	State change event for the primary variable.
userWalletsChanged	(userWallets: BaseWallet[]) => void	State change event for the userWallets variable.
walletOptionsChanged	(walletOptions: WalletOptionMetadata[]) => void	State change event for the walletOptions variable.

wallets.embedded submodule

Allows interacting with and creating an embedded wallet for the current user.

Property	Type	Description
hasWallet	boolean	Whether the logged in user has an embedded wallet.
getWallet	() => BaseWallet | null	Retrieves the embedded wallet of the current user, or null if it doesn’t exist.
createWallet	(params?: { chain?: "Evm" | "Sol" }) => BaseWallet	Creates an embedded wallet for the current user.

Event name	Type	Description
embeddedWalletCreated	(verifiedCredential: JwtVerifiedCredential | null) => void	Emitted when an embedded wallet is created.
hasWalletChanged	(hasWallet: boolean) => void	State change event for the hasWallet variable.

wallets.waas submodule

Provides advanced Wallet as a Service (WaaS) operations for secure key management and wallet operations. These methods are only available for Dynamic WaaS wallets.

WaaS operations require the wallet to be a Dynamic WaaS wallet (wallet.key === 'dynamicwaas').

Property	Type	Description
refreshWalletAccountShares	(walletId: string, params: { accountAddress: string; password?: string }) => Promise<void>	Refreshes the account shares for a WaaS wallet.
backupKeySharesToGoogleDrive	(walletId: string, params: { accountAddress: string; password?: string }) => Promise<void>	Backs up wallet key shares to Google Drive for secure recovery.
signRawMessage	(walletId: string, params: { accountAddress: string; message: string; password?: string }) => Promise<string>	Signs a raw message with the WaaS wallet. Message must be 64 characters.
updatePassword	(walletId: string, params: { accountAddress: string; existingPassword: string; newPassword: string }) => Promise<void>	Updates the password for a WaaS wallet.
importPrivateKey	(walletId: string, params: { privateKey: string; thresholdSignatureScheme: string }) => Promise<void>	Imports an existing private key into a WaaS wallet.

wallets.delegation submodule

Provides methods for managing wallet delegation, allowing secure server-side operations on behalf of users.

Learn more about delegated access.

Property	Type	Description
initDelegationProcess	(params: { walletIds?: string[] }) => Promise<void>	Initiates the delegation process for specified wallets or all user wallets.
shouldPromptWalletDelegation	() => Promise<boolean>	Checks if the user should be prompted for delegation.
getWalletsDelegatedStatus	() => Promise<BaseWalletWithStatus[]>	Returns delegation status for all user wallets.
delegateKeyShares	(params: { wallets?: { chainName: ChainEnum; accountAddress: string }[]; password?: string }) => Promise<void>	Delegates key shares for specific wallets with optional password encryption. See Password encryption.
revokeDelegation	(params: { wallets: { chainName: ChainEnum; accountAddress: string }[]; password?: string }) => Promise<void>	Revokes delegation for specific wallets. Requires password if wallet was delegated with one.
denyWalletDelegation	(params: { walletId: string }) => Promise<void>	Denies delegation for a specific wallet.
dismissDelegationPrompt	(params: { walletId?: string }) => Promise<void>	Dismisses the delegation prompt for a wallet.
clearDelegationSessionState	() => Promise<void>	Clears delegation session state.

Extendable class

An object that can be extended by calling its .extend method with an Extension.

To extend here means to add or replace the existing properties of this object, as well as kicking off any related procedures. Like a structure on which you can attach lego bricks.

Since our client extends this class, you are able to easily pick and choose exactly which features you will need, maximizing the control, simplicity and package size of your project.

Property	Type	Description
extend	<T>(extension: Extension<T>): T & typeof this	Allows you to extend the properties of the calling object and kick off related procedures.

Extension method

Extension<T>(extendable: Extendable, core: Core): T

A method that can be passed to the .extend method of an Extendable object to extend its properties and trigger related procedures.

We do not currently provide support on how to create your own custom extensions, though it can be achieved.

WalletOptionMetadata type

Metadata about an available wallet option that can be connected.

Property	Type	Description
key	string	Unique identifier for the wallet connector.
name	string	Display name of the wallet.
chain	string | null	The blockchain chain this wallet supports.
group	string | null	The group this wallet belongs to.
groupName	string | null	The display name of the group.
isInstalledOnBrowser	boolean	Whether this wallet is installed on the browser.
isWalletConnect	boolean	Whether this wallet uses WalletConnect.
metadata	WalletMetadata	Additional metadata about the wallet (icon, brand color, etc.).

WalletMetadata type

Metadata about a wallet’s branding and configuration.

Property	Type	Description
id	string	Identifier for the wallet.
name	string	The wallet name.
icon	string	URL or data for the wallet icon.
brandColor	string?	Hex value for the wallet brand color (e.g., #F6851B).
groupKey	string?	Key used to group wallets together.
inAppBrowserUrl	string?	URL to open the wallet in the in-app browser.
deepLinks	WalletDeepLinks?	Mobile deep links for the wallet.
downloadLinks	WalletDownloadLinks?	Links to download the wallet on various platforms.
rdns	string?	The wallet rdns if it supports EIP-6963.