## AI Use Cases
If you want to build AI applications using Dynamic, you're in good company! We already support the likes of [aixbt](https://aixbt.tech/), [CoDatta](https://codatta.io/) and [Mahojin](https://www.mahojin.ai/) among many more.
You can use our standard wallet connector to connect to your users' wallets and plug them into your AI applications client side, like [this example using GOAT and Eleven Labs](https://github.com/goat-sdk/goat/tree/main/typescript/examples/by-framework/eleven-labs).
You can also sign up for early access to agentic wallets when they are released:
# Integrating Dynamic using AI
Source: https://docs.dynamic.xyz/ai/developing-with-ai
AI can be a powerful tool for developers. We've set up Dynamic to seamlessly integrate with your AI assisted coding workflow. Here's how:
1. Add docs to Cursor: Simply follow [this tutorial](https://docs.cursor.com/context/@-symbols/@-docs#add-custom-docs) to add Dynamic's docs to Cursor, which you can then use as context in a request, just like any other file.
2. Add docs to LLM's via txt file: Dynamic supports the [llms.txt](https://docs.dynamic.xyz/llms.txt) and also has [llms-full.txt](https://docs.dynamic.xyz/llms-full.txt), read about those [here](https://github.com/AnswerDotAI/llms-txt). This means you can use Dynamic's docs as plain text context in any LLM that supports it, or in your own custom tooling.
3. Copy a single page from the docs: Every page has a "Copy page" button that you can use to view the page as markdown, copy the page as markdown, or ask Claude/ChatGPT to use the page as context.
# Create a new entry for an allowlist
Source: https://docs.dynamic.xyz/api-reference/allowlists/create-a-new-entry-for-an-allowlist
https://app.dynamic.xyz/api-docs/public-api.yaml post /allowlists/{allowlistId}/entries
# Create new allowlist for a environment
Source: https://docs.dynamic.xyz/api-reference/allowlists/create-new-allowlist-for-a-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/allowlists
# Delete an allowlist
Source: https://docs.dynamic.xyz/api-reference/allowlists/delete-an-allowlist
https://app.dynamic.xyz/api-docs/public-api.yaml delete /allowlists/{allowlistId}
# Delete an allowlist entry
Source: https://docs.dynamic.xyz/api-reference/allowlists/delete-an-allowlist-entry
https://app.dynamic.xyz/api-docs/public-api.yaml delete /allowlistEntries/{allowlistEntryId}
# Disable the allow list
Source: https://docs.dynamic.xyz/api-reference/allowlists/disable-the-allow-list
https://app.dynamic.xyz/api-docs/public-api.yaml put /allowlists/{allowlistId}/disable
# Enable the allowlist
Source: https://docs.dynamic.xyz/api-reference/allowlists/enable-the-allowlist
https://app.dynamic.xyz/api-docs/public-api.yaml put /allowlists/{allowlistId}/enable
# Get all allowlists for a environment
Source: https://docs.dynamic.xyz/api-reference/allowlists/get-all-allowlists-for-a-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/allowlists
# Get all entries for an allowlist
Source: https://docs.dynamic.xyz/api-reference/allowlists/get-all-entries-for-an-allowlist
https://app.dynamic.xyz/api-docs/public-api.yaml get /allowlists/{allowlistId}/entries
# Get allowlist by id
Source: https://docs.dynamic.xyz/api-reference/allowlists/get-allowlist-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /allowlists/{allowlistId}
# Update the outcome, scope, or name of an allowlist entry by ID
Source: https://docs.dynamic.xyz/api-reference/allowlists/update-the-outcome-scope-or-name-of-an-allowlist-entry-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml put /allowlists/{allowlistId}
# Get environments analyticsvisits
Source: https://docs.dynamic.xyz/api-reference/analytics/get-environments-analyticsvisits
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/analytics/visits
Fetch visit analytics
# Get environments analyticswallets
Source: https://docs.dynamic.xyz/api-reference/analytics/get-environments-analyticswallets
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/analytics/wallets
Fetch wallets breakdown
# Disables the Sanctions API
Source: https://docs.dynamic.xyz/api-reference/chainalysis/disables-the-sanctions-api
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/integrations/chainalysis/sanctions/disable
# Enable the Sanctions API
Source: https://docs.dynamic.xyz/api-reference/chainalysis/enable-the-sanctions-api
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/integrations/chainalysis/sanctions/enable
# Find the Chainalysis configuration for an environment.
Source: https://docs.dynamic.xyz/api-reference/chainalysis/find-the-chainalysis-configuration-for-an-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/integrations/chainalysis
# Get tokens for passed chainName.
Source: https://docs.dynamic.xyz/api-reference/chains/get-tokens-for-passed-chainname
https://app.dynamic.xyz/api-docs/public-api.yaml get /chains/{chainName}/tokens
# Create a new custom field for an environment
Source: https://docs.dynamic.xyz/api-reference/custom-fields/create-a-new-custom-field-for-an-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/custom/fields
# Delete a specific custom field by its ID
Source: https://docs.dynamic.xyz/api-reference/custom-fields/delete-a-specific-custom-field-by-its-id
https://app.dynamic.xyz/api-docs/public-api.yaml delete /custom/fields/{customFieldId}
# Get the custom fields for an environment
Source: https://docs.dynamic.xyz/api-reference/custom-fields/get-the-custom-fields-for-an-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/custom/fields
# Retrieve a specific custom field by its ID
Source: https://docs.dynamic.xyz/api-reference/custom-fields/retrieve-a-specific-custom-field-by-its-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /custom/fields/{customFieldId}
# Update an existing custom field by its ID
Source: https://docs.dynamic.xyz/api-reference/custom-fields/update-an-existing-custom-field-by-its-id
https://app.dynamic.xyz/api-docs/public-api.yaml put /custom/fields/{customFieldId}
# Create a custom network for an organization
Source: https://docs.dynamic.xyz/api-reference/custom-networks/create-a-custom-network-for-an-organization
https://app.dynamic.xyz/api-docs/public-api.yaml post /organizations/{organizationId}/customNetworks
# Delete a custom network
Source: https://docs.dynamic.xyz/api-reference/custom-networks/delete-a-custom-network
https://app.dynamic.xyz/api-docs/public-api.yaml delete /organizations/{organizationId}/customNetworks/{networkId}
# Get a specific custom network
Source: https://docs.dynamic.xyz/api-reference/custom-networks/get-a-specific-custom-network
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations/{organizationId}/customNetworks/{networkId}
# Get all custom networks for an organization
Source: https://docs.dynamic.xyz/api-reference/custom-networks/get-all-custom-networks-for-an-organization
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations/{organizationId}/customNetworks
# Update a custom network
Source: https://docs.dynamic.xyz/api-reference/custom-networks/update-a-custom-network
https://app.dynamic.xyz/api-docs/public-api.yaml put /organizations/{organizationId}/customNetworks/{networkId}
# Create a new custom hostname for this environment
Source: https://docs.dynamic.xyz/api-reference/customhostnames/create-a-new-custom-hostname-for-this-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/custom/hostnames
# Delete the custom hostname
Source: https://docs.dynamic.xyz/api-reference/customhostnames/delete-the-custom-hostname
https://app.dynamic.xyz/api-docs/public-api.yaml delete /environments/{environmentId}/custom/hostnames/{customHostnameId}
# Get the custom hostnames for this environemnt
Source: https://docs.dynamic.xyz/api-reference/customhostnames/get-the-custom-hostnames-for-this-environemnt
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/custom/hostnames
# Delete a mobile deeplink URL by id
Source: https://docs.dynamic.xyz/api-reference/deeplinkurls/delete-a-mobile-deeplink-url-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml delete /deeplinkUrls/{deeplinkUrlId}
# Get all the whitelisted mobile deeplink URLs for a project environment
Source: https://docs.dynamic.xyz/api-reference/deeplinkurls/get-all-the-whitelisted-mobile-deeplink-urls-for-a-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/deeplinkUrls
# Whitelists a mobile deeplink URL for this project environment
Source: https://docs.dynamic.xyz/api-reference/deeplinkurls/whitelists-a-mobile-deeplink-url-for-this-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/deeplinkUrls
# Find an environment by ID
Source: https://docs.dynamic.xyz/api-reference/environments/find-an-environment-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}
# Get keys for an environment given environmentId
Source: https://docs.dynamic.xyz/api-reference/environments/get-keys-for-an-environment-given-environmentid
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/keys
# Get Live and Sandbox environments by projectId
Source: https://docs.dynamic.xyz/api-reference/environments/get-live-and-sandbox-environments-by-projectid
https://app.dynamic.xyz/api-docs/public-api.yaml get /projects/{projectId}/environments
# Get the unique number of visitors for an environment by environment ID
Source: https://docs.dynamic.xyz/api-reference/environments/get-the-unique-number-of-visitors-for-an-environment-by-environment-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/statistics/visitors
# Updates the environment settings
Source: https://docs.dynamic.xyz/api-reference/environments/updates-the-environment-settings
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}
# Get environment events
Source: https://docs.dynamic.xyz/api-reference/events/get-environment-events
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/events
# Get event types
Source: https://docs.dynamic.xyz/api-reference/events/get-event-types
https://app.dynamic.xyz/api-docs/public-api.yaml get /eventTypes
# Create a new export request for the project environment
Source: https://docs.dynamic.xyz/api-reference/exports/create-a-new-export-request-for-the-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/exports
# Download an export by ID
Source: https://docs.dynamic.xyz/api-reference/exports/download-an-export-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/exports/{exportId}/download
# Get an export using the ID
Source: https://docs.dynamic.xyz/api-reference/exports/get-an-export-using-the-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/exports/{exportId}
# Get the exports for an environment
Source: https://docs.dynamic.xyz/api-reference/exports/get-the-exports-for-an-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/exports
# Check if the external provided JWT is valid for the specified environment
Source: https://docs.dynamic.xyz/api-reference/externaljwt/check-if-the-external-provided-jwt-is-valid-for-the-specified-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/externalJwt/check
# Creates a new gate for the project environment
Source: https://docs.dynamic.xyz/api-reference/gates/creates-a-new-gate-for-the-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/gates
# Delete a gate
Source: https://docs.dynamic.xyz/api-reference/gates/delete-a-gate
https://app.dynamic.xyz/api-docs/public-api.yaml delete /environments/{environmentId}/gates/{gateId}
# Disable the gate for the environment
Source: https://docs.dynamic.xyz/api-reference/gates/disable-the-gate-for-the-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/gates/{gateId}/disable
# Enable the gate for the environment
Source: https://docs.dynamic.xyz/api-reference/gates/enable-the-gate-for-the-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/gates/{gateId}/enable
# Get the gates for an environment
Source: https://docs.dynamic.xyz/api-reference/gates/get-the-gates-for-an-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/gates
# Gets a gate
Source: https://docs.dynamic.xyz/api-reference/gates/gets-a-gate
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/gates/{gateId}
# Updates a gate
Source: https://docs.dynamic.xyz/api-reference/gates/updates-a-gate
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/gates/{gateId}
# Adds a domain to be allowed or blocked for global wallet access for this project environment
Source: https://docs.dynamic.xyz/api-reference/globalwalletaccesscontrol/adds-a-domain-to-be-allowed-or-blocked-for-global-wallet-access-for-this-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/globalWallet/accessControl/domains
# Creates a global wallet access control for this project environment
Source: https://docs.dynamic.xyz/api-reference/globalwalletaccesscontrol/creates-a-global-wallet-access-control-for-this-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/globalWallet/accessControl
# Delete a global wallet access control domain by id
Source: https://docs.dynamic.xyz/api-reference/globalwalletaccesscontrol/delete-a-global-wallet-access-control-domain-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml delete /environments/{environmentId}/globalWallet/accessControl/domains/{globalWalletAccessControlDomainId}
# Disabled global wallet access control for this environment
Source: https://docs.dynamic.xyz/api-reference/globalwalletaccesscontrol/disabled-global-wallet-access-control-for-this-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/globalWallet/accessControl/disable
# Enable global wallet access control for this environment
Source: https://docs.dynamic.xyz/api-reference/globalwalletaccesscontrol/enable-global-wallet-access-control-for-this-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/globalWallet/accessControl/enable
# Get all the global wallet access control domains for a project environment
Source: https://docs.dynamic.xyz/api-reference/globalwalletaccesscontrol/get-all-the-global-wallet-access-control-domains-for-a-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/globalWallet/accessControl
# Updates a global wallet access control for this project environment
Source: https://docs.dynamic.xyz/api-reference/globalwalletaccesscontrol/updates-a-global-wallet-access-control-for-this-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/globalWallet/accessControl
# Creates the global wallet settings for the environment
Source: https://docs.dynamic.xyz/api-reference/globalwallets/creates-the-global-wallet-settings-for-the-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/globalWallet/settings
# Disabled global wallet for this environment
Source: https://docs.dynamic.xyz/api-reference/globalwallets/disabled-global-wallet-for-this-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/globalWallet/disable
# Enable global wallet for this environment
Source: https://docs.dynamic.xyz/api-reference/globalwallets/enable-global-wallet-for-this-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/globalWallet/enable
# Get the global wallet settings for environment
Source: https://docs.dynamic.xyz/api-reference/globalwallets/get-the-global-wallet-settings-for-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/globalWallet/settings
# Updates the global wallet settings for the environment
Source: https://docs.dynamic.xyz/api-reference/globalwallets/updates-the-global-wallet-settings-for-the-environment
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/globalWallet/settings
# Creates an invite to the organization
Source: https://docs.dynamic.xyz/api-reference/invites/creates-an-invite-to-the-organization
https://app.dynamic.xyz/api-docs/public-api.yaml post /organizations/{organizationId}/invites
# Delete invite for user
Source: https://docs.dynamic.xyz/api-reference/invites/delete-invite-for-user
https://app.dynamic.xyz/api-docs/public-api.yaml delete /invites/{inviteId}
# Fetches all the Invites the belong to the organization
Source: https://docs.dynamic.xyz/api-reference/invites/fetches-all-the-invites-the-belong-to-the-organization
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations/{organizationId}/invites
# Get all the user invites
Source: https://docs.dynamic.xyz/api-reference/invites/get-all-the-user-invites
https://app.dynamic.xyz/api-docs/public-api.yaml get /invites
# Update invite for user (accept/reject)
Source: https://docs.dynamic.xyz/api-reference/invites/update-invite-for-user-acceptreject
https://app.dynamic.xyz/api-docs/public-api.yaml put /invites/{inviteId}
# Delete user membership from being an admin of an organization
Source: https://docs.dynamic.xyz/api-reference/members/delete-user-membership-from-being-an-admin-of-an-organization
https://app.dynamic.xyz/api-docs/public-api.yaml delete /members/{memberId}
# Get all users that are admins for an organization
Source: https://docs.dynamic.xyz/api-reference/members/get-all-users-that-are-admins-for-an-organization
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations/{organizationId}/members
# Get Membership Environment IDs
Source: https://docs.dynamic.xyz/api-reference/members/get-membership-environment-ids
https://app.dynamic.xyz/api-docs/public-api.yaml get /membershipEnvironmentIds
Retrieve the list of project environments that the user is a member of.
# Update a given members role
Source: https://docs.dynamic.xyz/api-reference/members/update-a-given-members-role
https://app.dynamic.xyz/api-docs/public-api.yaml put /members/{memberId}
# Delete all MFA Devices for the user
Source: https://docs.dynamic.xyz/api-reference/mfa/delete-all-mfa-devices-for-the-user
https://app.dynamic.xyz/api-docs/public-api.yaml delete /users/{userId}/mfa
# Disable the given mfa device for the organization
Source: https://docs.dynamic.xyz/api-reference/mfasettings/disable-the-given-mfa-device-for-the-organization
https://app.dynamic.xyz/api-docs/public-api.yaml put /organizations/{organizationId}/mfaSettings/{mfaDeviceType}/disable
# Enable the given mfa device for the organization
Source: https://docs.dynamic.xyz/api-reference/mfasettings/enable-the-given-mfa-device-for-the-organization
https://app.dynamic.xyz/api-docs/public-api.yaml put /organizations/{organizationId}/mfaSettings/{mfaDeviceType}/enable
# Get all mfa settings for an organization
Source: https://docs.dynamic.xyz/api-reference/mfasettings/get-all-mfa-settings-for-an-organization
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations/{organizationId}/mfaSettings
# Create a new name service for the environment and chain
Source: https://docs.dynamic.xyz/api-reference/nameservices/create-a-new-name-service-for-the-environment-and-chain
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/nameService/{chainName}
# delete the name service for the environment and chain
Source: https://docs.dynamic.xyz/api-reference/nameservices/delete-the-name-service-for-the-environment-and-chain
https://app.dynamic.xyz/api-docs/public-api.yaml delete /environments/{environmentId}/nameService/{chainName}
# Disabled name service for this environment and chain
Source: https://docs.dynamic.xyz/api-reference/nameservices/disabled-name-service-for-this-environment-and-chain
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/nameService/{chainName}/disable
# Enable name service for this environment and chain
Source: https://docs.dynamic.xyz/api-reference/nameservices/enable-name-service-for-this-environment-and-chain
https://app.dynamic.xyz/api-docs/public-api.yaml put /environments/{environmentId}/nameService/{chainName}/enable
# Get the name service for the environment and chain
Source: https://docs.dynamic.xyz/api-reference/nameservices/get-the-name-service-for-the-environment-and-chain
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/nameService/{chainName}
# Get the unsigned chain-specific message needed to be signed by the wallet owner using the wallet private key
Source: https://docs.dynamic.xyz/api-reference/nameservices/get-the-unsigned-chain-specific-message-needed-to-be-signed-by-the-wallet-owner-using-the-wallet-private-key
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/nameService/{chainName}/signingMessage
# Add coupon to subscription
Source: https://docs.dynamic.xyz/api-reference/organizations/add-coupon-to-subscription
https://app.dynamic.xyz/api-docs/public-api.yaml put /organizations/{organizationId}/billing/subscription/coupon
# Creates organization
Source: https://docs.dynamic.xyz/api-reference/organizations/creates-organization
https://app.dynamic.xyz/api-docs/public-api.yaml post /organizations
# Fetches all the active organizations that the user has access to
Source: https://docs.dynamic.xyz/api-reference/organizations/fetches-all-the-active-organizations-that-the-user-has-access-to
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations
# Find an organization by ID
Source: https://docs.dynamic.xyz/api-reference/organizations/find-an-organization-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations/{organizationId}
# Find the subscription of an organization using its ID
Source: https://docs.dynamic.xyz/api-reference/organizations/find-the-subscription-of-an-organization-using-its-id
https://app.dynamic.xyz/api-docs/public-api.yaml get /organizations/{organizationId}/billing/subscription
# Update an organization by ID
Source: https://docs.dynamic.xyz/api-reference/organizations/update-an-organization-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml put /organizations/{organizationId}
# Upgrade organziation to advanced plan
Source: https://docs.dynamic.xyz/api-reference/organizations/upgrade-organziation-to-advanced-plan
https://app.dynamic.xyz/api-docs/public-api.yaml put /organizations/{organizationId}/billing/upgrade
# Adds an allowed origin for this project environment
Source: https://docs.dynamic.xyz/api-reference/origins/adds-an-allowed-origin-for-this-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml post /environments/{environmentId}/origins
# Delete a origin by id
Source: https://docs.dynamic.xyz/api-reference/origins/delete-a-origin-by-id
https://app.dynamic.xyz/api-docs/public-api.yaml delete /origins/{originId}
# Get all the allowed origins for a project environment
Source: https://docs.dynamic.xyz/api-reference/origins/get-all-the-allowed-origins-for-a-project-environment
https://app.dynamic.xyz/api-docs/public-api.yaml get /environments/{environmentId}/origins
# Introduction
Source: https://docs.dynamic.xyz/api-reference/overview
## Introduction
Dynamic provides a robust API that allows developers to securely access their
dashboard environment's data and programmatically update settings relevant to
their Dynamic-powered application.
## Authentication
All APIs in this section require a bearer token used to authenticate requests
and make sure the caller is authorized to access the resources in the requests.
Please follow these steps:
#### Get an API token from Dashboard
1. Go to the your environment's dashboard
[Developer Tab](https://app.dynamic.xyz/dashboard/developer/api)
2. In the "API Token" section, click on "Create Token"
3. Provide a name for the token. The best practice here would be to name the
token after the system you intend to use this token with. A few examples:
"Mycompany Admin", "Ben's personal token", or "background-job service".
4. **Make sure to copy the API token** before closing the modal. This is the
last time you will have access to the plaintext API token! Dynamic DOES NOT
have access to the plaintext API token anywhere. If you lose this API token,
you will need to create a new one.
5. The token should start with the prefix `dyn_` followed by 56 alphanumeric
characters.
#### Using the API token
Use the token generated through dashboard to programmatically access Dynamic's
API by adding it to the `Authentication` header of your HTTP request.
Example:
```bash curl
curl \
--location 'https://app.dynamic.xyz/api/v0/environments/<
By default, you can use Dynamics credentials to send SMS messages to your users. However, if you want to send beyond US & Canada, you will need to set up your own Twilio account. In order to do this, you toggle off "Use Dynamic's credentials" and a section will open up for you, where you can enter your own credentials.
## SMS & Embedded Wallets
When you enable SMS sign-up, you can also enable embedded wallets for your users. This means that when a user signs up with their phone number, they will also receive a wallet that they can use to interact with your application.
In order to ensure your end users are adequately protected against attacks like sim swaps, we highly encourage you to [enable account MFA (TOTP) via Google Authenticator](/authentication-methods/mfa).
Next we'll need to let the user change between languages, and it's as simple as the following:
```tsx
const {locale} = useDynamicContext();
const handleOnClick = (localeProvided) => {
if (localeProvided === 'it') {
locale.changeLanguage('it');
} else {
locale.changeLanguage('en');
}
};
return (
);
```
That's it! You now know how to customize the text in the SDK to your heart's content.
## Further Reading
Make sure to check out the full reference for the locale object [here](/react-sdk/objects/locale).
# UI Customization Overview
Source: https://docs.dynamic.xyz/design-customizations/customizing-ui
| 
|
Let's create a button that, when clicked, will automatically open the Ethereum tab.
```tsx
import React from "react";
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
/**
* Component for a button that opens the Ethereum tab by default.
*/
const ConnectWithEthereum: React.FC = () => {
const { setShowAuthFlow, setSelectedTabIndex } = useDynamicContext();
/**
* Handles the button click event by setting the default tab to Ethereum and showing the authentication flow.
*/
const onClickHandler = (): void => {
setSelectedTabIndex(1); // Set the selected tab index to 1, which corresponds to the Ethereum tab
setShowAuthFlow(true);
};
return ;
};
export default ConnectWithEthereum;
```
# Adapt UI With Views
Source: https://docs.dynamic.xyz/design-customizations/views
## What is it?
Views are used to customize the kind of UI that shows up at any point in time in your application, specifically giving you complete control over the signup/login options you show your user.
## How does it work?
Views are used primarily in the overrides prop of the [DynamicContextProvider](/react-sdk/providers/dynamiccontextprovider). You pass in an array of configurations for each view you want to customize, each view has its own set of options.
## Types of Views
### Authentication Method Options (Login)
The `SdkViewType.Login` is used to adjust the login/signup UI options programmatically.
When using the login view, you add an object to the views array. This object should have `type: SdkViewType.Login` and `sections` which is an array of SdkViewSection objects.
### SdkViewSection structure
1. Click "Create new project"
2. Enter Project Name.
## Organizations
Organizations are a way to group projects together. Organizations are billed distinctly, and each organization can have multiple projects.
### Creating a new organization
In the navigation bar, click on the Organization dropdown menu (first on the left):
1. Click "Create organization" at the bottom of the dropdown
2. Enter Organization Name and Website URL
And you're done. You now have a new organization that you can use. You will need
to invite members of your team to this organization if you would like to work
with them there.
# Rate Limits
Source: https://docs.dynamic.xyz/developer-dashboard/rate-limits
Dynamic rate limit policies
Dynamic enforces rate limits based upon IP address, project environment, and certain endpoints to protect against attacks and to prevent abuse of Dynamic's platform. These limits are subject to change.
## Errors
Requests returning a `429` status code have been rate limited.
```json
{
"message": "Rate limit exceeded",
"code": 429
}
```
## Rate limit categories
* IP-based rate limits
* Project environment-based rate limits
* Endpoint-based rate limits
## SDK rate limits
All endpoints used by the SDK prefixed by `/sdk` are subject to the following limits.
* 100 requests per minute per IP
* 10000 requests per minute per project environment
### Endpoints
| Endpoint | Paths | Limited by | Rate Limit |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------ |
| Nonce | /:environmentId/nonce | IP Address | 10 requests per 1 minute |
| Connect | /:environmentId/connect | IP Address | 10 requests per 1 minute |
| Signin | /:environmentId/verify/:environmentId/emailVerifications/signin
/:environmentId/smsVerifications/signin
/:environmentId/providers/:providerType/signin
/:environmentId/telegram/signin
/:environmentId/farcaster/signin
/:environmentId/externalAuth/signin | IP Address | 10 requests per 1 minute | | OTP | /:environmentId/emailVerifications/create
/:environmentId/emailVerifications/retry
/:environmentId/smsVerifications/create
/:environmentId/smsVerifications/retry | IP Address | 10 requests per 1 minute | | MFA | /:environmentId/users/mfa/register/totp
/:environmentId/users/mfa/auth/totp
/:environmentId/users/mfa/register/passkey
/:environmentId/users/mfa/auth/passkey
/:environmentId/users/mfa/recovery
/:environmentId/users/mfa/auth/recovery | IP Address | 5 requests per 1 minute | | Token balances | /:environmentId/chains/:chainName/balances | IP Address | 20 requests per 1 minute | | Embedded wallets | /:environmentId/users/embeddedWallets
/:environmentId/users/embeddedWallets/walletAccounts
/:environmentId/users/embeddedWallets/sessionKey | IP Address | 20 requests per 1 minute | | Update user | /:environmentId/users | IP Address | 5 requests per 1 minute | | Delete user | /:environmentId/users | IP Address | 2 requests per 1 minute | ## Developer rate limits All endpoints used by Developers are subject to the following rate limits. * 1500 requests per minute per IP * 3000 requests per minute per project environment ### Endpoints | Endpoint | Path | Limited by | Rate Limit | | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------- | | Bulk create user | /environments/:environmentId/users/bulk | IP Address | 150 requests per 1 minute | | Create embedded wallet | /environments/:environmentId/users/embeddedWallets
/environments/:environmentId/users/embeddedWallets/farcaster | IP Address | 300 requests per 1 minute | | Organization invites | /organizations/:organizationId/invites | IP Address | 20 requests per 1 minute | ## Webhooks See [webhooks limits](/developer-dashboard/webhooks#limits) for more information. # Sandbox vs Live Source: https://docs.dynamic.xyz/developer-dashboard/sandbox-vs-live Every project you create in Dynamic comes with a Sandbox and a Live environment. Both these environments behave similarly but we've customized the Sandbox environment to make it ideal for testing and exploring features. ### Two Key Differences 1. **Everything is free**: all Dynamic features on Sandbox are free. Whether you choose to upgrade to our Advanced tier or not, all the features that we offer will be available for you to test and explore. 2. **Sandbox is limited to 100 users**: your Sandbox environment is intended to help you test configurations and features and is not intended to be live on your site. We therefore have limited Sandbox to 100 users. After 100 users, you will not be able to authenticate new wallets unless you delete users.
# Security Settings
Source: https://docs.dynamic.xyz/developer-dashboard/security
We take security seriously at Dynamic and most of the work we do is behind the scenes so you don't have to worry about it. We will surface some security features that can be configured.
Today, we have 2 features that you can configure
1. CORS origin urls
2. JWT expiration time
### Allowed CORS Origin
Adding origins for
[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to your project
environment (sandbox and live) protects your environment from unauthorized
websites using your public environment key.
Any origins added to an environment will allow only those domains to make API
requests via our SDK.
# SDK and API Keys
Source: https://docs.dynamic.xyz/developer-dashboard/tokens-api-keys
This page hosts the keys that you'll need to setup the SDK, validate the JWT, and generate tokens for API usage.
To access this page, navigate to the
[developer](https://app.dynamic.xyz/dashboard/developer/api) page in your
dashboard.
#### Environment ID
The environment ID is the key used for our platform to identify your SDK and
associate the users to your project environment. Each project has 2 keys, one
for Sandbox and one for Live. Whenever you want to setup a new instance of the
SDK, you simply need to copy the Environment ID and copy it into the settings
prop in the SDK.
```ts TypeScript
import {
DynamicContextProvider,
DynamicWidget,
} from "@dynamic-labs/sdk-react-core";
const App = () => (
Whether you need React, React Native or Next.js, whether you want to use Ethers or Viem, whether you want to use Wagmi or not, we've got you covered. Simply run
```Create Dynamic App
npx create-dynamic-app@latest
```
and follow the prompts!
# Dynamic Package
Source: https://docs.dynamic.xyz/flutter/client
* User is blocked in Dynamic SDK:
**Add scope for users `jwt` when having specific NFT**
Gate setup:
* User needs to have specific NFT to have `admin` scope
* User has an `admin` scope added to the `jwt`
```Text json
{
...
"scope": "admin",
...
}
```
### Working with scopes
To simplify working with scopes, we created a custom hook named `useDynamicScopes`. It allows checking for users scopes and checking if one or many of them are in users `jwt` token. Check the docs [here](/react-sdk/hooks/usedynamicscopes).
# Create Your Own Global Wallet Package
Source: https://docs.dynamic.xyz/global-wallets/create-your-own-package
# Overview
This enables developers to embed your global wallet into their applications. Dynamic Global Wallet supports both EIP-6963 and Solana Wallet Standard - and works in Rainbowkit, Family, and other wallet provider implementations.
The global wallet uses pop ups and encrypted messaging to handle actions like connecting, signing, and transactions. The wallet can be used with AA to sponsor gas and perform additional policy-related activities
- [CSS Variables](/design-customizations/css/css-variables)
- [Custom CSS](/design-customizations/css/custom-css)
3. Click "Verify and Continue" and sign the message from Namestone to verify your domain. Make sure that
your primary wallet (in the top right corner of the dashboard) is the wallet associated with your domain.
4. Once your domain is verified, you can close the drawer and click "Save" to enable personalized subdomains.
### Require Subdomains
The require subdomains toggle will ask your users to choose a subdomain when they sign up or register with a new wallet.
## Choosing subdomains
Users can view and change their subdomain in the Profile section of the DynamicWidget:
{Droplet.wallets.map(wallet => {
const provider = createEIP1193Provider(wallet);
const walletClient = createWalletClient({
account: wallet.address as Hex,
transport: custom(provider)
});
return (
)
})}
)
}
```
## Provider Integration
### Viem Integration
```ts
import Droplet from 'droplet-wallet';
import { createWalletClient, custom, Hex } from 'viem';
const provider = createEIP1193Provider(wallet);
const walletClient = createWalletClient({
account: wallet.address as Hex,
transport: custom(provider)
});
```
### Ethers.js Integration
```ts
import Droplet from 'droplet-wallet';
import { ethers } from 'ethers';
const provider = createEIP1193Provider(wallet);
const ethersProvider = new ethers.BrowserProvider(provider);
```
## API Reference
### Core Methods
#### `connect`
Connects the global wallet to your dapp via a pop-up interface.
```ts
import Wallet, { connect } from 'wallet';
const connectedWallets = await connect(Wallet);
```
**Parameters:**
* `client`: GlobalWalletClient – The global wallet client instance
**Returns:**
* `Promise
## Security
When users connect to third-party websites and initiate transactions, Dynamic automatically interacts with the Blockaid API ([www.blockaid.io](http://www.blockaid.io)) to run transaction simulations and verify that the associated URLs are safe and not malicious.
Please be aware that this feature has usage limits, and additional charges may apply for higher-volume usage. For details on scaling and pricing, please contact our support team.
## FAQ
### Headless and hooks support
Currently, global connectivity is not supported in headless mode or with hooks.
### Safety practices
For best safety practices, please refer to our security section above. In general:
* Educate users to check which web3 apps they connect to.
* Dynamic will be rolling out new integrations to warn users if they attempt to connect to malicious dApps in the near future.
### Using Account Abstraction with global wallets
Account Abstraction is compatible with global wallets. If using gas sponsorship, you should whitelist your own dApps/contracts. For more information, see our [Smart Wallets documentation](/smart-wallets/add-smart-wallets).
### What is a URI code?
A URI (Uniform Resource Identifier) code in the context of WalletConnect is a string that contains all the necessary information for a wallet to establish a connection with a dApp.
### Compatibility with other chains
Currently, global connectivity only work on EVM chains. Solana support may come in the future as more dApps support WalletConnect with Solana.
# Web3 Wallet Libraries
Source: https://docs.dynamic.xyz/global-wallets/web3-libraries
## RainbowKit
You can guide your partners to add your wallet as a recommended wallet in their app. To do so, they will create a custom connector, as described below, which will should your wallet. When clicked, the wallet will render a QR code, which will work with Dynamic's [QR scanning](/global-wallets/qr-scanning) feature.
### Step 1: Import `connectorsForWallets` and `getWalletConnectConnector`
```javascript
import { RainbowKitProvider, connectorsForWallets, Wallet, getWalletConnectConnector, darkTheme } from '@rainbow-me/rainbowkit';
```
### Step 2: Create a custom connector
```javascript
export interface MyWalletOptions {
projectId: string;
}
export const legionkey = ({ projectId }: MyWalletOptions): Wallet => ({
id: 'legion-key',
name: 'LegionKey',
iconUrl: './images/legion-key.png',
iconBackground: '#985d3c',
mobile: {
getUri: (uri: string) => uri,
},
qrCode: {
getUri: (uri: string) => uri,
instructions: {
learnMoreUrl: 'https://my-wallet/learn-more',
steps: [
{
description:
'We recommend putting My Wallet on your home screen for faster access to your wallet.',
step: 'install',
title: 'Open the My Wallet app',
},
{
description:
'After you scan, a connection prompt will appear for you to connect your wallet.',
step: 'scan',
title: 'Tap the scan button',
},
],
},
},
extension: {
instructions: {
learnMoreUrl: 'https://my-wallet/learn-more',
steps: [
{
description:
'We recommend pinning My Wallet to your taskbar for quicker access to your wallet.',
step: 'install',
title: 'Install the My Wallet extension',
},
{
description:
'Be sure to back up your wallet using a secure method. Never share your secret phrase with anyone.',
step: 'create',
title: 'Create or Import a Wallet',
},
{
description:
'Once you set up your wallet, click below to refresh the browser and load up the extension.',
step: 'refresh',
title: 'Refresh your browser',
},
],
},
},
createConnector: getWalletConnectConnector({ projectId }),
});
```
### Step 3: Config the connectors
```javascript
const connectors = connectorsForWallets(
[
{
groupName: 'Recommended',
wallets: [legionkey],
},
{
groupName: 'Common',
wallets: [rainbowWallet, walletConnectWallet],
},
],
{
appName: 'My RainbowKit App',
projectId: 'YOUR_PROJECT_ID',
}
);
```
### Step 4: Add to the Rainbowkit Configuration
```javascript
const config = createConfig({
connectors,
...
});
```
## ReOwn AppKit (formally WalletConnect)
To integrate ReOwn AppKit (formally WalletConnect), follow these steps to submit your wallet as an official wallet into the ReOwn ecosystem:
### Step 1: Create an account on reown.com
* Visit [reown.com](https://reown.com) and sign up for a new account if you don't already have one.
* Verify your email address and complete the account setup process.
### Step 2: Create a new walletKit project
* Log in to your ReOwn account.
* Navigate to the dashboard and look for the option to create a new walletKit project.
* Fill in the required information about your wallet, including its name, description, and supported networks.
### Step 3: Submit your wallet for review
* Once your walletKit project is set up, you'll need to submit your wallet for review.
* Provide all necessary documentation, including your wallet's features, security measures, and any other relevant information.
* Ensure that your wallet meets all of ReOwn's guidelines and requirements for official wallets.
### Step 4: Once approved, it will show up in any AppKit list
* After submission, the ReOwn team will review your wallet.
* When approved, your wallet will be added to the official ReOwn ecosystem.
* It will then appear in AppKit lists, making it easily discoverable for users across various dApps that implement ReOwn AppKit.
* Edit the WalletKit project ID in the Dynamic Dashboard [here](https://app.dynamic.xyz/dashboard/log-in-user-profile/#walletconnect).
By following these steps, you'll integrate your wallet with ReOwn AppKit, increasing its visibility and accessibility within the ReOwn ecosystem.
# Go Live Checklist
Source: https://docs.dynamic.xyz/go-live-checklist
{status === "initial" && !error ? (
Create Dynamic-powered embedded wallets
) : newWallets && newWallets.length > 0 ? (
newWallets.map((wallet, index) => (
{wallet}
))
) : (
No wallets created yet or an error occurred.
)}
## Introduction to Farcaster
[Farcaster](https://www.farcaster.xyz/) is a protocol for building sufficiently decentralized social networks. Clients (such as [Warpcast](https://warpcast.com/)) build on top of Farcaster to provide the user interface and user experience for interacting with the decentralized network.
This is a beautiful relationship because the underlying social graph is shared by all the clients. This means that users can switch between clients without losing their social graph. It also means that clients can be built by different teams, each focusing on different aspects of the user experience.
Farcaster is not a blockchain. It is a protocol that stores the social graph on a blockchain, currently Optimism. If you're wondering what exactly it means when Farcaster defines itself as "sufficiently decentralized", Varun Srinivasan, one of the co-founders of Farcaster [describes it as](https://www.varunsrinivasan.com/2022/01/11/sufficient-decentralization-for-social-networks):
"A social network achieves sufficient decentralization if two users can find each other and communicate, even if the rest of the network wants to prevent it. This implies that users can always reach their audience, which can only be true if developers can build many clients on the network. If only one client existed, it could stop users from communicating. Achieving this only requires three decentralized features: the ability to claim a unique username, post messages under that name, and read messages from any valid name."
Due to this decentralized and permissionless nature, Farcaster has been able to introduce a number of features that are not possible in traditional social networks, one being Frames which you can think of as "mini-apps". For example, you can purchase items directly from your social media feed or tip creators directly from your feed.
## Farcaster + Dynamic
Our mission is to create incredible onboarding experiences for anyone interacting with Web3. We believe that Farcaster is a key piece of the Web3 puzzle, and we are excited to be working with the Farcaster team to bring the best possible onboarding experience to users of Farcaster. You can do this in a number of different ways:
### Sign in with Farcaster
If you want to allow your users to sign into a dapp using their Farcaster identity, similar to how you would with Google or other, this is as easy as a toggle in the dashboard. You can learn about that [here](/guides/integrations/farcaster/sign-in-with-farcaster).
### Enable Write Access
You may want to create certain actions in Farcaster on behalf of your users. For example, you may want to post a message on their behalf. For this you will need your user to go through a write access flow, and you can learn about how to do that [here](/guides/integrations/farcaster/farcaster-write-access).
### Wallets in Frames
If you are building a Frame and want to allow users to interact in a way that requires a wallet, you can generate a wallet from just an email address on multiple chains. You can learn about that [here](/guides/integrations/farcaster/embedded-wallet-frame).
# Enable Write Access to Farcaster
Source: https://docs.dynamic.xyz/guides/integrations/farcaster/farcaster-write-access
## Introduction
This tutorial will help you enable Sign in with Farcaster in your application, as well as enabling write access to Farcaster on behalf of that user.
We've partnered with the wonderful team at Neynar on this use case who have implemented Dynamic as part of Sign in with Neynar. This means three things for you:
* it's completely plug and play, drop in the code snippet and ship
* warps are already sponsored by Neynar
* you get the best of Dynamic and Neynar in one go
## Video walkthrough
## Live demo
You can see this flow in action on the Neynar demo: [https://demo.neynar.com/](https://demo.neynar.com/). You can find the code for this demo [here](https://github.com/neynarxyz/farcaster-examples/tree/main/wownar).
## Step By Step Walkthrough
{primaryWallet && (
Error: {error}
)}
);
}
export default App
```
# How to Use Dynamic in a Safe App
Source: https://docs.dynamic.xyz/guides/integrations/safe-app
{txHash && (
)}
{error && (
Transaction Hash:
{`${txHash.slice(0, 6)}...${txHash.slice(-4)}`}
(View on Explorer)
)}
Option 2.
Use this public shared key to test it out: [https://rpc.shield3.com/v3/UlihwLJtYY9bWgkuLA6KS6liL6iTpXKqhWvPBl80/0x01/rpc](https://rpc.shield3.com/v3/UlihwLJtYY9bWgkuLA6KS6liL6iTpXKqhWvPBl80/0x01/rpc)
### Step 2 - Change the RPC URL
On the Dynamic.xyz dashboard go to [the EVM Configuration tab](https://app.dynamic.xyz/dashboard/configurations#evm).
Toggle on Ethereum Mainnet, then click the down arrow on the far right.
The section will expand to show you the current RPC URL used and you can paste in the RPC URL you received in step 1 here.
### Step 3 - Test it out!
You can now run your Dynamic Implementation normally and send a transaction while connected to Ethereum.
1 - Unverified Contracts (Block | Flag | Alert)
If enabled, interactions with unverified contracts that cannot be decoded are forbidden. User can configure this policy to result in block, flag for MFA, or permit with an alert.
2 - OFAC SDN Block Native and ERC20 Transactions
Block native transfers, ERC20 transfers, and ERC20 approvals to OFAC addresses. As part of its enforcement efforts, OFAC publishes a list of individuals and companies owned or controlled by, or acting for or on behalf of, targeted countries. It also lists individuals, groups, and entities, such as terrorists and narcotics traffickers designated under programs that are not country-specific. Collectively, such individuals and companies are called “Specially Designated Nationals” or “SDNs.” Their assets are blocked and U.S. persons are generally prohibited from dealing with them.
3 - Native Transfers Spending Limits (Block | MFA)
If enabled, transactions with native values (ex. ETH) over a customizable threshold are forbidden. Users can configure this policy to result in a block, or flag for MFA.
4 - ERC20 Stablecoin Transfers Spending Limits (Block | MFA)
If enabled, transfers and approvals with verified stablecoins (ex. USDC, DAI, USDT) over a customizable threshold are forbidden. Users can configure this policy to result in a block, or flag for MFA.
5 - DEX Token Swap Protection
If enabled, token swaps are permitted with verified token pairs. Users can customize which pairs are allowed, and set a slippage limit to prevent trades that might result in MEV exploitation.
If you have additional requests for policies or custom use cases reach out to Shield3 at [info@shield3.com](mailto:info@shield3.com), join the Support Telegram or fill out the Survey
## Custom Error Codes
When Shield3 blocks or flags a transaction the RPC url returns a custom error message. The format is as follows:
```json
{
"jsonrpc": "2.0",
"error": {
"code": "-XXXXXX",
"message": "ERROR MESSAGE HERE"
},
"id": XX
}
```
These include:
**Transaction Blocked \[code -9999982]**
* Raised when policy engine results in block.
**Transaction Flagged for MFA \[code -9999981]**
* Raised when MFA result from policy engine.
* Webhook is sent to user’s configured webhook.
**RPC Call Failed \[code -9999980]**
* Raised when proxy call to user’s RPC fails.
**Invalid API Key \[code -9999979]**
* Raised when API key does not match any account.
**Invalid Node \[code -9999977]**
* Raised when network in RPC url does not match a valid network (0x01, 0x05, etc).
**Uncaught Error in Shield3 \[code -9999976]**
* Something went wrong, raises alert at Shield3 internally as well.
# Telegram Auto-Wallets
Source: https://docs.dynamic.xyz/guides/integrations/telegram/telegram-auto-wallets
Create a wallet in a single-click from your telegram mini-app.
## Introduction
If the user is linked with Telegram, they are automatically logged in.
If not, a splash modal prompts the user to confirm if they have an account. Based on the user's response, they are either are prompted to log in or a new account is automatically created and logged in.
This ensures app owners can maintain a single user identity, avoiding duplicate accounts.
## Introduction
Telegram Mini Apps (or TMAs) are web applications that run inside the Telegram messenger.
Dynamic works out of the box with TMAs, all you need to do is get your app scaffolded, and add Dynamic by following the quickstart guide.
The next step you might want to take is to update the contact if the user adds more details to their Dynamic profile i.e. wallet addresses etc. We will cover this in a further guide, so stay tuned!
# Webhooks using a serverless function
Source: https://docs.dynamic.xyz/guides/webhooks-serverless
This guide will teach you how to catch events from Dynamic webhooks using a serverless function.
## Prerequisites
* A [Dynamic](https://dynamic.xyz) account
* An [AWS](https://aws.amazon.com/) account
## Step 1: Scaffold a serverless function
You can do this directly through AWS, but we prefer to use [Serverless](https://www.serverless.com/) which creates a helpful layer of abstraction on top of Lambda.
First install their framework:
```bash
npm install -g serverless
```
Then run their setup command:
```bash
serverless
```
You will need to plug in your AWS credentials during setup, which you can find in your AWS console.
When asked which template you want to use, select `AWS - Node.js - HTTP API` as this tutorial will be using Node.js.
If you cd into the directory that was created, you should see an `index.js` file which is where we will be writing our code.
It will look something like this:
```javascript
module.exports.handler = async (event) => {
return {
statusCode: 200,
body: JSON.stringify(
{
message: "Go Serverless v3.0! Your function executed successfully!",
input: event,
},
null,
2
),
};
};
```
## Step 2: Create our webhook inside Dynamic
We need to create a webhook inside Dynamic that will send a POST request to our serverless function whenever a new user signs up.
To do this we can visit [the webhooks section of the dashboard](https://app.dynamic.xyz/dashboard/developer/webhooks) and click "Create Webhook". It will ask you for a URL and to mark the events you want to listen to.
For now we can use a fake URL, which we can generate from [webhook.site](https://webhook.site/). This will give us a URL that we can use to test our webhook, and will show us the data that is being sent to it.
For the events, you should make sure user.created is selected, and that's it! Save away and a test event will be sent to your URL.
## Step 3: Adapt the function to receive a Dynamic webhook event
Let's say in this instance We are most interested in [the user object](https://docs.dynamic.xyz/api-reference/schemas/User), as this is returned by the user.created event. You can find the full list of events [here](/developer-dashboard/eventTypes).
As you'll see from the event reference, the only required field on the object is the ID, so if you want to collect more information you'll need to make sure you're doing [Info Capture](/users/information-capture) on signup.
## Workshop recording
Check back soon!
## Adding Soneium as a network in Dynamic
```typescript
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core"
import { EthereumWalletConnectors} from "@dynamic-labs/ethereum"
import { soneiumMinato } from "viem/chains"
{error &&
);
};
```
## Best Practices
1. **Always confirm deletion**: Include a confirmation step before proceeding with account deletion.
2. **Clear explanation**: Clearly explain what data will be deleted and that the action is permanent.
## Hook Types and Functions
The `useDeleteUserAccount` hook provides:
* `deleteUser`: Function to initiate account deletion
* `isLoading`: Boolean indicating if deletion is in progress
* `error`: Error object if deletion fails
# Headless Email Signup
Source: https://docs.dynamic.xyz/headless/headless-email
## Introduction
This guide will help you let a user signup/login with email, without any of our UI components. We've split the guide into two tabs as you'll see below. The first uses our SDK hooks (but none of the UI components) - we recommend this choice if you can. The second tab shows you how to handle email login without any SDK interaction at all i.e. API only.
## Tutorial
Error: {error.message}
}
{!!user && (
)
}
```
Authenticated user:
{JSON.stringify(user, null, 2)}
)}
Signup with Email
setEmail(e.target.value)} placeholder="Enter your email" value={email} /> {verifying && (
setOTP(e.target.value)}
placeholder="Enter your OTP"
value={OTP}
/>
)}
{JWT && Your JWT is: {JWT}
}
{isLoggedIn ?
:
Choose which type of key you want to reveal from the embedded wallet
{result}Please log in to continue.
}
);
};
```
# Headless MFA
Source: https://docs.dynamic.xyz/headless/headless-mfa
Headless MFA only supports one verfied MFA device. Adding a second device will results in a 401
## Introduction
This guide will show you how to add MFA to your app using your own custom UI. You can also refer to the general MFA guide [here](/authentication-methods/mfa) to learn more about this feature (note that this guide is for account level MFA, rather than transaction level MFA).
For a working example, see: [https://codesandbox.io/p/sandbox/kh8g8s](https://codesandbox.io/p/sandbox/kh8g8s)
## General Flow
1. User logs in
2. User is redirected to the MFA view
3. User adds a device
4. User is redirected to the OTP view
5. User enters the OTP
6. User is redirected to the backup codes view
7. User acknowledges the backup codes
The user must accept the backup codes before the MFA flow is complete.
## Step-by-Step Implementation
### Step 1: Import Necessary Modules and Components
Start by importing the required modules and components:
```typescript
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import { FC, useEffect, useState, ReactElement, useMemo, useRef } from "react";
import {
DynamicContextProvider,
DynamicWidget,
useDynamicContext,
useIsLoggedIn,
useMfa,
useSyncMfaFlow,
} from "@dynamic-labs/sdk-react-core";
import { MFADevice } from "@dynamic-labs/sdk-api-core";
import QRCodeUtil from "qrcode";
```
### Step 2: Define Types
Define the types for the MFA registration data.
```typescript
type MfaRegisterData = {
uri: string;
secret: string;
};
```
### Step 3: Create the `MfaView` Component
This component handles the main logic for MFA, including device management, QR code generation, OTP submission, and backup codes.
```typescript
export const MfaView = () => {
const [userDevices, setUserDevices] = useState([]);
const [mfaRegisterData, setMfaRegisterData] = useState();
const [currentView, setCurrentView] = useState("devices");
const [backupCodes, setBackupCodes] = useState([]);
const [error, setError] = useState();
const isLogged = useIsLoggedIn();
const {
addDevice,
authenticateDevice,
getUserDevices,
getRecoveryCodes,
completeAcknowledgement,
} = useMfa();
const refreshUserDevices = async () => {
const devices = await getUserDevices();
setUserDevices(devices);
};
const { userWithMissingInfo, handleLogOut } = useDynamicContext();
useEffect(() => {
if (isLogged) {
refreshUserDevices();
}
}, [isLogged]);
useSyncMfaFlow({
handler: async () => {
if (userWithMissingInfo?.scope?.includes("requiresAdditionalAuth")) {
getUserDevices().then(async (devices) => {
if (devices.length === 0) {
setError(undefined);
const { uri, secret } = await addDevice();
setMfaRegisterData({ secret, uri });
setCurrentView("qr-code");
} else {
setError(undefined);
setMfaRegisterData(undefined);
setCurrentView("otp");
}
});
} else {
getRecoveryCodes().then(setBackupCodes);
setCurrentView("backup-codes");
}
},
});
const onAddDevice = async () => {
setError(undefined);
const { uri, secret } = await addDevice();
setMfaRegisterData({ secret, uri });
setCurrentView("qr-code");
};
const onQRCodeContinue = async () => {
setError(undefined);
setMfaRegisterData(undefined);
setCurrentView("otp");
};
const onOtpSubmit = async (code: string) => {
try {
await authenticateDevice({ code });
getRecoveryCodes().then(setBackupCodes);
setCurrentView("backup-codes");
refreshUserDevices();
} catch (e) {
setError(e.message);
}
};
return (
);
}
```
**Explanation:**
* **HeadlessMfaView:**
* Checks if the user is logged in or has missing information that requires additional authentication.
* If the user is logged in, it renders the `MfaView` component.
* If the user is not logged in, it renders the `LogIn` component.
* **App:**
* Your main app entry point.
* Make sure to set you environment id.
### Conclusion
By following this detailed breakdown, you should have a clear understanding of how the provided code implements a headless MFA solution using a custom UI. Each part of the code is explained, including the purpose of each component, hook, and function. This should help you understand the overall flow and how to customize it for your needs.
# Headless Overview
Source: https://docs.dynamic.xyz/headless/headless-overview
## Defining "headless"
While you can use the API to entirely decouple a frontend from Dynamic and still enable onboarding experiences, headless in this case refers to the ability to use the Dynamic SDK without our UI components.
This allows you to build your own UI components and still use the Dynamic SDK to manage the data and logic of your onboarding experience.
## Why go headless?
The Dynamic UI components handle a ton of edge cases, are actively maintained, and are designed to be easy to use while being completely flexible.
However, if for any reason these components are not fitting your use case, you might want to go headless.
## Getting started
You should still follow [the getting started guide](/quickstart) to add the SDK to your project.
Once your app is wrapped with the DynamicContextProvider, you can now start to use our hooks and context to build your own UI components.
This section outlines guides for each part of the onboarding experience, and how to build them headlessly. Specifically, they mimic building the same components as the Dynamic UI components, but with your own UI.
## Guides
* [Headless Email Signup/Login](/headless/headless-email)
* [Headless SMS Signup/Login](/headless/headless-sms)
* [Headless Social Signup/Login](/headless/headless-social)
* [Headless Export for Embedded Wallets](/headless/headless-embedded-reveal)
# Headless SMS signup
Source: https://docs.dynamic.xyz/headless/headless-sms
### Overview
Leveraging Dynamic's React package, this guide will help you create a sign in / sign up flow based on an sms login form.
We use [the `useConnectWithOtp` hook](/react-sdk/hooks/useconnectwithotp) to expose two methods: `connectWithSms` and `verifyOneTimePassword`.
The first method will send an SMS to the user's phone number, and the second will verify the OTP sent to the user's phone.
Once that's done, the user will be authenticated and you can access their information through the `useDynamicContext` hook!
### Dashboard Setup
#### SMS Signup/Login
The first thing you'll want to do is create a new Dynamic organization and setup Dashboard.
1. Sign up at app.dynamic.xyz
2. Fill in the modal to create your organization and project.
3. Under the Developer menu, go to SDK & APIs and fetch the Environment ID. Keep this as we'll need this key in a little bit.
Next we'll want to enable SMS signup/login:
For more information on how to configure SMS signup/login, check out our [SMS Signup/Login guide](/authentication-methods/email-social-sms).
### Configuring the SDK
Let's start by installing our packages. Follow our [Quickstart guide](/quickstart) for a detailed walkthrough.
When you're done, we'll update our App.js to include our environment ID in the setup and import the `DynamicContextProvider` and `EthereumWalletConnectors`.
You app.js file should look like this (note that we are only importing the EthereumWalletConnectors for now):
```jsx
import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
// Placeholder for our SMS signup/login form component
import ConnectWithSmsView from './ConnectWithSmsView';
function App() {
return (
);
}
export default App;
```
### SMS Signup/Login UI
Now that we have our environment, we can create our SMS signup/login form. We use the [`useConnectWithOtp` hook](/react-sdk/hooks/useconnectwithotp) to handle the SMS setup.
```tsx
import { FC, FormEventHandler } from 'react';
import { useConnectWithOtp, useDynamicContext } from '@dynamic-labs/sdk-react-core';
const ConnectWithSmsView: FC = () => {
const { user } = useDynamicContext()
const { connectWithSms, verifyOneTimePassword } = useConnectWithOtp();
const onSubmitSmsHandler: FormEventHandler = async (
event,
) => {
event.preventDefault();
const phone = {
dialCode: event.currentTarget.dialCode.value,
iso2: event.currentTarget.iso2.value,
phone: event.currentTarget.phone.value,
};
await connectWithSms(phone);
};
const onSubmitOtpHandler: FormEventHandler = async (
event,
) => {
event.preventDefault();
const otp = event.currentTarget.otp.value;
await verifyOneTimePassword(otp);
};
return (
```npm
npm i @dynamic-labs/sdk-react-core
```
```yarn
yarn add @dynamic-labs/sdk-react-core
```
This hook comes with a method called `signInWithSocialAccount` that you can utilize:
```tsx
import { FC } from 'react';
import {
DynamicWidget,
useDynamicContext,
useSocialAccounts,
} from '@dynamic-labs/sdk-react-core';
import { ProviderEnum } from '@dynamic-labs/types';
import { FarcasterIcon, GoogleIcon, TwitterIcon } from '@dynamic-labs/iconic';
const SocialSignIn = () => {
const { error, isProcessing, signInWithSocialAccount } = useSocialAccounts();
return (
);
};
const LoggedInUser = () => {
const { user } = useDynamicContext();
return (
<>
{error}
}
{currentView === "devices" && (
Devices
{JSON.stringify(userDevices, null, 2)}
Backup Codes
{codes.map((code) => ({code}
))} ); const LogIn = () => ( <>User not logged in!
Secret: {data.secret}
); }; const OTPView = ({ onSubmit }: { onSubmit: (code: string) => void }) => ( ); ``` **Explanation:** * **BackupCodesView:** * Displays the backup codes and provides an "Accept" button to acknowledge them. * **LogIn:** * Displays a message indicating that the user is not logged in and shows the `DynamicWidget` for login. * **QRCodeView:** * Displays the QR code for MFA setup and the secret key. Provides a "Continue" button to proceed to the OTP view. * **OTPView:** * Provides a form for the user to enter the OTP. On form submission, it calls the `onSubmit` function with the entered OTP. ### Step 5: Create the Main `HeadlessMfaView` Component This component checks if the user is logged in and displays the appropriate view. ```typescript export const HeadlessMfaView: FC = () => { const { user, userWithMissingInfo } = useDynamicContext(); return (
{user || userWithMissingInfo ?
);
};
export default function App() {
return (
{!!user && (
)
}
export default ConnectWithSmsView
```
# Headless Social Login
Source: https://docs.dynamic.xyz/headless/headless-social
This section shows you how to enable and implement social signup/login headlessly, using the Dynamic React SDK but without any of the UI components.
## Prerequisites
You must have at least one social provider enabled in the dashboard. For instructions on how to do this, check out [the configuring social providers section](/social-providers/overview).
## Implementation
You'll use [the `useSocialAccounts` hook](/react-sdk/hooks/usesocialaccounts) available from the `sdk-react-core` package:
Authenticated user:
{JSON.stringify(user, null, 2)}
)}
Log in or sign up
{isProcessing && Processing...} {error && {error.message}}user: {user?.email}
); }; export const HeadlessSocialSignInView: FC = () => { const { user } = useDynamicContext(); return (
{user ?
);
};
```
# Headless User Profile
Source: https://docs.dynamic.xyz/headless/headless-user-profile
## Introduction
This guide will help you to create a completely headless user profile including everything you see in the regular [Dynamic Widget UI component](/react-sdk/components/dynamicwidget)/[Dynamic Embedded Widget UI component](/react-sdk/components/dynamicembeddedwidget). If you'd like to see the Dynamic Widget/Embedded Widget in action, head over to [the live demo](https://demo.dynamic.xyz/).
## Prerequisites
Like with all this series of headless guides, "headless" is defined a way to use the Dynamic SDK without the need for Dynamic UI components (i.e. DynamicWidget, DynamicUserProfile).
You still need to add the SDK and set up the Dynamic Context Provider (complete [the quickstart](/quickstart) if you haven't done so already, or refer to [an example app](/example-apps))
### Setup
#### Show the user's profile based on whether they are logged in or not
How: Check if the user is logged in or not
Hook/Component: [useIsLoggedIn](/react-sdk/hooks/useisloggedin)
Notes: We start here assuming you have signup/login implemented already
```
import { useIsLoggedIn } from "@dynamic-labs/sdk-react-core";
const isLoggedIn = useIsLoggedIn();
return <>{isLoggedIn ?
{user?.firstName &&
);
```
#### Allow user to update their profile information
How: useUserUpdateRequest hook
Hook/Component: [useUserUpdateRequest](/react-sdk/hooks/useuserupdaterequest)
Notes: We include the validation for email updates here
```
import { useUserUpdateRequest, useOtpVerificationRequest } from "@dynamic-labs/sdk-react-core";
const { verifyOtp } = useOtpVerificationRequest();
const { updateUser } = useUserUpdateRequest();
const [showUpdateForm, setShowUpdateForm] = useState(false);
const [showVerifyForm, setShowVerifyEmailForm] = useState(false);
const updateUserInfoFormSubmit = async (e) => {
e.preventDefault();
try {
setLoading(true);
// Call the updateUser function with the new values entered by the user
const { isEmailVerificationRequired } = await updateUser({
firstName: e.target[0].value,
email: e.target[1].value,
});
// If email verification is required, show the email verification form
if (isEmailVerificationRequired) {
setShowVerifyEmailForm(true);
}
} catch (e) {
console.log("Error", e);
} finally {
setLoading(false);
setShowUpdateForm(false);
}
};
// Handler for the email verification form submission
const onVerifyEmailFormSubmit = async (e) => {
e.preventDefault();
try {
setLoading(true);
const verificationToken = e.target[0].value;
// Call the verifyEmail function with the entered verification token
await verifyOtp(verificationToken);
} catch (e) {
console.log("Error", e);
} finally {
setLoading(false);
// Hide the email verification form after the process is completed
setShowVerifyEmailForm(false);
}
return false;
};
return (
First name: {user.firstName}
} {user?.email &&E-Mail: {user.email}
} {user?.alias &&Alias: {user.alias}
} {user?.lastName &&Last name: {user.lastName}
} {user?.jobTitle &&Job: {user.jobTitle}
} {user?.phoneNumber &&Phone: {user.phoneNumber}
} {user?.tShirtSize &&Tshirt size: {user.tShirtSize}
} {user?.team &&Team: {user.team}
} {user?.country &&Country: {user.country}
} {user?.username &&Username: {user.username}
}
{/* Render the profile update form */}
{showUpdateForm && (
)}
{/* Render the email verification form if needed */}
{showVerifyEmailForm && (
)}
Please make sure you are on V4 of the SDK on your frontend before continuing.
## During Signup (automatic)
### Creating wallets for non-wallet authentication login
By default, embedded wallets are created automatically for users during sign-up if they don't already have a wallet on the enabled chain. All you have to do is check that the "Create on Sign up" toggle is turned on in [the Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic).
### Creating wallets for external wallet login
Embedded wallets can be automatically created for users signing in with external wallets, such as Metamask. To enable this feature, click the “Create on Sign up” card to expand the “Advanced Options” panel, and ensure the "Embedded Wallet for Third-Party Wallets" toggle is enabled.
Automatic embedded wallet creation only creates a single wallet for a user on
each chain you have selected. If you want to create multiple wallets per chain
you will need to use the
[createEmbeddedWalletAccount](/react-sdk/hooks/useembeddedwallet#create-embedded-wallet-account)
method from the `useEmbeddedWallet` hook. See [creating additional wallets](/wallets/embedded-wallets/create-embedded-wallets#creating-additional-wallets)
## Before Signup (pre-generated)
Pre-generated wallets allow you to create a wallet for a user prior to their first interaction with your application using either an email, phone number or social identifier (i.e. Farcaster or Twitter).
Simply provide an identifier to our API and receive the new wallet address in the response. The user can receive funds and assets into their wallet!
```javascript
const options = {
method: "POST",
headers: {
Authorization: "Bearer ",
"Content-Type": "application/json",
},
body: '{"identifier":"me@myemail.com","type":"email", "chain":"ETH", ,"socialProvider":"emailOnly"}',
};
fetch(
"https://app.dynamicauth.com/api/v0/environments/YOUR_ENVIRONMENT_ID/embeddedWallets",
options
)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err));
```
Check out the [createEmbeddedWallet
API](https://docs.dynamic.xyz/api-reference/wallets/createEmbeddedWallet) to see all the
available identifier types.
## Creating wallets on additional chains
For users with an existing embedded wallet on a single chain, you can create an embedded wallet on an additional chain using the [createEmbeddedWalletAccount](/react-sdk/hooks/useembeddedwallet#create-embedded-wallet-account) method exported from the `useEmbeddedWallet` hook.
## Custom Logic (manual)
### Creating wallets any time
If you do not want to create wallets for users automatically when they sign up, you can create wallets for users using custom logic, calling the `createEmbeddedWallet` method from the `useEmbeddedWallet` hook when you want to create a wallet for a user.
```javascript
import { useEmbeddedWallet } from "@dynamic-labs/sdk-react-core";
// component declaration and all other logic you might need
const { createEmbeddedWallet } = useEmbeddedWallet();
const onCreateWalletHandler = async () => {
try {
await createEmbeddedWallet();
} catch (e) {
console.error(e);
}
};
```
### Creating additional wallets
For users with an existing embedded wallet, you can create additional embedded wallets using the [createEmbeddedWalletAccount](/react-sdk/hooks/useembeddedwallet#create-embedded-wallet-account) method exported from the `useEmbeddedWallet` hook.
Using the `createEmbeddedWalletAccount` method to create additional wallets on the same chain derives wallets from the user's existing secret recovery phrase. This means that the user can access all their wallets using the same exported recovery phrase for each chain. The private keys for each wallet are derived from the recovery phrase and are unique to each wallet.
Embedded wallets created in Live environments cannot be deleted or removed. Ensure that you only create the desired quantity of wallets for each user.
The limitations for creating additional wallets are as follows:
* Maximum of 5 wallets per chain
* Maximum of 15 wallets per user
* If Smart Wallets are enabled, each generated signer wallet will have its own AA enabled wallet
### Creating Embedded Wallet alongside Branded Wallet
Keep the "Create on Sign up" toggle in the [Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic) toggled on, and then use the `createEmbeddedWallet` method from the `useEmbeddedWallet` hook to create a wallet for a user who has signed up using a branded wallet.
You can tell if you need to create that wallet post signup by checking `userHasEmbeddedWallet` from the `useEmbeddedWallet` hook.
```javascript
import { useEmbeddedWallet } from "@dynamic-labs/sdk-react-core";
// component declaration and all other logic you might need
const { createEmbeddedWallet, userHasEmbeddedWallet } = useEmbeddedWallet();
const onCreateWalletHandler = async () => {
if (!userHasEmbeddedWallet) {
try {
await createEmbeddedWallet();
} catch (e) {
console.error(e);
}
}
};
```
## Notes
### Content Security Policy (CSP)
Embedded wallets use iframes to provide one more security layer to the wallet. If you enforce CSP on your website, you will need to add the following to your `frame-src` directive:
* [https://export.turnkey.com](https://export.turnkey.com) - used for exporting a wallet's private key or seed phrase
## What Next?
* Learn how to use/interact with the wallet in [the Using Wallets section](/wallets/using-wallets)
* Learn how to customize the transaction flow in the [Embedded Transaction UI guide](/wallets/embedded-wallets/embedded-transaction-ui)
# Creating Transactions
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/creating-transactions
Since you can use embedded wallets like any other wallet, you can learn how to access and interact with the wallet in the [Using Wallets](/wallets/using-wallets) section.
The Using Wallets section also provides examples of wallet interactions for both [EVM](/wallets/using-wallets/evm) and [Solana](/wallets/using-wallets/solana), some of these examples are outlined below:
## EVM
* [Sign a message](/wallets/using-wallets/evm/sign-a-message)
* [Sign typed data](/wallets/using-wallets/evm/sign-typed-data)
* [Send a transaction](/wallets/using-wallets/evm/send-balance)
* [Sign a transaction with Wagmi](/wallets/using-wallets/evm/send-a-transaction-wagmi)
* [Fetch wallet balance](/wallets/using-wallets/evm/get-wallet-balance)
## Solana
* [Send legacy transaction](/wallets/using-wallets/solana/send-legacy-solana-transaction)
* [Send versioned transaction](/wallets/using-wallets/solana/send-versioned-solana-transaction)
# Overview
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/dynamic-embedded-wallets
An embedded wallet is a programmable web3 crypto wallet that provides seamless onboarding for your users. Created automatically at signup, these wallets allow users to immediately receive tokens and interact with blockchain networks without understanding complex wallet management.
Dynamic currently offers TEE based embedded wallets:
Looking for documentation on our legacy embedded wallets that use Trusted Execution Environments (TEE)? You can find the v1-v2 documentation here.
We are also excited to announce our new TSS-MPC offering, which is rolling out in the coming weeks.
We announced our new TSS-MPC offering at EthDenver 2025, and its rolling out in the coming weeks - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more.
Both wallet types are non-custodial and support use cases from basic web3 login to full wallet applications, differing primarily in their approach to key security and recovery.
# Customizing Transaction UI
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/embedded-transaction-ui
By default, when prompted to sign a transaction with an embedded wallet, a user will see a screen similar to this one:
## Disable Confirmation Screen
You can enable/disable this transaction confirmation screen with a single toggle in the [Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic). If you want to keep the confirmation UI but customize it, read on!
## Customize Confirmation Screen
### Modal title
By default this reads "Confirm transaction" as you can see in the image above, but you can customize it to say whatever you want. To do this, use [Translations](/design-customizations/customizing-copy-translations) and set the following:
```tsx
const locale = {
en: {
dyn_send_transaction: {
confirmation: {
title: "My New Title",
},
},
}
};
```
### Logo/Icon
In the [general page under Settings](https://app.dynamic.xyz/dashboard/settings/general) of your Dynamic Developer Dashboard, you can set your app logo URL. This logo will be displayed in the transaction confirmation screen in place of where you currently see the Dynamic logo in the image above.
### App Name
In the same [general page under Settings](https://app.dynamic.xyz/dashboard/settings/general) as above, you can also set your app name. This name will be displayed in the transaction confirmation screen in place of where you currently see "Dynamic" in the image above.
### Origin URL
This parameter is set by Dynamic and cannot be customized for obvious security reasons. It is the URL of the website that is requesting the transaction.
## Bring your own UI
You can also build your own flows for transactions and simply use the SDK hooks to trigger the actions you need, check out [the headless section](/headless) for that!
# Overview
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/overview-tee-wallets
we announced our new TSS-MPC offering at EthDenver 2025, and its rolling out in the coming weeks - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you’re looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you’ll have a clear upgrade path to transition your users to the new system.
## Overview
You can think of an embedded wallet like a powerful web-account. An embedded wallet is a programmable web3 crypto wallet that can be issued invisibly to customers on your website or app. Customers with an embedded wallet can immediately receive digital tokens and make on-chain interactions without needing to go through the complexities of understanding the intricacies of typical EOA wallets like Metamask or Phantom, or needing to download anything to start their journey.
Dynamic-powered embedded wallets can be used in a range of scenarios - from ways to ease onboarding on your websites to working as the base for building your own full stack wallet.
## Non Custodial
**Dynamic-powered embedded wallets are non-custodial, meaning they are always end-user owned and controlled. Only the end-user has ownership and access to their wallet private keys.**
Dynamic leverages a combination of internal and third party services, secure key management, advanced policy engines and security measures to limit potential security threats and ensure end user self-custody. All wallet private keys are encrypted and isolated such that neither Dynamic nor the Developer have access to the end user's wallet private keys. End-user decryption activities only run upon end-user activity requests.
In addition, all end users of Dynamic-powered embedded wallets can always export their wallet private key to take their assets into a different wallet provider or alternative storage location.
Dynamic is SOC2 Type 2 compliant and hires independent third parties to regularly conduct audits of our code, processes and systems. Dynamic also runs evergreen bug bounty programs.
## Multi-chain
Dynamic offers embedded wallets on EVM and SVM compatible networks. If you enable both, they will both be created at once and whichever you have marked as "primary" will be shown as the primary address in their profile upon sign in.
To enable embedded wallets for EVM or SVM networks the respective chains
must also be enabled. You can find more information about enabling chains and
networks [here](/chains/enabling-chains).
## Smart Wallets
You can turn these embedded wallets into smart contract wallets using our [smart wallet](/smart-wallets/add-smart-wallets) feature. By doing so, you can sponsor your end-users' fees, add complex approval logic, and much more.
# Wallet Reveal & Unlinking
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/reveal-export
This page details the Dynamic-powered embedded wallet reveal and export process, which enables end users to retrieve and backup their wallet credentials, as well as delete them from the Dynamic-powered embedded wallet.
## Revealing a Private Key/Seed Phrase
When implementing Dynamic in headless mode, please ensure you are surfacing this flow to your end users, so that they always maintain control of their wallet.
Revealing a wallet private key/seed phrase allows end users to retrieve their wallet credentials for backup or migration to another wallet or service. This is critical to ensure a user maintains control of their wallet, in case a user loses access to the provider service, needs to recover their wallet, or wants to use a different wallet provider with their existing wallet.
## End User Experience
The Dynamic export flow reveals the private key/seed phrase in an secure isolated iframe to limit the ability of Dynamic, the developer, or anyone in the flow to view the exported key. For more details on the security of the iframe and cryptographic flows go to our FAQs.
## Programmatically Triggering Wallet Export Flow
To ensure a user maintains control of their wallet, in case a user loses access to the provider service, we recommend using our hook to place the export flow immediately after creating the account.
To open the export wallet flow on behalf of your users, you can call the `initExportProcess` method from the [`useEmbeddedReveal`](/react-sdk/hooks/useembeddedreveal) hook. This will open the flow described above. Only the end-user will be able to see the private key or seed phrase.
```jsx
import { useEmbeddedReveal } from "@dynamic-labs/sdk-react-core";
const { initExportProcess } = useEmbeddedReveal();
;
```
You can see the experience by going to [demo.dynamic.xyz](https://demo.dynamic.xyz) and creating an embedded wallet.
## Unlinking customer’s embedded wallet from your app
This feature is available on V4.
Once an end-user has revealed their private key/seed phrase, they can choose to unlink it from your site, maintaining full control over the interfaces on which their private key exists. To do this, Dynamic provides a checkbox option and confirmation screen to complete this flow.
If an end user chooses to complete this flow, their embedded wallet will no longer work within your application. They will be issued a new embedded wallet if they log in again.
## Risks and Considerations
You should always provide your end users with a path to reveal and replicate their keys from their embedded wallet. When using the headless embedded wallet flow, please ensure you add a path for users to complete this step using the programmatic option described above.
End users should be aware that replicating their wallet credentials can expose their wallet to risk if the credentials are not stored securely. Users are advised to store their credentials in a secure location and not share them with anyone. When implementing Dynamic in headless mode, we recommend communicating these warnings to users.
## FAQs
Q. What is the security of the iFrame and how do you ensure only the end-user can access these credentials?
A. We leverage joint architecture with Turnkey to secure this flow, and you can dive into the cryptographic flows here: [https://docs.turnkey.com/features/export-wallets#cryptographic-details](https://docs.turnkey.com/features/export-wallets#cryptographic-details)
Q. What happens if user reveals and replicates their private key and loses it?
A. Users can return to use the application service. If they unlinked their account from the application service during export and then lost their private key, they would not be able to retrieve that wallet.
# Transaction Simulation
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/transaction-simulation
Please make sure you are on V4 of the SDK on your frontend before continuing.
Transaction Simulation can be enabled in the Embedded Wallet settings on the dashboard.
When turned on, as well as having the Confirmation UI on, transactions will be simulated to show all asset transfers of a transaction. So, if you are swapping 0.1 SOL to USDC, you will see the assets coming in and out on the transaction UI.
## Future Enhancements
Our upcoming security features will include comprehensive transaction and signature analysis to protect users from potential vulnerabilities. This includes detection of token and NFT approval requests, as well as any other asset exposures in order to provide enhanced transparency during transaction flows.
# Advanced Features
Source: https://docs.dynamic.xyz/wallets/mpc/advanced
Dynamic's TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
Dynamic's Embedded Wallets TSS-MPC solution is highly flexible and customizable, designed to meet the needs of enterprise customers and complex use cases. We offer several advanced features that can be tailored to your specific requirements. Here are some key capabilities:
## Developer-Hosted Backups
Enterprises can maintain their own backup infrastructure for key shares through [Developer-Hosted Backups](/wallets/mpc/glossary#developer-hosted-backups), providing an additional layer of control and security. This allows you to implement custom backup policies, manage recovery processes internally, and ensure business continuity according to your organization's requirements.
## Custom Key Derivation Options
Our solution supports flexible key derivation paths and customizable derivation schemes. This enables advanced use cases like hierarchical deterministic wallets, custom address generation patterns, and integration with existing key management systems.
## Advanced Key Sharing Configurations
Beyond the standard 2-of-3 setup, we support more complex key sharing arrangements like 3-of-5 configurations and other custom threshold schemes. This allows for more sophisticated security models, including:
* Multiple backup options
* Tiered access controls
* Enhanced security through additional key shares
* Custom recovery flows with [Independent Recovery](/wallets/mpc/glossary#independent-recovery)
# Architecture & Cryptography
Source: https://docs.dynamic.xyz/wallets/mpc/architecture
Dynamic's TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
## Architecture Overview
Dynamic's TSS-MPC implementation uses a default 2-of-2 threshold signature scheme, where:
* The user holds one [User Share](/wallets/mpc/glossary#user-share)
* Dynamic holds a [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share)
* Both shares are required to sign transactions
### Key Share Management
**During wallet creation:**
1. The [User Share](/wallets/mpc/glossary#user-share) is generated and stored locally on their device (on web, this is done in an iframe)
2. The [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share) is generated and stored by Dynamic in encrypted form
3. An encrypted copy of the User Share is stored by Dynamic using [User Share Backup Options](/wallets/mpc/glossary#user-share-backup-options)
4. The backup is encrypted using the [Encryption Proxy Service](/wallets/mpc/glossary#encryption-proxy-service)
5. Dynamic cannot decrypt the backup without the user
6. Users can optionally add [Passcode Encryption](/wallets/mpc/glossary#passcode-encryption) for additional backup security
**When signing transactions:**
1. The [User Share](/wallets/mpc/glossary#user-share) participates from their local device
2. The encrypted [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share) is decrypted and used for signing within a [TEE (Trusted Execution Environment)](/wallets/mpc/glossary#tee-trusted-execution-environment)
3. The complete private key is never reconstructed, even within the TEE
**This architecture ensures that:**
* No single party has complete control of the private key
* Users maintain self-custody of their wallet
* Recovery is possible if a user loses access to their device
* The system is resistant to compromise of any single party
* All sensitive signing operations are protected within the TEE
For advanced recovery options including cloud backup (Google Drive/iCloud) and upgrading to a 2-of-3 setup, see our [Recovery documentation](/wallets/mpc/recovery).
## Technical Implementation
### Distributed Key Generation (DKG)
The wallet creation process begins with Distributed Key Generation, where multiple parties work together to generate key shares without ever constructing the complete private key. Each party generates random values and participates in a secure protocol to create their share of the final key. This ensures no single party ever has access to the complete private key.
### Communication Security using MPC Relay
All communication between parties during key generation and signing is secured through our [MPC Relay](/wallets/mpc/glossary#mpc-relay) infrastructure. The relay:
* Ensures authenticated and encrypted communication channels
* Manages session establishment and party coordination
* Provides fault tolerance and retry mechanisms
* Implements rate limiting and abuse prevention
### Key Management Operations
To maintain security over time, two key management operations are available:
* [Key Resharing](/wallets/mpc/glossary#key-resharing): Modifies the existing parties or updates the threshold signature scheme
* [Key Refreshing](/wallets/mpc/glossary#key-refreshing): Rotates existing key shares to generate new cryptographically equivalent shares
## Protocols
We employ the following TSS-MPC cryptographic protocols in our SDK using audited libraries:
### Signature Schemes
* [ECDSA (DKLs19 Protocol)](/wallets/mpc/glossary#ecdsa-dkls19-protocol): For Ethereum and EVM-compatible chains
* [EdDSA (FROST Protocol)](/wallets/mpc/glossary#eddsa-frost-protocol): For Solana, StarkNet, and other EdDSA ecosystems
* [BIP-340 (FROST Protocol)](/wallets/mpc/glossary#bip-340-frost-protocol): For Bitcoin and Taproot-enabled blockchains
# Beta Testing Guide
Source: https://docs.dynamic.xyz/wallets/mpc/beta-testing-guide
Developer guide for testing Dynamic's TSS-MPC implementation
The TSS-MPC implementation is currently in beta testing. We may introduce
significant changes that could impact wallet functionality. **Do not store any
assets you cannot afford to lose.**
## Overview
This beta version of Dynamic TSS-MPC supports **2/2 and 2/3 threshold signature schemes**. This guide works for both React and React Native implementations. Server wallets are accessible through our node SDKs.
Headless documentation will be provided in future updates.
Future releases will provide additional key share storage flexibility, including independent hosting of backup shares.
## Server Wallets Overview
Spin up millions of secure, server-controlled wallets with battle-tested MPC infrastructure. Built for onchain automation, Dynamic Server Wallets let you trigger transactions, interact with contracts, and run complex flows—all without user involvement, and fully owned by your backend.
[Server wallets set up steps](#server-wallets-with-node-sdk)
### Supported Chains
* EVM
* Solana (SVM)
Breaking changes may occur in future updates.
## Known Limitations
The following features are currently not supported but will be included in subsequent releases:
1. **Importing an exported Solana Private key to a popular Solana Wallet**
* Private key exports will not be in a format compatible with Phantom Wallet or other wallets adhering to the ED25519 standard.
2. **Account Abstraction & Gas Sponsorship**
3. **Global Wallets**
4. **Low-Level Access to Signers** for chains other than EVM and SVM
5. **Pre-Generated wallets**
6. **Google Auth backup share**
## Additional Functions & Headless Setups
Documentation for headless implementations and advanced functions (including key refreshing, passcodes, backup share Google auth) will be added in the near future.
## Getting Started
### 1. Create a New Environment ID
Do not mix this environment with an existing environment containing V2 or V1
wallets.
### 2. Request Feature Access
Share your **Environment ID** with the Dynamic team to enable TSS-MPC via a feature flag.
### 3. Enable Embedded Wallets V3
Navigate to the [Dynamic Dashboard > Developers](https://app.dynamic.xyz/dashboard), Enabled Embedded Wallets and set the default wallet version to V3.
reference example: [https://github.com/dynamic-labs/mpc-react-demo](https://github.com/dynamic-labs/mpc-react-demo)
### 1. Install Wallet Connectors
```bash
npm i @dynamic-labs/waas-evm
npm i @dynamic-labs/waas-svm
```
### 2. Configure Your Provider
Include the connectors inside your provider settings:
```jsx
import { DynamicWaasEVMConnectors } from "@dynamic-labs/waas-evm";
import { DynamicWaasSVMConnectors } from "@dynamic-labs/waas-svm";
const connectors: [
// include existing connectors
DynamicWaasEVMConnectors,
DynamicWaasSVMConnectors,
],
const settings = {
...existingSettings,
walletConnectors: connectors,
};
return (
{/* Your app components */}
);
```
### 3. Access the walletClient, and/or signer as you would with Dynamic previously
```jsx
import { FC, useCallback, useState } from 'react';
import { encodeFunctionData, parseUnits } from 'viem';
import { baseSepolia } from 'viem/chains';
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isEthereumWallet } from '@dynamic-labs/ethereum-core';
const { primaryWallet } = useDynamicContext();;
const handleSubmit = useCallback(
async (args: TransactionArgs & { action: 'send' | 'approve' }) => {
if (!primaryWallet || !isEthereumWallet(primaryWallet) || isLoading) {
return;
}
try {
const provider = await primaryWallet.getWalletClient();
// Check if we're on Base Sepolia
const chain = await provider.getChainId();
if (chain !== baseSepolia.id) {
setErrorMessage(
`Please switch to Base Sepolia network (Chain ID: ${baseSepolia.id}). Current chain ID: ${chain}`,
);
return;
}
const usdcAmount = parseUnits(args.amount, 6); // USDC has 6 decimal places
const transaction = {
chain: baseSepolia,
data: await encodeFunctionData({
abi: USDC_ABI,
args: [args.toAddress, usdcAmount],
functionName: args.action === 'send' ? 'transfer' : 'approve',
}),
to: USDC_CONTRACT_ADDRESS as `0x${string}`,
};
const hash = await provider.sendTransaction(transaction);
setTxnHash(hash);
}
catch(e: any){
console.log('error', e)
}
},
[primaryWallet],
);
```
### Access MPC functionality through the connector directly
```jsx
import { DynamicWaasEVMConnector } from '@dynamic-labs/waas-evm';
const provider = await primaryWallet.getWalletClient();
// DynamicWaasEVMConnector or DynamicWaasSVMConnector
const waasConnector =
primaryWallet.connector as DynamicWaasEVMConnector;
const walletAccount = await waasConnector.createWalletAccount();
// get a wallet client for the wallet account by address
await waasConnector.getWalletClientByAddress({
accountAddress: walletAccount.accountAddress,
});
// export the client keyshares
await waasConnector.exportClientKeyshares({
accountAddress: walletAccount.accountAddress,
});
// export the private key
await waasConnector.exportPrivateKey({
accountAddress: walletAccount.accountAddress,
});
// import the private key
await waasConnector.importPrivateKey({
chainName: 'EVM',
privateKey: 'XXXX',
});
```
### Some MPC functionality is only accessible through the connector waas client
```jsx
const provider = await primaryWallet.getWalletClient();
// DynamicWaasEVMConnector or DynamicWaasSVMConnector
const waasConnector =
primaryWallet.connector as DynamicWaasEVMConnector;
const waasWalletClient = waasConnector.getWaasWalletClient();
const privateKey = await waasWalletClient.offlineExportPrivateKey({
keyShares: [],
});
```
### If using Vite please add the following wasmMiddleware to your vite.config.ts file
```jsx
///
reference example: [https://github.com/dynamic-labs/mpc-node-server-demo](https://github.com/dynamic-labs/mpc-node-server-demo)
### 1. Retrieve your auth token
Navigate to the [Dynamic Dashboard](https://app.dynamic.xyz/dashboard/developer/api) and create a new API token.
### 2. Install desired Node SDKs
```bash
npm i @dynamic-labs-wallet/node-evm
npm i @dynamic-labs-wallet/node-svm
```
### 3. Create client with authenticateApiToken call. Seperate clients are needed for each chain.
```typescript
const BASE_API_URL = 'https://app.dynamicauth.com';
const MPC_RELAY_URL = 'relay.dynamic-preprod.xyz';
export const authenticatedEvmClient = async ({
authToken,
environmentId,
baseApiUrl,
baseMPCRelayApiUrl,
}: {
authToken: string;
environmentId: string;
baseApiUrl?: string;
baseMPCRelayApiUrl?: string;
}) => {
const client = new DynamicEvmWalletClient({
authToken,
environmentId,
baseApiUrl: BASE_API_URL,
baseMPCRelayApiUrl: MPC_RELAY_URL,
});
await client.authenticateApiToken(authToken);
return client;
};
```
### 4. Access MPC functionality by creating a new wallet account
```typescript
const AUTH_TOKEN = 'your-auth-token';
const ENVIRONMENT_ID = 'your-environment-id';
const evmClient = await authenticatedEvmClient({
authToken: AUTH_TOKEN,
environmentId: ENVIRONMENT_ID,
});
const thresholdSignatureScheme = 'TWO_OF_TWO'; // or 'TWO_OF_THREE'
const password = 'your-optional-password';
const onError = (error: Error) => {
// handle error
console.error(error);
};
const {
accountAddress,
rawPublicKey,
publicKeyHex,
externalServerKeyShares,
} = await evmClient.createWalletAccount({
thresholdSignatureScheme,
password,
onError,
});
```
You can now use the accountAddress to sign messages, create transactions, and more. You can also back up your externalServerKeyShares to a secure location.
### 5. Example: Sign a message with the MPC wallet account
```typescript
const AUTH_TOKEN = 'your-auth-token';
const ENVIRONMENT_ID = 'your-environment-id';
const evmClient = await authenticatedEvmClient({
authToken: AUTH_TOKEN,
environmentId: ENVIRONMENT_ID,
});
const message = 'Hello, world!';
const accountAddress = '0x1234567890123456789012345678901234567890';
const password = 'your-optional-password';
const serializedSignature = await evmClient.signMessage({
message,
accountAddress,
password,
});
```
## Key Wallet Functions to Test
### Creating and Importing Wallets
#### `createWalletAccount()`
Creates a new TSS-MPC wallet account.
#### `importPrivateKey(options)`
Imports a private key.
**Parameters:**
* `privateKey`: string - The private key to import
* `chainName`: string - Currently supports 'EVM' and 'SOL' only
* `thresholdSignatureScheme`: string - Defaults to 'TWO\_OF\_TWO'
### Export Functions
#### `exportPrivateKey(options)`
Exports the private key for a specific account.
**Parameters:**
* `accountAddress`: string - The address of the account to export
#### `exportClientKeyshares(options)`
Exports client keyshares for a specific account.
**Parameters:**
* `accountAddress`: string - The address of the account to export keyshares for
#### `offlineExportPrivateKey()`
Exports a private key in offline mode.
## Feedback
We appreciate your feedback on the TSS-MPC beta. When providing feedback, please:
1. Use the tag **TSS-MPC Feedback or Question** in your communications
2. Create a thread in Slack with the #TSS-MPC-Feedback hashtag
# Creating Embedded Wallets
Source: https://docs.dynamic.xyz/wallets/mpc/creating-wallets
Dynamic's TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
No matter how your user signs up, whether it's using social login i.e. Telegram, email/phone login or even with a branded wallet i.e. Metamask, you can create an embedded wallet for them using Dynamic. Simply decide when you want this wallet created and follow the guides below.
Please make sure you are on V4 of the SDK on your frontend before continuing.
## During Signup (automatic)
### Creating wallets for non-wallet authentication login
By default, embedded wallets are created automatically for users during sign-up if they don't already have a wallet on the enabled chain. All you have to do is check that the "Create on Sign up" toggle is turned on in [the Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic).
### Creating wallets for external wallet login
Embedded wallets can be automatically created for users signing in with external wallets, such as Metamask. To enable this feature, click the "Create on Sign up" card to expand the "Advanced Options" panel, and ensure the "Embedded Wallet for Third-Party Wallets" toggle is enabled.
Automatic embedded wallet creation only creates a single wallet for a user on
each chain you have selected. If you want to create multiple wallets per chain
you will need to use the
[createEmbeddedWalletAccount](/react-sdk/hooks/useembeddedwallet#create-embedded-wallet-account)
method from the `useEmbeddedWallet` hook. See [creating additional wallets](/wallets/embedded-wallets/create-embedded-wallets#creating-additional-wallets)
## Before Signup (pre-generated)
Pre-generated wallets allow you to create a wallet for a user prior to their first interaction with your application using either an email, phone number or social identifier (i.e. Farcaster or Twitter).
Simply provide an identifier to our API and receive the new wallet address in the response. The user can receive funds and assets into their wallet!
```javascript
const options = {
method: "POST",
headers: {
Authorization: "Bearer ",
"Content-Type": "application/json",
},
body: '{"identifier":"me@myemail.com","type":"email", "chain":"ETH", ,"socialProvider":"emailOnly"}',
};
fetch(
"https://app.dynamicauth.com/api/v0/environments/YOUR_ENVIRONMENT_ID/embeddedWallets",
options
)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err));
```
Check out the [createEmbeddedWallet
API](https://docs.dynamic.xyz/api-reference/wallets/createEmbeddedWallet) to see all the
available identifier types.
## Creating wallets on additional chains
For users with an existing embedded wallet on a single chain, you can create an embedded wallet on an additional chain using the [createEmbeddedWalletAccount](/react-sdk/hooks/useembeddedwallet#create-embedded-wallet-account) method exported from the `useEmbeddedWallet` hook.
## Custom Logic (manual)
### Creating wallets any time
If you do not want to create wallets for users automatically when they sign up, you can create wallets for users using custom logic, calling the `createEmbeddedWallet` method from the `useEmbeddedWallet` hook when you want to create a wallet for a user.
```javascript
import { useEmbeddedWallet } from "@dynamic-labs/sdk-react-core";
// component declaration and all other logic you might need
const { createEmbeddedWallet } = useEmbeddedWallet();
const onCreateWalletHandler = async () => {
try {
await createEmbeddedWallet();
} catch (e) {
console.error(e);
}
};
```
### Creating additional wallets
For users with an existing embedded wallet, you can create additional embedded wallets using the [createEmbeddedWalletAccount](/react-sdk/hooks/useembeddedwallet#create-embedded-wallet-account) method exported from the `useEmbeddedWallet` hook.
Using the `createEmbeddedWalletAccount` method to create additional wallets on the same chain derives wallets from the user's existing secret recovery phrase. This means that the user can access all their wallets using the same exported recovery phrase for each chain. The private keys for each wallet are derived from the recovery phrase and are unique to each wallet.
Embedded wallets created in Live environments cannot be deleted or removed. Ensure that you only create the desired quantity of wallets for each user.
The limitations for creating additional wallets are as follows:
* Maximum of 5 wallets per chain
* Maximum of 15 wallets per user
* If Smart Wallets are enabled, each generated signer wallet will have its own AA enabled wallet
### Creating Embedded Wallet alongside Branded Wallet
Keep the "Create on Sign up" toggle in the [Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic) toggled on, and then use the `createEmbeddedWallet` method from the `useEmbeddedWallet` hook to create a wallet for a user who has signed up using a branded wallet.
You can tell if you need to create that wallet post signup by checking `userHasEmbeddedWallet` from the `useEmbeddedWallet` hook.
```javascript
import { useEmbeddedWallet } from "@dynamic-labs/sdk-react-core";
// component declaration and all other logic you might need
const { createEmbeddedWallet, userHasEmbeddedWallet } = useEmbeddedWallet();
const onCreateWalletHandler = async () => {
if (!userHasEmbeddedWallet) {
try {
await createEmbeddedWallet();
} catch (e) {
console.error(e);
}
}
};
```
# FAQs
Source: https://docs.dynamic.xyz/wallets/mpc/faq
Our TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
## Migration and Transition
### How do I upgrade my existing users?
We're working on seamless upgrade flows that will allow existing users to easily migrate from TEE to TSS-MPC wallets. This capability is coming soon.
### When can I get TSS-MPC wallets?
Our TSS-MPC offering is rolling out in the coming weeks. If you'd like to see a demo or migrate early, reach out and we'll make it happen.
### Will there be a cost to me?
No. Dynamic's pricing structure remains identical. There are no pricing changes, UI changes, or anything similar.
### Will your TEE support be deprecated? Is the migration mandatory?
No. We expect to continue supporting all existing customers using our TEE-based wallets. New customers will use our TSS-MPC wallets, and existing customers will have paths to migrate new and existing users.
### What exactly is changing in Dynamic's embedded wallet infrastructure?
We're evolving from TEE-based wallets to TSS-MPC wallets, which use threshold signatures and multi-party computation to enhance security and user experience. The core functionality remains the same, but with improved security, recovery options, and chain support.
### Why is Dynamic migrating from TEE-based wallets to TSS-MPC wallets?
Dynamic's TSS-MPC, represents the next evolution in wallet security and user experience. It eliminates single points of failure, provides more flexible recovery options, and enables advanced features while maintaining the same great user experience and speed. It is optimized to handle everything from thru-put trading and chains, to large capital money movements.
## Technical Details
### How does TSS-MPC differ from TEE-based wallets?
TSS-MPC generates cryptographic key shares that collectively enable signing operations without ever constructing a complete private key. This differs from TEE wallets which secure a complete private key within trusted hardware.
### Are TSS-MPC wallets more secure than TEE-based wallets?
Both approaches are highly secure, but TSS-MPC provides additional security benefits by never constructing a complete private key, even during signing operations. It also enables more flexible recovery options and security policies.
### Will TSS-MPC affect wallet performance?
No. While early MPC implementations were known for being slow, Dynamic's TSS-MPC solution uses advanced optimizations to deliver signing speeds comparable to traditional wallets (less than a second).
## User Impact
### Will users notice any changes?
No. The user experience remains identical - users can continue using familiar authentication methods like email and social login while maintaining self-custody.
### Will existing wallet addresses or balances be affected?
No. All assets and addresses will remain unchanged through the migration process.
### What new features will users get?
Users will gain access to more flexible recovery options, including cloud backup support and custom security policies. They'll also have access to more blockchain networks and signature schemes. We will also be adding support for agentic use cases among other exciting features. Stay tuned.
## Support
### Can I get early access?
Yes! Contact us through our [Slack community](https://www.dynamic.xyz/join-slack) or [website](https://www.dynamic.xyz) to learn more about early access opportunities.
### Where can I find more documentation?
Detailed technical documentation about our TSS-MPC implementation is available in our [Architecture](/wallets/mpc/architecture) and [Advanced Features](/wallets/mpc/advanced) sections.
# Glossary of Terms
Source: https://docs.dynamic.xyz/wallets/mpc/glossary
Dynamic's TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
| Term | Definition | Use |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TSS (Threshold Signature Scheme) | A cryptographic protocol that distributes signing authority across multiple parties, requiring a minimum threshold of participants to create valid signatures. Enables secure, distributed control while maintaining resilience against compromise of individual participants. | Dynamic enables the distribution, redistribution of shares across parties. Dynamic allows for thresholds to be adjusted based on the desired level of security and trust. Dynamic's TSS-MPC ensures a private key does not exist or compiled during any signing or ceremonies. |
| TEE (Trusted Execution Environment) | Isolated execution environments that operate within hardened Amazon EC2 instances and are ideal for handling highly sensitive data. Data can be encrypted and processed securely without leaving the protected environment. Allows for Cryptographic Attestation to verify the enclave is operating as expected and not tampered with. Dynamic uses AWS Nitro Enclaves. | Protects key management from unauthorized access. The TEE is stateless. Used for Server Share encryption/decryption and signing operations. |
| MPC Relay | The infrastructure that manages signing ceremonies and share communication over secure socket connections without exposing key material. | Enables decentralized signing with key shares. Ensures encrypted communication, session management, and fault tolerance. |
| Encryption Proxy Service | A relay that securely encrypts and proxies data for backup and recovery. | The encryption proxy service is a third-party encryption service for backups and recovery. It facilitates encrypted backup key storage and recovery. Used to double encrypt a passcode (if used). Further removes any single point of failure risks and ensures Dynamic does not have access to any key operations. |
| Key Resharing | The process of modifying the existing parties or updating the threshold signature scheme (e.g., upgrading from 2-of-2 to 2-of-3). | Used if a user adds a backup or if the Developer would like to modify the signature scheme to host backups for independent recovery. Resharing and refreshing requires user participation to prevent unilateral decisioning. |
| Key Refreshing | The process of rotating existing key shares to generate new cryptographically equivalent shares without changing the underlying wallet address. | Enhances security by preventing long-term exposure of shares. Can be manually triggered. Automatically performed during resharing. |
| Dynamic Server Share | A key share retained by Dynamic generated and encrypted within a Trusted Execution Environment (TEE). | Ensures Dynamic can participate in MPC signing without full key control. Generated securely inside a TEE where it is encrypted and then sent to Dynamic for storage. |
| User Share | Client-side key share, owned and controlled by the end user. Depending on the TSS Scheme there can be multiple user shares. | Used when signing transactions, stored locally or with an encrypted backup. Rendered in an iframe, stored in local storage or in device enclave (if mobile device used). |
| User Share Backup Options | Methods for securely storing an encrypted copy of the User Share for recovery purposes. Options include Google Drive, Apple iCloud, or local download. The backup is always encrypted before storage, with Dynamic never having access to decryption keys. | Enables User Share recovery in case of device loss or when setting up a new device. When using cloud storage options (Google Drive, Apple iCloud), encryption is done in the browser. For all options, the [Encryption Proxy Service](/wallets/mpc/glossary#encryption-proxy-service) ensures Dynamic cannot access the stored share. |
| Passcode Encryption | An optional user-set passcode that encrypts a User Share before storage. | Adds an extra layer of user-controlled security for stored shares. Used to restore a share on new devices or sessions. When a passcode is set up: Double encryption process: (1) Browser-side encryption with passcode, (2) Proxy Service encryption before storage. Dynamic never sees the passcode and only ever has access to a hash of the passcode encrypted share, ensuring it cannot be used to decrypt the share. |
| Independent Recovery | In 2-of-3 or 3-of-5 setups it enables offline recovery without Dynamic. Moving from 2-of-2 to 2-of-3 can be performed by the user. | Ensures account access if user share is lost. Can be stored by the user on Google Drive, Apple iCloud, or locally. In advanced setups, enterprises can be involved in independent recovery. |
| Developer-Hosted Backups | An enterprise feature allowing organizations to maintain their own backup infrastructure for key shares. | Enables custom backup policies, internal recovery processes, and business continuity management according to organization requirements. |
| ECDSA (DKLs19 Protocol) | A widely used digital signature algorithm for blockchain transactions, implemented using the DKLs19 protocol. | Supported on Ethereum, EVM-compatible chains. Used in Dynamic's TSS-MPC infrastructure for secure transaction signing. |
| EdDSA (FROST Protocol) | A modern, efficient, and secure digital signature algorithm based on Edwards curves. Implemented using the FROST Protocol. | Supported on Solana, StarkNet, and other ecosystems utilizing EdDSA. Used in Dynamic's TSS-MPC infrastructure for secure transaction signing. |
| BIP-340 (FROST Protocol) | A Schnorr-based digital signature scheme used in Bitcoin and other networks. Implemented using the FROST Protocol. | Supported on Bitcoin and Taproot-enabled blockchains. Used in Dynamic's TSS-MPC infrastructure for secure transaction signing. |
**Important Note**: Dynamic never has access to a quorum of shares that would allow key reconstruction. Even if a backup is encrypted via Dynamic's Encryption Proxy Service, it cannot be decrypted unilaterally by Dynamic.
# Import & Export
Source: https://docs.dynamic.xyz/wallets/mpc/import-export
Dynamic's TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
## Importing External Keys
When importing an existing private key into Dynamic's TSS-MPC system, we use Shamir Secret Sharing (SSS) to securely split the key into multiple shares. This process:
1. Takes your existing private key as input
2. Uses SSS to split it into either 2 or 3 shares (depending on your configuration)
3. Distributes the shares between the relevant parties (user, server, and optionally a backup)
4. Securely destroys the original complete private key
After import, the key exists only in its distributed form and all future operations use TSS-MPC - the complete private key is never reconstructed. This maintains the security benefits of TSS-MPC while allowing seamless migration from traditional wallets.
## Exporting Keys
Key export should be treated with caution as it temporarily reconstructs the complete private key. We recommend using the MPC system for normal operations and only exporting when absolutely necessary.
For maximum user control and portability, Dynamic allows users to export their private keys. During export:
1. The key shares are temporarily recombined on the user's device using secure MPC
2. The private key is constructed client side and provided to the user
This ensures users maintain true self-custody and can always access their assets, even outside of Dynamic's ecosystem.
When implementing Dynamic in headless mode, please ensure you are surfacing this flow to your end users, so that they always maintain control of their wallet.
### End User Experience
The Dynamic export flow reveals the private key/seed phrase in an secure isolated iframe to limit the ability of Dynamic, the developer, or anyone in the flow to view the exported key. For more details on the security of the iframe and cryptographic flows go to our FAQs.
### Programmatically Triggering Wallet Export Flow
To open the export wallet flow on behalf of your users, you can call the `initExportProcess` method from the [`useEmbeddedReveal`](/react-sdk/hooks/useembeddedreveal) hook. This will open the flow described above. Only the end-user will be able to see the private key or seed phrase.
```jsx
import { useEmbeddedReveal } from "@dynamic-labs/sdk-react-core";
const { initExportProcess } = useEmbeddedReveal();
;
```
You can see the experience by going to [demo.dynamic.xyz](https://demo.dynamic.xyz) and creating an embedded wallet.
### Unlinking customer's embedded wallet from your app
Once an end-user has revealed their private key/seed phrase, they can choose to unlink it from your site, maintaining full control over the interfaces on which their private key exists. To do this, Dynamic provides a checkbox option and confirmation screen to complete this flow.
If an end user chooses to complete this flow, their embedded wallet will no longer work within your application. They will be issued a new embedded wallet if they log in again.
## Risks and Considerations
You should always provide your end users with a path to reveal and replicate their keys from their embedded wallet. When using the headless embedded wallet flow, please ensure you add a path for users to complete this step using the programmatic option described above.
End users should be aware that replicating their wallet credentials can expose their wallet to risk if the credentials are not stored securely. Users are advised to store their credentials in a secure location and not share them with anyone. When implementing Dynamic in headless mode, we recommend communicating these warnings to users.
# Migration Guide
Source: https://docs.dynamic.xyz/wallets/mpc/migration
Our TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
## Overview
Migration tools for upgrading existing v2 embedded wallets to TSS-MPC v3 will be available soon. Contact us to learn more about early access.
If you have an existing project with users on Dynamic's TEE embedded wallets, you can enable our new TSS-MPC wallets in your dashboard. Once enabled, any new users will automatically receive v3 wallets with all the benefits of MPC.
For existing users with v2 wallets, we are working on introducing seamless upgrade flows that will allow them to easily migrate to v3 wallets using our built-in export and import functionality. This capability is coming soon - stay tuned for updates.
# Network Support
Source: https://docs.dynamic.xyz/wallets/mpc/network-support
Learn about the different networks supported by MPC wallets.
# Default Networks
Dynamic provides first-class support for EVM and SVM, with signer support for networks like Sui, Bitcoin, Cosmos, or any chain using:
* [ECDSA (DKLs19 Protocol)](/wallets/mpc/glossary#ecdsa-dkls19-protocol)
* [EdDSA (FROST Protocol)](/wallets/mpc/glossary#eddsa-frost-protocol)
* [BIP-340 (FROST Protocol)](/wallets/mpc/glossary#bip-340-frost-protocol)
Need expanded support for a specific chain? Contact us to discuss your use case.
Interested in implementing these advanced features? [Contact us](https://www.dynamic.xyz/get-started) to discuss your specific use case and how we can help customize our TSS-MPC solution for your needs.
# Using Dynamic TSS-MPC for additional networks and chains
This guide explains how to integrate Dynamic's TSS-MPC wallet infrastructure with blockchain networks that aren't supported out-of-the-box, such as Cardano.
Dynamic's TSS-MPC implementation provides secure, threshold-based signing across multiple networks. Today our out of the box implementation with abstractions support EVM, SVM, and rolling out support for Bitcoin and Cosmos. **Dynamic fully supports the necessary derivation paths and signing methods for other chains including Cardano**.
To integrate with an unsupported network, you will need to:
* Install the Dynamic Browser SDK
* Access low-level signer information
* Handle chain-specific data (message formatting, transaction preparation, etc.)
* Ensure proper derivation paths are configured
## Installation
Install the Dynamic Browser SDK:
```bash
npm install @dynamic-labs-wallet/browser
```
## Accessing Low-Level Signer Information
To work with other chains, you'll need to access and use the low-level signing functionality provided by the SDK. This allows you to implement chain-specific requirements while leveraging Dynamic's TSS-MPC infrastructure.
## Compile and use Chain-Specific Data
Each chain has unique requirements for message formatting, transaction structures, and address derivation. You'll need to implement these according to the network's specifications.
### Signature Example with Cardano
Cardano's message signing format requires a specific prefix structure:
```
\x19Cardano Signed Message:\n
```
Where `` is a single-byte integer representation of the message length.
For comparison, Ethereum uses:
```
\x19Ethereum Signed Message:\n
```
### Transaction Generation
You'll need to create properly formatted transactions for the target chain.
Cardano transactions require serialization using **CBOR (Concise Binary Object Representation)** encoding. You can use the **CIP-30 wallet API** or **Cardano serialization libraries** to construct valid transactions.
### Public Address Derivation
To derive a Cardano-compatible address, you need to:
* Convert the public key to a Cardano address using the correct format (Base, Enterprise, etc.)
* Handle **Shelley-era address formats** as required
### Serialization/Deserialization
Cardano transactions require:
* **CBOR encoding** for transaction data
* Proper **binary structure** for address formats
## Derivation Paths
Dynamic fully supports the necessary derivation paths for different blockchains. The following are the currently supported derivation paths:
For **Cardano**, use:
```javascript
{
derivationPath: [44, 1815, 0, 0, 0], // 1815 is Cardano's coin type
signingAlgorithm: SigningAlgorithm.ED25519
}
```
Dynamic's core packages will ensure the correct derivation paths are applied.
## Implementation Steps
1. **Setup the Dynamic SDK** as usual
2. **Access the low-level signer** from the SDK
3. **Implement chain-specific message formatting** for your target blockchain
4. **Create transaction structures** according to the chain's requirements
5. **Derive addresses** using the appropriate algorithm
6. **Request a signature** using the proper signing algorithm
7. **Process and utilize the signature** according to the chain's needs
## Resources
* [Dynamic Browser SDK](https://www.npmjs.com/package/@dynamic-labs-wallet/browser)
# Overview
Source: https://docs.dynamic.xyz/wallets/mpc/overview
Our TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
## Overview
You can think of an embedded wallet like a powerful web-account. An embedded wallet is a programmable web3 crypto wallet that can be issued invisibly to customers on your website or app. Customers with an embedded wallet can immediately receive digital tokens and make on-chain interactions without needing to go through the complexities of understanding the intricacies of typical EOA wallets like Metamask or Phantom, or needing to download anything to start their journey.
Dynamic-powered embedded wallets can be used in a range of scenarios - from ways to ease onboarding on your websites to working as the base for building your own full stack wallet.
## Why TSS-MPC?
Threshold Signature Scheme Multi-Party Computation (TSS-MPC) represents the next evolution in wallet security and user experience. Unlike traditional wallets where a single private key creates a single point of failure, TSS-MPC generates cryptographic key shares that collectively enable signing operations without ever constructing a complete private key. This approach offers several key benefits:
* **Enhanced Security**: No single party ever has access to the complete private key, significantly reducing the risk of theft or compromise. In fact, a private key never exists - even during any wallet activity.
* **Lightning Fast Performance**: Early MPC implementations were known for being slow (6+ seconds), Dynamic's TSS-MPC solution uses advanced optimizations to deliver signing speeds comparable to traditional wallets (less than a second)
* **Better Recovery Options**: Lost access can be restored through a combination of remaining key shares, eliminating the need for seed phrases
* **Flexible Key Management**: Enables advanced features like social recovery and custom security policies
* **Improved User Experience**: Users can authenticate using familiar methods like email and social login while maintaining self-custody
* **More chain support**: Dynamic TSS-MPC employs three signature schemes across major blockchains:
* [ECDSA (DKLs19 Protocol)](/wallets/mpc/glossary#ecdsa-dkls19-protocol): For Ethereum and EVM-compatible chains
* [EdDSA (FROST protocol)](/wallets/mpc/glossary#eddsa-frost-protocol): For Solana, StarkNet, and other EdDSA ecosystems
* [BIP-340 (FROST Protocol)](/wallets/mpc/glossary#bip-340-frost-protocol): For Bitcoin and Taproot-enabled blockchains
## Self Custodial
**Dynamic-powered embedded wallets are self-custodial, meaning they are always end-user owned and controlled. Only the end-user has ownership and access to their wallet private keys.**
Dynamic's TSS-MPC implementation uses a [User Share](/wallets/mpc/glossary#user-share) stored locally on the user's device and a [Server Share](/wallets/mpc/glossary#server-share) that participates in signing operations within a [TEE](/wallets/mpc/glossary#tee-trusted-execution-environment). The [MPC Relay](/wallets/mpc/glossary#mpc-relay) manages signing ceremonies without exposing key material. For added security, users can enable [Passcode Encryption](/wallets/mpc/glossary#passcode-encryption) and store a share in select [Backup options](/wallets/mpc/glossary#backup-share).
Dynamic offers a full range of flexibility for key sharing. Our default set up of 2/2 can be adjusted to 2/3 or to 3/5. This further mitigates single points of failure and adds fail safes for Users and Developers alike. For additional security, periodic [Key Resharing](/wallets/mpc/glossary#key-resharing--refreshing) can be performed.
Dynamic-powered embedded wallets can always be exported by the end-user to move to a different wallet provider or alternative storage location.
Dynamic is SOC2 Type 2 compliant and hires independent third parties to regularly conduct audits of our code, processes and systems. Dynamic also runs evergreen bug bounty programs.
## Multi-chain
Dynamic offers embedded wallets on EVM and SVM compatible networks. If you enable both, they will both be created at once and whichever you have marked as "primary" will be shown as the primary address in their profile upon sign in.
To enable embedded wallets for EVM or SVM networks the respective chains
must also be enabled. You can find more information about enabling chains and
networks [here](/chains/enabling-chains).
## Smart Accounts
You can turn these embedded wallets into smart accounts using our [smart wallet](/smart-wallets/add-smart-wallets) feature. By doing so, you can sponsor your end-users' fees, add complex approval logic, and much more.
# Recovery
Source: https://docs.dynamic.xyz/wallets/mpc/recovery
Dynamic's TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
## Standard Recovery Flow
Dynamic's TSS-MPC wallets use a 2-of-2 threshold signature scheme where one [User Share](/wallets/mpc/glossary#user-share) is held by the user on their device and a [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share) is held by Dynamic. For basic recovery scenarios, when a user logs in on a new device:
1. The user authenticates with their credentials
2. Dynamic provides their encrypted copy of the User Share
3. The share is decrypted through the [Encryption Proxy Service](/wallets/mpc/glossary#encryption-proxy-service) (Dynamic does not have access to encryption/decryption keys)
4. The decrypted share is stored on the new device
5. The wallet is ready for use immediately
This process happens invisibly to the end user, providing a seamless recovery experience. In other words, the user does not need to know a recovery occurred.
## Enhanced Security with Passcode Protection
For additional security, users can opt to protect their stored User Share with [Passcode Encryption](/wallets/mpc/glossary#passcode-encryption):
* The stored User Share is encrypted with the user's passcode
* When recovering on a new device, users must enter their passcode to decrypt the share
* Without the correct passcode, the stored share cannot be accessed
* This provides an extra layer of security but requires users to remember their passcode
You can toggle this option as required or optional in your developer dashboard.
## Cloud Backup Recovery (2-of-3 Setup)
Users can enable additional recovery options through [User Share Backup Options](/wallets/mpc/glossary#user-share-backup-options), storing their User Share to Google Drive, Apple iCloud, or downloading it locally.
When this is enabled:
* The system automatically upgrades to a 2-of-3 threshold scheme through [Key Resharing](/wallets/mpc/glossary#key-resharing)
* The user maintains their local [User Share](/wallets/mpc/glossary#user-share)
* A copy of the User Share is stored using their chosen backup option
* Dynamic continues to secure the [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share)
This creates three recovery paths:
1. Using the stored User Share from backup + Dynamic Server Share
2. Using the local User Share + Dynamic Server Share
3. Using the local User Share + stored User Share from backup ([Independent Recovery](/wallets/mpc/glossary#independent-recovery))
When a user has access to both their local User Share and the stored backup copy, they can perform Independent Recovery without requiring Dynamic's share. As long as they are logged in and have access to the client-side SDK, they can use these two shares to reconstruct and export their private key completely independently of Dynamic's systems. This provides an important self-custody guarantee - users can always recover their wallet even if Dynamic's services are unavailable.
We also offer additional more sophisticated recovery configurations including custom threshold schemes and [Developer-Hosted Backups](/wallets/mpc/glossary#developer-hosted-backups), see our [Advanced Features documentation](/wallets/mpc/advanced).
# Transactions
Source: https://docs.dynamic.xyz/wallets/mpc/transactions
Our TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more. If you're looking to start using Dynamic today, we recommend starting with our TEE wallets. When our TSS-MPC wallets are rolled out, you'll have a clear upgrade path to transition your users to the new system.
## Creating Transactions
Since TSS-MPC wallets function like any standard wallet, you can use them with all the common web3 libraries and patterns. The key difference is that signing operations are performed using secure MPC between the user's key share and Dynamic's key share.
For detailed examples of wallet interactions, see:
### EVM Examples
* [Sign a message](/wallets/using-wallets/evm/sign-a-message)
* [Sign typed data](/wallets/using-wallets/evm/sign-typed-data)
* [Send a transaction](/wallets/using-wallets/evm/send-balance)
* [Sign a transaction with Wagmi](/wallets/using-wallets/evm/send-a-transaction-wagmi)
* [Fetch wallet balance](/wallets/using-wallets/evm/get-wallet-balance)
### Solana Examples
* [Send legacy transaction](/wallets/using-wallets/solana/send-legacy-solana-transaction)
* [Send versioned transaction](/wallets/using-wallets/solana/send-versioned-solana-transaction)
## Transaction UI
By default, when a user needs to sign a transaction, they'll see a confirmation screen like this:
You can customize various elements of the transaction UI:
### Disable Confirmation Screen
You can enable/disable the transaction confirmation screen with a single toggle in the [Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic).
### Modal Title
Change the default "Confirm transaction" text using [Translations](/design-customizations/customizing-copy-translations):
## Transaction Simulation
When turned on, as well as having the Confirmation UI on, transactions will be simulated to show all asset transfers of a transaction. So, if you are swapping 0.1 SOL to USDC, you will see the assets coming in and out on the transaction UI.
# Multi Asset UI
Source: https://docs.dynamic.xyz/wallets/multi-asset
## Overview
With Dynamic's multi-asset UI, you can present your end users with the individual balances of each asset they hold in their wallet.
Balance and pricing information is refreshed every 20 min. If you need minute by minute refresh and different asset support, contact sales.
The list of tokens reflect the top 1000 tokens by DEX volume. We leverage Coingecko for pricing.
You can also choose to show the Fiat balance of those assets in whatever their primary currency is.
Multi-asset is only supported on the following networks: Ethereum, Optimism, Polygon, Arbitrum, and Base.
## Configuration
Enabling multi-asset (turned on by default) is as simple as a toggle in the Dynamic Dashboard within [the Log in & User Profile page](https://app.dynamic.xyz/dashboard/log-in-user-profile), under the "Design Settings" section.
## UI Layout
The multi-asset UI is designed to be collapsible, so that it doesn't take up too much space on your page. It will display balances in either the native token or the fiat equivalent, depending on your configuration.
It will display in the user profile section of [the DynamicWidget](/react-sdk/components/dynamicwidget), or if you are implementing individual UI components, you can use [the UserProfile](/react-sdk/components/dynamicuserprofile) component.
## Build it yourself
You can also build your own multi-asset UI using the hooks provided by the Dynamic SDK, you can use [the useTokenBalances hook](/react-sdk/hooks/usetokenbalances) to do so.
# Send Assets
Source: https://docs.dynamic.xyz/wallets/send-balance-ui
## Summary
Dynamic provides a simple and easy-to-use interface for users to send tokens to any address on EVM and Solana (available on the latest V3 of the SDK).
This allows your users to easily move funds from their wallets without leaving the dapp, while removing the burden of creating send flows and gas calculations across all EVM networks and Solana for you as a developer. Note that for Solana, we also include a priority fee to improve success rates in case of congestion on the network.
You have two options to surface this UI to your end users: the first is within the Dynamic Widget, and the second is programmatically opening the UI from your own site. We cover both options here.
## Within Dynamic Widget/Embedded Widget
### Add the widget
Simply add the [Dynamic Widget](/react-sdk/components/dynamicwidget) or [Dynamic Embedded Widget](/react-sdk/components/dynamicembeddedwidget) to your dapp and the Send Token UI will be available to your users.
```jsx
import { DynamicWidget, DynamicEmbeddedWidget } from "@dynamic-labs/sdk-react-core";
// COMPONENT INSIDE TREE WHERE DYNAMIC CONTEXT IS AVAILABLE
const Main => {
return (
You can then choose from any available token in your wallet, add an amount and recipient address, then preview the transaction before confirming.
## Standalone UI (useSendBalance)
You can use our useSendBalance hook to trigger the Send Balance UI and optionally, prepopulate the form for the user.
### How it works
The useSendBalance hook depends on the DynamicContextProvider, so it has to be used as a child of the Dynamic context. When you use the hook, you will get a function named `open`. That method accepts the follow options:
| Parameter | Type | Description |
| :--------------- | :--------------- | :----------------------------- |
| recipientAddress | String | The initial recipient address |
| value | ethers.BigNumber | The initial transaction amount |
The `open` function will return a promise; If successful, the promise will be resolved with the transaction; if not successful, the promise will be rejected accompanied by the error collected from the provider.
Here is an example of a custom Send button
```typescript
import { useSendBalance } from "@dynamic-labs/sdk-react-core";
const MySendButton = () => {
const { open } = useSendBalance();
return ;
};
```
From this example, when the user clicks the button, they will be prompted to fill the amount and recipient fields, review the transaction, and they will see a confirmation at the end of the flow.
For the second example, we will pre-populate the recipient and amount fields for the user.
```typescript
import { useSendBalance } from "@dynamic-labs/sdk-react-core";
import { ethers } from "ethers";
const MySendButton = () => {
const { open } = useSendBalance();
const onCickSend = async () => {
try {
const tx = await open({
recipientAddress: "",
value: ethers.utils.parseEther("1"),
});
} catch (err) {
// Handle the promise rejection
}
};
return ;
};
```
Here, when the user clicks the button, they will be prompted with the same UI, but now it will be pre-populated with the recipient address and amount.
# Accessing Wallets
Source: https://docs.dynamic.xyz/wallets/using-wallets/accessing-wallets
Learn about primaryWallet, useUserWallets, onEmbeddedWalletCreated, and handleConnectedWallet
## Introduction
It's not neccessary for a wallet to be associated with a user when they sign up, but the likelyhood is that if a user is interacting with Web3, one will be connected at some point, whether embedded or external (branded).
### Primary Wallet
Normally, if one or more wallets are connected, a `primaryWallet` object will be available on the Dynanmic Context which you can access with [the `useDynamicContext` hook](/react-sdk/hooks/usedynamiccontext). This is a quick and easy way to access the main wallet associated with that user.
```jsx
const { primaryWallet } = useDynamicContext();
```
### useUserWallets
Going beyond the primary wallet, you might want to get every wallet associated with the given user. The best option for this is to use [the `useUserWallets` hook](/react-sdk/hooks/useuserwallets).
```jsx
import { FC } from 'react'
import { useUserWallets } from '@dynamic-labs/sdk-react-core'
export const ListConnectedWallets: FC = () => {
const userWallets = useUserWallets()
return (
)
}
```
### onEmbeddedWalletCreated
If you're using embedded wallets, you can listen for the `onEmbeddedWalletCreated` event to know when a wallet has been created for a user. This is useful for when you want to know when a user has a wallet created for them, but you don't want to have to poll the API to check.
```tsx
{
console.log('onEmbeddedWalletCreated was called', args);
}
}
}}
>
{/* ... rest of your app ... */}
```
## Add extra logic during any wallet connection (handleConnectedWallet)
Sometimes you may want to inject some of your own logic during the process of a wallet becoming connected. Dynamic has a concept of ["handlers"](/react-sdk/overview#handlers), which is a particular kind of callback to allow custom code to run as part of a process (i.e. signup).
`handleConnectedWallet` is a handler that runs before we establish the wallet connection. You can use this callback to run your logic and reject (by returning boolean false). For example, running a fraud check before establishing the connection.
The args returned by handleConnectedWallet is a [Wallet](/wallets/using-wallets/accessing-wallets#wallet-interface) but without the `connected` boolean.
```jsx
{
console.log("handleConnectedWallet was called", args);
// if runYourOwnLogic return true, the connection will be established, otherwise it will not
return runYourOwnLogic();
},
},
}}
>
{/* ... rest of your app ... */}
```
## What next?
Click here to learn how to interact with wallets.
# Bitcoin Wallets
Source: https://docs.dynamic.xyz/wallets/using-wallets/bitcoin/bitcoin-wallets
We covered what a wallet in general looks like in the [Accessing Wallets](/wallets/using-wallets/accessing-wallets) section and then what a wallet connector looks like in the [Interacting With Wallets section](/wallets/using-wallets/interacting-with-wallets). However, the wallet connector for Bitcoin wallets is a bit different from the EVM wallets, so we will cover that seperately here.
This is because Bitcoin wallets have different capabilities and requirements. For example, Bitcoin wallets can have multiple addresses associated with them, like payment and ordinal addresses.
## Checking if a wallet is a Bitcoin wallet
You can use the `isBitcoinWallet` helper method to check if a wallet is a Bitcoin wallet. That way, TypeScript will know which methods are available to you.
```ts
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
if (!isBitcoinWallet(wallet)) {
throw new Error('This wallet is not a Bitcoin wallet');
}
const result = wallet.sendBitcoin({
amount: 100000000n,
recipientAddress: 'SOME-ADDRESS',
});
```
## Bitcoin Wallet
| Method | Description |
| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| sendRawTransaction(rawTransactionHex: string): Promise\ | This method submits a raw transaction to the bitcoin blockchain and returns the transaction ID as the response |
| sendBitcoin(transaction: BitcoinTransaction): Promise\ | A method to send an amount of satoshis to a recipient bitcoin address |
| signMessage(messageToSign: string, \{ addressType: WalletAddressType, protocol: BitcoinSignProtocol }): Promise\ | Signs a message with a specific bitcoin address type ('ordinals' or 'payment') and/or protocol ('ecdsa' or 'bip322-simple') |
| signPsbt(request: BitcoinSignPsbtRequest): Promise\ | Signs a PSBT and returns an object with the signed PSBT |
| signPsbts(request: BitcoinSignPsbtRequest\[]): Promise\ | Signs a list of PSBTs and returns an array of signed PSBTs in base64 |
## Type Definitions
```ts
type BitcoinSignPsbtRequest = {
allowedSighash: number[];
unsignedPsbtBase64: string;
signature?: {
address: string;
signingIndexes: number[] | undefined;
disableAddressValidation?: boolean; // helpful for multi-sig
}[];
};
type BitcoinTransaction = {
amount: bigint;
recipientAddress: string;
}
type WalletAddressType = 'payment' | 'ordinal';
type WalletAdditionalAddress {
address: string;
publicKey?: string;
type: WalletAddressType;
}
type BitcoinSignPsbtResponse = {
signedPsbt: Psbt; // see reference below for what a PSBT is
};
```
## What is a satoshi?
This smallest unit allows for transactions involving very small amounts of bitcoin,
facilitating microtransactions and improving the granularity of payments in the Bitcoin network.
```
1 Bitcoin = 100,000,000 Satoshis
```
## What is a PSBT?
A partially signed bitcoin transaction (PSBT) is a standard for transactions that have not fully signed.
This allows different participants with different keys/signers to sign a transaction without revealing their private keys to others.
Multi-sig wallets utilize these. This allows for a multi-step transaction process which is both safer and more efficient.
## Examples
We’ve included a few examples of how to use the Bitcoin wallet connector in this section:
* [Send a transaction](/wallets/using-wallets/bitcoin/send-a-transaction)
* [Send a raw transaction](/wallets/using-wallets/bitcoin/send-raw-transaction)
* [Sign a message](/wallets/using-wallets/bitcoin/sign-a-message)
# Send Bitcoin
Source: https://docs.dynamic.xyz/wallets/using-wallets/bitcoin/send-a-transaction
In this example, we are going to send bitcoin using the wallet connector.
```JavaScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
const SendBitcoinButton = () => {
const { primaryWallet } = useDynamicContext();
const sendBitcoin = async () => {
if (!primaryWallet || !isBitcoinWallet(primaryWallet)) return;
// The first argument is the address you are sending to, the second argument is the amount of BTC in satoshis
const transactionId = await primaryWallet.sendBitcoin('', 1);
console.log('transactionId', transactionId);
};
return ;
};
```
# Send a raw transaction
Source: https://docs.dynamic.xyz/wallets/using-wallets/bitcoin/send-raw-transaction
In this example, we are going to send a raw transaction as a hex value to the bitcoin network.
For information on how to construct the transactionHexString, please refer to [this example](https://medium.com/@claudio_69833/how-to-create-bitcoin-transactions-with-javascript-b3b43f53ca0c).
```JavaScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
const SendRawTransaction = () => {
const { primaryWallet } = useDynamicContext();
const signMessage = async () => {
if (!primaryWallet || !isBitcoinWallet(primaryWallet)) return;
const transactionId = await primaryWallet.sendRawTransaction('transactionHexString');
console.log('transactionId', transactionId);
};
return ;
};
```
# Sign a message
Source: https://docs.dynamic.xyz/wallets/using-wallets/bitcoin/sign-a-message
In this example, we are going to sign a message for Bitcoin.
```JavaScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
const SignMessageButton = () => {
const { primaryWallet } = useDynamicContext();
const signMessage = async () => {
if (!primaryWallet || !isBitcoinWallet(primaryWallet)) return;
const signature = await primaryWallet.signMessage('example');
console.log('signature', signature);
};
return ;
};
```
You can also sign a message with a specific address type (payment or ordinal) or protocol (ecdsa or bip322-simple) by passing extra params in the `signMessage` options.
```JavaScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
const SignMessageButton = () => {
const { primaryWallet } = useDynamicContext();
const signMessageWithOrdinalsAddress = async () => {
if (!primaryWallet || !isBitcoinWallet(primaryWallet)) return;
const signature = await primaryWallet.signMessage('example', { addressType: 'ordinals' });
console.log('signature', signature);
};
const signMessageWithPaymentAddress = async () => {
if (!primaryWallet || !isBitcoinWallet(primaryWallet)) return;
const signature = await primaryWallet.signMessage('example', { addressType: 'payment' });
console.log('signature', signature);
};
const signMessageWithEcdsaProtocol = async () => {
if (!primaryWallet || !isBitcoinWallet(primaryWallet)) return;
const signature = await primaryWallet.signMessage('example', { addressType: 'ordinals', protocol: 'ecdsa' });
console.log('signature', signature);
};
return <>
;
};
```
Notes:
* Some wallets don't allow you to specify the address type or protocol. In this case, we'll just default to the address type and protocol that the wallet supports.
* If you don't specify an address type, we'll default to the address type that the wallet supports or ordinals address.
* If you don't specify a protocol, we'll default to the protocol that the wallet supports or bip322-simple.
# Sign a Partially Signed Bitcoin Transaction (PSBT)
Source: https://docs.dynamic.xyz/wallets/using-wallets/bitcoin/sign-a-psbt
# Guide to Creating a Partially Signed Bitcoin Transaction (PSBT) for Developers
This guide will walk you through the steps to create and sign a Partially Signed Bitcoin Transaction (PSBT) using a combination of JavaScript libraries and React components. The provided code example is comprehensive, but we'll break it down step-by-step to ensure you understand each part.
## Table of Contents
1. [Understanding Partially Signed Bitcoin Transactions (PSBT)](#1-understanding-partially-signed-bitcoin-transactions-psbt)
2. [Step-by-Step Guide](#2-step-by-step-guide)
* [Step 1: Import Necessary Libraries and Functions](#step-1-import-necessary-libraries-and-functions)
* [Step 2: Initialize the ECC Library](#step-2-initialize-the-ecc-library)
* [Step 3: Define Constants and Helper Functions](#step-3-define-constants-and-helper-functions)
* [Step 4: Generate the PSBT](#step-4-generate-the-psbt)
* [Step 5: Create the SignMessageViaTransaction Component](#step-5-create-the-signmessageviatransaction-component)
* [Step 6: Create the Main Component](#step-6-create-the-main-component)
3. [Full Code Example](#3-full-code-example)
***
## 1. Understanding Partially Signed Bitcoin Transactions (PSBT)
A Partially Signed Bitcoin Transaction (PSBT) is a standard format for handling Bitcoin transactions that require multiple signatures or other complex signing workflows. PSBTs enable the separation of transaction creation and signing, allowing for more flexible and secure transaction management.
### Key Features of PSBT
* **Interoperability**: PSBTs can be used across different wallets and software.
* **Flexibility**: Allows for multiple parties to contribute signatures to a single transaction.
* **Security**: Enhances security by enabling hardware wallets and other secure devices to sign transactions without exposing private keys.
***
## 2. Step-by-Step Guide to Creating a PSBT
This section provides a detailed step-by-step guide to creating a PSBT using the `bitcoinjs-lib` library in JavaScript. We'll break down each part of the provided code example and explain what it does.
### Step 1: Import Necessary Libraries and Functions
First, we import the necessary libraries and helper functions for working with Bitcoin transactions, data conversions, hashing, elliptic curve cryptography, and React components.
* **bitcoinjs-lib**: A popular JavaScript library for working with Bitcoin transactions.
* **@stacks/common**: Provides utility functions for handling data conversions.
* **@noble/hashes/sha256**: Implements the SHA-256 hashing algorithm.
* **@bitcoinerlab/secp256k1**: Provides elliptic curve cryptography functions for Bitcoin.
* **@dynamic-labs/sdk-react-core**: Provides context for accessing wallet information.
* **@dynamic-labs/wallet-connector-core**: Checks if the wallet connector is a Bitcoin connector.
* **useState**: A React hook for managing state in a functional component.
```javascript
import { DynamicWidget, useDynamicContext } from "@dynamic-labs/sdk-react-core";
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
import * as bitcoin from 'bitcoinjs-lib';
import { hexToBytes, utf8ToBytes } from '@stacks/common';
import { sha256 } from '@noble/hashes/sha256';
import ecc from '@bitcoinerlab/secp256k1';
import { useState } from "react";
```
### Step 2: Initialize the ECC Library
Before we can work with elliptic curve cryptography (ECC) functions in Bitcoin transactions, we need to initialize the ECC library. This step is crucial for enabling cryptographic operations such as signing and verifying transactions.
**bitcoin.initEccLib(ecc);**
* **Purpose**: The `bitcoinjs-lib` library relies on an ECC library to perform cryptographic operations. By default, `bitcoinjs-lib` does not include an ECC library to keep the core library lightweight and modular. We need to explicitly provide an ECC implementation.
* **Library Used**: In this example, we use the `@bitcoinerlab/secp256k1` library, which is an implementation of the secp256k1 elliptic curve, commonly used in Bitcoin.
* **Initialization**: We pass the `ecc` object from the `@bitcoinerlab/secp256k1` library to the `bitcoin.initEccLib` function to initialize the ECC library. This allows `bitcoinjs-lib` to use the ECC functions provided by the `@bitcoinerlab/secp256k1` library.
```javascript
bitcoin.initEccLib(ecc);
```
### Step 3: Define Constants and Helper Functions
Next, we define some constants and helper functions that will be used throughout the process. These include a message tag for BIP-322, a hashed version of this tag, and values for a dummy transaction input.
#### BIP-322 Message Tag and Hash
**BIP-322** is a Bitcoin Improvement Proposal that defines a standard way to sign and verify arbitrary messages using Bitcoin keys. To ensure the message being signed is unique and recognizable as a BIP-322 message, a specific tag (`bip322MessageTag`) is used. This tag is hashed twice using SHA-256 to create a unique identifier (`messageTagHash`).
```javascript
const bip322MessageTag = 'BIP0322-signed-message';
const messageTagHash = Uint8Array.from([
...sha256(utf8ToBytes(bip322MessageTag)),
...sha256(utf8ToBytes(bip322MessageTag)),
]);
```
#### Dummy Transaction Input Values
The `bip322TransactionToSignValues` object contains placeholder values for a previous transaction output. These values are used to construct a virtual transaction that is not actually spending real Bitcoins but is required to prepare the PSBT.
* **prevoutHash**: A 32-byte array of zeros, representing the hash of a non-existent previous transaction.
* **prevoutIndex**: Set to `0xffffffff`, a special value indicating that this is not a real transaction output.
* **sequence**: Set to `0`, indicating the sequence number of the transaction input.
```javascript
export const bip322TransactionToSignValues = {
prevoutHash: hexToBytes('0000000000000000000000000000000000000000000000000000000000000000'),
prevoutIndex: 0xffffffff,
sequence: 0,
};
```
#### Hashing the BIP-322 Message
The `hashBip322Message` function takes a message (as a `Uint8Array` or a string) and hashes it using the SHA-256 algorithm, along with the `messageTagHash`. This ensures that the message is uniquely identified as a BIP-322 message.
```javascript
export function hashBip322Message(message) {
return sha256(
Uint8Array.from([...messageTagHash, ...(isString(message) ? utf8ToBytes(message) : message)])
);
}
function isString(value) {
return typeof value === 'string';
}
```
### Step 4: Generate the PSBT
The `generatePsbt` function creates a Partially Signed Bitcoin Transaction (PSBT) using the provided address and message.
#### Step-by-Step Explanation:
1. **Generate Script**: Convert the Bitcoin address into a scriptPubKey. This script is used to determine the conditions under which the Bitcoin can be spent.
2. **Hash the Message**: Hash the message using the BIP-322 message hash function. This ensures the message is uniquely identified and securely hashed.
3. **Create ScriptSig**: Create the scriptSig with the hashed message. The scriptSig is part of the transaction input and contains the conditions required to spend the UTXO.
4. **Virtual Transaction**: Create a virtual transaction to spend, setting the necessary inputs and outputs. This virtual transaction simulates spending a UTXO without actually spending real Bitcoins.
5. **Create PSBT**: Create a PSBT object and add the necessary inputs and outputs. This PSBT will be signed by the wallet.
```javascript
const generatePsbt = (address, message) => {
const { prevoutHash, prevoutIndex, sequence } = bip322TransactionToSignValues;
// Generate the script for the given address
const script = bitcoin.address.toOutputScript(
address,
bitcoin.networks.bitcoin
);
// Hash the message
const hash = hashBip322Message(message);
// Create the scriptSig with the hashed message
const commands = [0, Buffer.from(hash)];
const scriptSig = bitcoin.script.compile(commands);
// Create a virtual transaction to spend
const virtualToSpend = new bitcoin.Transaction();
virtualToSpend.version = 0;
virtualToSpend.addInput(Buffer.from(prevoutHash), prevoutIndex, sequence, scriptSig);
virtualToSpend.addOutput(script, 0);
// Create the PSBT
const virtualToSign = new bitcoin.Psbt({ network: bitcoin.networks.bitcoin });
virtualToSign.setVersion(0);
const prevTxHash = virtualToSpend.getHash();
const prevOutIndex = 0;
const toSignScriptSig = bitcoin.script.compile([bitcoin.script.OPS.OP_RETURN]);
try {
virtualToSign.addInput({
hash: prevTxHash,
index: prevOutIndex,
sequence: 0,
witnessUtxo: { script, value: 0 },
});
} catch (e) {
console.log(e);
throw e;
}
virtualToSign.addOutput({ script: toSignScriptSig, value: 0 });
return virtualToSign.toBase64();
}
```
### Step 5: Create the SignMessageViaTransaction Component
The `SignMessageViaTransaction` component handles the interaction with the wallet to sign the PSBT.
#### Step-by-Step Explanation:
1. **useDynamicContext**: Hook to access the primary wallet from the context. This provides information about the connected wallet.
2. **useState**: React hook to manage the message state. This allows us to keep track of the message that we want to sign.
3. **Check Wallet Connector**: Ensure the wallet connector supports Bitcoin. If the wallet does not support Bitcoin, we return `null` and do not render the component.
4. **signMessageViaTransaction**: Function to generate the PSBT, request the wallet to sign it, and handle the signed PSBT. This function includes:
* **Get Address**: Get the Bitcoin address from the wallet.
* **Generate PSBT**: Call the `generatePsbt` function to create the PSBT.
* **Sign PSBT**: Request the wallet to sign the PSBT using the provided parameters.
* **Handle Signed PSBT**: Log the signed PSBT or handle any errors that occur during signing.
```javascript
const SignMessageViaTransaction = () => {
const { primaryWallet } = useDynamicContext();
const [message, setMessage] = useState('Hello World');
if (!isBitcoinWallet(primaryWallet)) return null;
const signMessageViaTransaction = async () => {
// Get the Bitcoin address from the wallet
const address = await primaryWallet.getAddress();
// Generate the PSBT
const psbt = generatePsbt(address, message);
// Define the parameters for signing the PSBT
const params = {
allowedSighash: [1], // Only allow SIGHASH_ALL
unsignedPsbtBase64: psbt, // The unsigned PSBT in Base64 format
signature: [{
address, // The address that is signing
signingIndexes: [0] // The index of the input being signed
}]
};
try {
// Request the wallet to sign the PSBT
const signedPsbt = await primaryWallet.signPsbt(params);
console.log(signedPsbt); // Log the signed PSBT
} catch (e) {
console.log(e); // Handle any errors that occur during signing
}
}
return (
)
}
```
### Step 6: Create the Main Component
The `Main` component renders the `DynamicWidget` for wallet connection and the `SignMessageViaTransaction` component.
#### Step-by-Step Explanation:
1. **DynamicWidget**: This component handles the wallet connection UI, allowing users to connect their wallets.
2. **SignMessageViaTransaction**: This component handles the signing of the PSBT via the connected wallet.
```javascript
const Main = () => {
return (
{...}
```
# EIP-5792
Source: https://docs.dynamic.xyz/wallets/using-wallets/evm/eip-5792
Learn how to use EIP-5792
## Standard
[EIP-5792](https://eips.ethereum.org/EIPS/eip-5792) defines a standard for smart contract wallets that introduced new JSON-RPC methods. These methods allow
batched, gas-sponsored, and conditional transactions through a simple interface.
These endpoints make it easier for dapps and wallets to interact with smart accounts without needing to understand account abstraction internals like ERC-4337.
EIP-5792 introduced the following functions:
* wallet\_getCapabilities
* wallet\_sendCalls
* wallet\_getCallsStatus
* wallet\_showCallsStatus
## Support
As of 04/2025 EIP-5792 is still rolling out, and you can find a list of wallets that support it [here](https://www.eip5792.xyz/ecosystem/wallets).
The example below show how to handle `wallet_getCapabilities` for atomic (batch transactions) and paymaster support, and sendCalls with for a batched transaction.
## Example
```tsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { parseEther } from 'viem';
...
const { primaryWallet} = useDynamicContext();
...
const signAtomicSponsoredTransactionExample = async () => {
if (primaryWallet) {
const chainId = (await primaryWallet.getNetwork());
const walletClient = await primaryWallet.getWalletClient();
const capabilities = await walletClient.getCapabilities();
if (capabilities && capabilities[chainId]) {
const chainCapabilities = capabilities[chainId];
const paymasterServiceSupported = chainCapabilities.paymasterService?.supported;
const atomicStatusSupported = chainCapabilities.atomic && (chainCapabilities.atomic.status == 'ready' || chainCapabilities.atomic.status == 'supported');
if (!atomicStatusSupported) {
console.log('atomic is not supported for chainId:', chainId);
return;
}
if (!paymasterServiceSupported) {
console.log('paymaster is not supported for chainId:', chainId);
}
const callParams = {
calls: [
{
to: '0x58e2C06939056c2fC760bE062Ef6dbbbCD4045e3',
value: parseEther('0.001')
},
{
to: '0x58e2C06939056c2fC760bE062Ef6dbbbCD4045e3',
value: parseEther('0.001')
},
]
};
if (paymasterServiceSupported) {
callParams.capabilities = {
paymasterService: {
url: undefined
}
};
}
const result = await walletClient.sendCalls(callParams);
return result;
}
}
};
```
# EVM Wallets
Source: https://docs.dynamic.xyz/wallets/using-wallets/evm/evm-wallets
There are methods in the Ethereum wallet specific to EVM which we list below, but in general all the methods you need are present on the generic Wallet [described here](/wallets/using-wallets/interacting-with-wallets).
## Check if a wallet is an Ethereum wallet
You can use the `isEthereumWallet` helper method to check if a wallet is a Ethereum wallet. That way, TypeScript will know which methods are available to you.
```ts
import { isEthereumWallet } from '@dynamic-labs/ethereum';
if (!isEthereumWallet(wallet)) {
throw new Error('This wallet is not a Ethereum wallet');
}
const client = await primaryWallet.getWalletClient();
```
## Ethereum Wallet Methods
| Method | Description |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| getPublicClient(): Promise\> | Retrieves the public client. |
| getWalletClient(chainId?: string): Promise\> | Retrieves the wallet client. |
| isAtomicSupported(chainId?: number): Promise\ | If the wallet supports atomic actions (EIP-5792). |
| isPaymasterServiceSupported(chainId?: number): Promise\ | If the wallet supports paymaster services (EIP-5792). |
| sendCalls(callParams: Omit\, options?: \{ paymasterURL?: string }): Promise\ | Sends multiple transactions atomically. Requires EIP-5792 support. |
### Read only actions
If you want to read data from the blockchain, you will want either a ["Public Client"](https://viem.sh/docs/clients/public.html) (Viem terminology), or a ["Provider"](https://docs.ethers.org/v5/getting-started/#getting-started--glossary) (Ethers terminology). Both allow you read only access to the blockchain.
```jsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const { primaryWallet } = useDynamicContext();
const getEnsName = async () => {
const publicClient = await primaryWallet?.getPublicClient()
// Now you can use the public client to read data from the blockchain
const ens = await publicClient?.getEnsName({ address: primaryWallet.address })
return ens
}
```
```jsx
import { getWeb3Provider } from '@dynamic-labs/ethers-v6';
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const { primaryWallet } = useDynamicContext();
const getBalance = async () => {
const provider = await getWeb3Provider(primaryWallet);
// Now you can use the provider to read data from the blockchain
const balance = await provider?.getBalance(primaryWallet.address);
return balance
}
```
### Write actions
If you want to write data to the blockchain, you will need a ["Wallet Client"](https://viem.sh/docs/clients/wallet.html) (Viem terminology), or a ["Signer"](https://docs.ethers.io/v5/api/signer/) (Ethers terminology). Both allow you to sign transactions with the private key.
```jsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isEthereumWallet } from '@dynamic-labs/ethereum';
const { primaryWallet } = useDynamicContext();
const sendTransaction = async () => {
if(!primaryWallet || !isEthereumWallet(primaryWallet)) {
return;
}
const walletClient = await primaryWallet.getWalletClient();
// Now you can use the wallet client to write data to the blockchain
const tx = await walletClient?.sendTransaction({
to: '0x1234567890abcdef',
value: '1000000000000000000'
});
return tx
}
```
```jsx
import { getSigner } from '@dynamic-labs/ethers-v6';
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const { primaryWallet } = useDynamicContext();
const sendTransaction = async () => {
const signer = await getSigner(primaryWallet);
// Now you can use the signer to write data to the blockchain
const tx = await signer?.sendTransaction({
to: '0x1234567890abcdef',
value: '1000000000000000000'
});
return tx
}
```
## Send multiple transactions atomically
If you want to send multiple transactions atomically, you can use the `sendCalls` method. This requires the wallet to support EIP-5792.
```jsx
import { parseEther } from 'viem';
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isEthereumWallet } from '@dynamic-labs/ethereum';
const { primaryWallet } = useDynamicContext();
const sendTransactions = async () => {
if(!primaryWallet || !isEthereumWallet(primaryWallet) || !primaryWallet.isAtomicSupported()) {
return;
}
// Now you can use the wallet client to write data to the blockchain
const { id } = await primaryWallet.sendCalls({
calls: [
{
to: '0x1111111111111111111111111111111111111111',
value: parseEther('0.001'),
},
{
to: '0x2222222222222222222222222222222222222222',
value: parseEther('0.001'),
},
],
version: '2.0.0',
});
return id
}
```
## Examples
We've included a few examples of how to use the EVM wallet connector in this section:
* [Get balance for all connected wallets](/wallets/using-wallets/evm/get-balance-for-all-wallets)
* [Get balance for a single wallet](/wallets/using-wallets/evm/get-wallet-balance)
* [Send a transaction](/wallets/using-wallets/evm/send-a-transaction)
* [Send a transaction with Wagmi](/wallets/using-wallets/evm/send-a-transaction-wagmi)
* [Send balance using embedded wallet](/wallets/using-wallets/evm/send-balance)
* [Sign a message](/wallets/using-wallets/evm/sign-a-message)
# Get balance for all wallets
Source: https://docs.dynamic.xyz/wallets/using-wallets/evm/get-balance-for-all-wallets
In this example, we will get the balance for each connected wallet.
For each wallet, we will get the provider with [useRpcProviders](/react-sdk/hooks/userpcproviders), to fetch the
balance by calling the `getBalance` with the wallet address.
```JavaScript
import { useUserWallets } from '@dynamic-labs/sdk-react-core';
import { useRpcProviders } from '@dynamic-labs/sdk-react-core'
import { evmProvidersSelector } from '@dynamic-labs/ethereum-core'
const App = () => {
const userWallets = useUserWallets();
const { defaultProvider } = useRpcProviders(evmProvidersSelector)
useEffect(() => {
userWallets.forEach(async (wallet) => {
if (!wallet) return;
// Get the EVM Mainnet provider
const provider = defaultProvider?.provider;
if (!provider) return;
// Fetch the wallet balance
const balance = await provider.getBalance({ address: wallet.address });
console.log('balance', balance.toString());
});
}, [userWallets, defaultProvider]);
...
}
```
# Send a transaction on Ethereum/EVM
Source: https://docs.dynamic.xyz/wallets/using-wallets/evm/send-a-transaction
```tsx
import { FC, FormEventHandler, useState } from "react";
import { parseEther } from "viem";
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
import { isEthereumWallet } from "@dynamic-labs/ethereum";
export const SendTransactionSection: FC = () => {
const { primaryWallet } = useDynamicContext();
const [txnHash, setTxnHash] = useState("");
if (!primaryWallet || !isEthereumWallet(primaryWallet)) return null;
const onSubmit: FormEventHandler = async (event) => {
event.preventDefault();
const formData = new FormData(event.currentTarget);
const address = formData.get("address") as string;
const amount = formData.get("amount") as string;
const publicClient = await primaryWallet.getPublicClient();
const walletClient = await primaryWallet.getWalletClient();
const transaction = {
to: address,
value: amount ? parseEther(amount) : undefined,
};
const hash = await walletClient.sendTransaction(transaction);
setTxnHash(hash);
const receipt = await publicClient.getTransactionReceipt({
hash,
});
console.log(receipt);
};
return (
);
};
```
# Mint an NFT on EVM with Wagmi
Source: https://docs.dynamic.xyz/wallets/using-wallets/evm/send-a-transaction-wagmi
```jsx
import { FC } from 'react';
import {
useContractWrite,
usePrepareContractWrite,
useWaitForTransaction,
} from 'wagmi';
export const ContractWriteSection: FC = () => {
const { config } = usePrepareContractWrite({
abi: [
{
inputs: [],
name: 'mint',
outputs: [],
stateMutability: 'nonpayable',
type: 'function',
},
] as const,
address: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
functionName: 'mint',
});
const { data, write } = useContractWrite(config);
const { isLoading, isSuccess } = useWaitForTransaction({
hash: data?.hash,
});
return (
);
};
```
# Sign a message in Ethereum/EVM
Source: https://docs.dynamic.xyz/wallets/using-wallets/evm/sign-a-message
In this example, we are creating a button to sign a message and log the signature to the console.
```JavaScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const SignMessageButton = () => {
const { primaryWallet } = useDynamicContext();
const signMessage = async () => {
if (!primaryWallet) return;
const signature = await primaryWallet.signMessage('example');
console.log('signature', signature);
};
return ;
};
```
# Fetch all token balances for a wallet
Source: https://docs.dynamic.xyz/wallets/using-wallets/general/get-token-balances
The Dynamic UI components (DynamicWidget and UserProfile) have a built in UI for displaying multi asset balances, we strongly recommend using those components if you can! Learn more in [the Multi-Asset UI section](/wallets/multi-asset).
Token balance are currently supported on: Ethereum, Worldchain, Shape, Zksync, Optimism, Polygon, Geist, Arbitrum, Blast, Linea, Base, Scroll, Gnosis, BNB, Avalanche, Apechain, Lens, Soneium, Rootstock, Abstract, Settlus, Ink, Solana, Bitcoin runes
## Hook
You can fetch token balances for a user's wallet using the `useTokenBalances` hook:
```jsx
import { useTokenBalances } from "@dynamic-labs/sdk-react-core";
const { tokenBalances, isLoading, isError, error } = useTokenBalances();
```
## Return Value
This hook returns an object for `tokenBalances` with the following properties:
| Property | Type | Description |
| ---------- | ------- | ---------------------------------------------------------------------- |
| networkId | integer | The network ID of the token i.e. 1 for Ethereum, 137 for Polygon, etc. |
| address | string | The address of the token. |
| name | string | The name of the token. |
| symbol | string | The symbol of the token. |
| decimals | integer | The number of decimals the token has. |
| logoURI | string | The URI of the token's logo image. |
| balance | float | The balance of the token in the user's wallet. |
| rawBalance | integer | The raw balance of the token in the user's wallet. |
## Reference
You can find the full reference for the `useTokenBalances` hook [here](/react-sdk/hooks/usetokenbalances).
## Full Example
```jsx
import { useDynamicContext, useTokenBalances } from "@dynamic-labs/sdk-react-core";
const Balances = () => {
const { primaryWallet } = useDynamicContext();
const { tokenBalances, isLoading, isError, error } = useTokenBalances();
if(!primaryWallet) return
| Field | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| additionalAddresses: WalletAdditionalAddress\[] | Additional addresses associated to the wallet (e.g. ordinals and payment addresses for bitcoin wallets) |
| address: string | Public address of the connected wallet |
| chain: string | Current BlockChain name (e.g: 'ETH', 'SOL', 'BTC', etc) |
| connector: WalletConnector | The wallet connector object |
| id: string | The wallet's unique id (matches thw wallet verified credential on connect-anf-sign) |
| isAuthenticated: boolean | True if the user is authenticated, otherwise it's false |
| key: string | The wallet key (e.g. metamask, phantom, etc) |
| Method | Description |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| getBalance(): Promise\ | Retrieves the balance of the wallet. |
| getNameService(): Promise\ | Retrieves the name service data associated with the wallet. |
| getNetwork(): Promise\ | Retrieves the network value. (e.g: 1, 137, 'mainnet') |
| isConnected(): Promise\ | If the wallet is connected. |
| proveOwnership(messageToSign: string): Promise\ | Proves ownership of the wallet by signing a message. |
| signMessage(messageToSign: string): Promise\ | Signs a message using the wallet. |
| switchNetwork(networkChainId: number \| string): Promise\ | Switches the network that the wallet is connected to. |
| sync(): Promise\ | Prompts the user to reconnect the wallet if not connected and only resolves when the wallet is connected and active. |
### WalletConnector Interface
The connector is akin to the wallet provider itself i.e. Metamask, Phantom, etc. It is abstracted away from any single account. Therefore you'll find methods and props that are relevant to the wallet provider itself like isInstalledOnBrowser, or getDeepLink.
Below we outline the props and methods for a wallet connector object no matter what chain the account belongs to. In each chain specific section, we also outline the props and methods for a wallet connector object for that chain.
| Field | Description |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| canConnectViaCustodialService: boolean | If the wallet needs to be connected via a custodial service such as Blocto, this will be true. |
| canConnectViaQrCode: boolean | If the wallet is not installed, and can be connected via a QR code, this will be true. |
| canConnectViaSocial: boolean | Whether this connector can be connected via social login. |
| chainRpcProviders: typeof ChainRpcProviders \| undefined | The RPC providers for the chain the wallet is connected to |
| connectedChain: Chain | The chain this wallet is connected to |
| endSession(): Promise\ | Close the wallet connection |
| getAddress(opts?: GetAddressOpts): Promise\ | Get the public address of the wallet |
| getAdditionalAddresses(mainAddress?: string): Promise\ | Get the additional addresses of the wallet, given the main address |
| getConnectedAccounts(): Promise\ | Get the address silently |
| getDeepLink(): string \| undefined | Get the deep link of the wallet |
| getMobileOrInstalledWallet(): WalletConnector | Whether the wallet connector should fall back to a different wallet connector |
| getNetwork(): Promise\ | Get the current network of the wallet |
| getSession(): unknown \| Promise\ | Get the session for the wallet |
| isAvailable: boolean | If the wallet provider is available (i.e. Metamask is not installed) |
| isEmbeddedWallet: boolean | If the wallet generated by a valid embedded wallet provider |
| isInitialized: boolean | Whether the connector has been initialized |
| isInstalledOnBrowser(): boolean | Check if the wallet is installed on the browser |
| isWalletConnect: boolean | Flag if it is wallet Connect |
| key: string | Override key or the normalized wallet name if needed |
| proveOwnership(messageToSign: string): Promise\ | In most cases this is an alias for `signMessage` |
| providerResources: string\[] \| undefined | Additional resources to add to the message to be signed |
| supportsNetworkSwitching():boolean | Whether the wallet supports network switching |
| switchNetworkOnlyFromWallet: boolean \| undefined | Requires switching network in the wallet itself |
## Chain specific interfaces
* [EVM Interactions](/wallets/using-wallets/evm/evm-wallets)
* [Bitcoin Interactions](/wallets/using-wallets/bitcoin/bitcoin-wallets)
* [Solana Interactions](/wallets/using-wallets/solana/solana-wallets)
* [Sui Interactions](/wallets/using-wallets/sui/sui-wallets)
# Configure Web3.js Connection
Source: https://docs.dynamic.xyz/wallets/using-wallets/solana/configure-custom-connection
Modify Web3.js Connection to your unique needs.
## Configurable Wallet Connectors
In some cases you would want to override the default settings of the Web3.js Connection.
Dynamic allows you do to so by passing [`SolanaConnectionConfig`](https://solana.com/docs/clients/javascript-reference#connection) prop and an additional `customRpcUrls` property to `SolanaWalletConnectorsWithConfig`
For example:
```jsx
import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
import { SolanaWalletConnectorsWithConfig } from '@dynamic-labs/solana';
{...}
```
# Gasless Transactions on Solana
Source: https://docs.dynamic.xyz/wallets/using-wallets/solana/gasless-transactions
## Introduction
In this guide, we'll show you how to create Solana transactions where a fee payer wallet pays the gas fees instead of your users. We achieve this by partially signing the transaction on the server and sending it to the client for final signing.
## Getting Started
### Setting up the Project
We'll use Next.js for this example since we can then keep the frontend and the API route together. To get started, create a new project with:
```shell
npx create-dynamic-app@latest gasless-solana
```
If you already have a Next.js app, simply follow our [quickstart guide](/quickstart) to add the Dynamic SDK.
### Setting Up the Fee Payer Wallet
You'll need a wallet that will pay for gas fees on behalf of your users:
1. Create a Solana wallet and add some funds to it (for paying gas fees)
2. Add its private key (string format) to your `.env.local` file:
```env .env.local
FEE_PAYER_PRIVATE_KEY=your_private_key_here
NEXT_PUBLIC_RPC=https://api.devnet.solana.com
```
Never share your private key or commit it to your code repository. Always use environment variables and add them to your `.gitignore`.
## Server Implementation
### Creating the API Route
Now we'll create an API route that will prepare partially-signed transactions. Create a file at `app/api/gas/route.ts`:
```typescript app/api/gas/route.ts
import {
createTransferCheckedInstruction,
getAssociatedTokenAddress,
createAssociatedTokenAccountInstruction,
} from "@solana/spl-token";
import { Connection, Keypair, PublicKey, Transaction } from "@solana/web3.js";
import { NextRequest, NextResponse } from "next/server";
import bs58 from "bs58";
export const dynamic = "force-dynamic";
// This is a USDC token address on devnet - replace with your token address if needed
const USDC_MINT = new PublicKey("Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr");
const RPC_URL = process.env.NEXT_PUBLIC_RPC || "https://api.devnet.solana.com";
const PRIVATE_KEY = process.env.FEE_PAYER_PRIVATE_KEY || "";
export async function POST(request: NextRequest) {
try {
// Get data from the request
const body = await request.json();
const { senderAddress, recipientAddress, amount } = body;
// Basic validation
if (!senderAddress || !recipientAddress || !amount) {
return NextResponse.json(
{ success: false, message: "Missing required parameters" },
{ status: 400 }
);
}
if (!PRIVATE_KEY) {
return NextResponse.json(
{
success: false,
message: "Missing fee payer private key in environment variables",
},
{ status: 500 }
);
}
const connection = new Connection(RPC_URL, "confirmed");
// Set up the fee payer wallet
const privateKeyBuffer = bs58.decode(PRIVATE_KEY);
const feePayer = Keypair.fromSecretKey(new Uint8Array(privateKeyBuffer));
// Convert addresses to PublicKey objects
let sender: PublicKey;
let recipient: PublicKey;
try {
sender = new PublicKey(senderAddress);
recipient = new PublicKey(recipientAddress);
} catch (error) {
return NextResponse.json(
{ success: false, message: "Invalid Solana address" },
{ status: 400 }
);
}
// Get token accounts for sender and recipient
const senderTokenAccount = await getAssociatedTokenAddress(
USDC_MINT,
sender
);
const recipientTokenAccount = await getAssociatedTokenAddress(
USDC_MINT,
recipient
);
const recipientTokenInfo = await connection.getAccountInfo(
recipientTokenAccount
);
const instructions = [];
// Create recipient token account if it doesn't exist
if (!recipientTokenInfo) {
instructions.push(
createAssociatedTokenAccountInstruction(
feePayer.publicKey,
recipientTokenAccount,
recipient,
USDC_MINT
)
);
}
// Add transfer instruction
instructions.push(
createTransferCheckedInstruction(
senderTokenAccount,
USDC_MINT,
recipientTokenAccount,
sender,
BigInt(amount),
6
)
);
// Create and partially sign transaction
const { blockhash, lastValidBlockHeight } =
await connection.getLatestBlockhash("confirmed");
const transaction = new Transaction();
transaction.recentBlockhash = blockhash;
transaction.lastValidBlockHeight = lastValidBlockHeight;
transaction.feePayer = feePayer.publicKey;
instructions.forEach((instruction) => transaction.add(instruction));
transaction.partialSign(feePayer);
// Serialize the transaction to send back to client
const serializedTransaction = bs58.encode(
transaction.serialize({
requireAllSignatures: false,
verifySignatures: false,
})
);
return NextResponse.json({
success: true,
serializedTransaction,
message: transaction.serializeMessage().toString("base64"),
});
} catch (error) {
return NextResponse.json(
{
success: false,
message:
error instanceof Error ? error.message : "Unknown error occurred",
},
{ status: 500 }
);
}
}
```
### How It Works
Our API route:
1. Receives details about the transfer (who's sending, receiving, and how much)
2. Creates a transaction with the instructions
3. Sets our server wallet as the fee payer
4. Partially signs the transaction with the fee payer wallet
5. Returns the transaction to the frontend
## Client Implementation
### Creating the Frontend Component
Now let's create a simple UI for users to send tokens without paying gas. Create `app/components/Send.tsx`:
```tsx app/components/Send.tsx
import { useDynamicContext, useIsLoggedIn } from "@dynamic-labs/sdk-react-core";
import { isSolanaWallet } from "@dynamic-labs/solana";
import { useState } from "react";
import { PublicKey, Transaction } from "@solana/web3.js";
import bs58 from "bs58";
import "./Send.css";
export default function Send() {
const isLoggedIn = useIsLoggedIn();
const { primaryWallet } = useDynamicContext();
const [isLoading, setIsLoading] = useState(false);
const [result, setResult] = useState("");
const [recipientAddress, setRecipientAddress] = useState("");
const [amount, setAmount] = useState("");
const [txSignature, setTxSignature] = useState(null);
const sendUSDC = async () => {
if (!primaryWallet || !isSolanaWallet(primaryWallet)) {
setResult("Wallet not connected or not a Solana wallet");
return;
}
if (!recipientAddress || !amount) {
setResult("Please enter recipient address and amount");
return;
}
try {
setIsLoading(true);
setResult("Preparing transaction...");
// Validate recipient address
let toAddress: PublicKey;
try {
toAddress = new PublicKey(recipientAddress);
} catch (error) {
setResult("Invalid recipient address");
setIsLoading(false);
return;
}
// Convert amount to USDC units (6 decimals)
const amountInUsdcUnits = parseFloat(amount) * 1_000_000;
// Call our API to prepare the transaction
const response = await fetch("/api/gas", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
senderAddress: primaryWallet.address,
recipientAddress: toAddress.toString(),
amount: amountInUsdcUnits,
}),
});
const responseData = await response.json();
if (!response.ok) {
throw new Error(
responseData.message || "Failed to prepare transaction"
);
}
// Get signer from wallet and the prepared transaction
const { serializedTransaction } = responseData;
const signer = await primaryWallet.getSigner();
setResult("Please sign the transaction...");
try {
// Have the user sign and send the transaction
setResult("Signing transaction...");
const transaction = Transaction.from(
bs58.decode(serializedTransaction)
);
const { signature } = await signer.signAndSendTransaction(transaction);
setTxSignature(signature);
setResult(`USDC transfer successful!`);
} catch (err) {
setTxSignature(null);
setResult(
`Error signing transaction: ${
err instanceof Error ? err.message : String(err)
}`
);
}
} catch (error) {
setTxSignature(null);
setResult(
`Error: ${error instanceof Error ? error.message : String(error)}`
);
} finally {
setIsLoading(false);
}
};
return (
{result && (
)}
)}
);
}
```
> For styling, create the Send.css file and you can find the styles we used [here](https://github.com/dynamic-labs/gasless-solana/blob/main/app/components/Send.css).
### Using the Component
Finally, add the component to your main page in `app/page.tsx`:
```tsx app/page.tsx
| Retrieves the RPC connection |
| getSigner(): Promise\ | Retrieves the solana signer for the wallet. |
## Examples
You can find examples of how to interact with Solana wallets in the examples section:
* [Send a Legacy Solana Transaction](/wallets/using-wallets/solana/send-legacy-solana-transaction).
* [Send a Versioned Solana Transaction](/wallets/using-wallets/solana/send-versioned-solana-transaction).
# Send A Sui Transaction
Source: https://docs.dynamic.xyz/wallets/using-wallets/sui/send-sui-transaction
```tsx
import { FC, FormEventHandler, useState } from 'react';
import { Transaction } from '@mysten/sui/transactions';
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isSuiWallet } from '@dynamic-labs/sui';
const MIST_PER_SUI = 1_000_000_000;
export const SendTransactionSection: FC = () => {
const { primaryWallet } = useDynamicContext();
const [txSignature, setTxSignature] = useState('');
if (!primaryWallet || !isSuiWallet(primaryWallet)) return null;
const onSubmit: FormEventHandler = async (event) => {
event.preventDefault();
const formData = new FormData(event.currentTarget);
const address = formData.get('address') as string;
const amount = Number(formData.get('amount')) * MIST_PER_SUI;
const walletClient = await primaryWallet.getSuiClient();
const tx = new Transaction();
tx.setSender(primaryWallet.address);
tx.setGasPrice(1_000);
tx.setGasBudget(10_000_000);
// Split the gas coin to create a new coin with the specified amount
const [coin] = tx.splitCoins(tx.gas, [amount]);
// Transfer the new coin to the recipient
tx.transferObjects([coin], address);
const signedTransaction = await primaryWallet.signTransaction(tx);
const executionResult = await walletClient?.executeTransactionBlock({
options: {},
signature: signedTransaction.signature,
transactionBlock: signedTransaction.bytes,
});
console.log(executionResult);
setTxSignature(executionResult?.digest || 'No transaction digest found');
};
return (
);
};
```
# Sui Wallets
Source: https://docs.dynamic.xyz/wallets/using-wallets/sui/sui-wallets
## Introduction
The Sui wallet connectors will generally have a couple of extra methods to simplify interactions with Sui wallets.
## Checking if a Wallet is a Sui Wallet
You can use the `isSuiWallet` helper method to check if a wallet is a Sui wallet. That way, TypeScript will know which methods are available to you.
```ts
import { isSuiWallet } from '@dynamic-labs/sui';
if (!isSuiWallet(wallet)) {
throw new Error('This wallet is not a Sui wallet');
}
```
## SuiWallet Class
We expose multiple helper methods that make it easier to interact with Sui wallets
while maintaining consistency with familiar patterns.
### `getSuiClient`
**Params**: none
**Returns**: Promise\<[SuiClient](https://sdk.mystenlabs.com/typedoc/classes/_mysten_sui.client.SuiClient.html) | undefined>
This method will return a Sui client with an RPC url already configured for the active network.
### `getWalletAccount`
**Params**: none
**Returns**: Promise\<[WalletAccount](https://docs.sui.io/standards/wallet-standard#managing-wallets) | undefined>
This method will return the currently active [WalletAccount](https://docs.sui.io/standards/wallet-standard#managing-wallets).
### `getActiveNetwork`
**Params**: none
**Returns**: Promise\
The active network will usually be one of the following:
* `sui:mainnet`
* `sui:testnet`
* `sui:devnet`
* `sui:localnet`
## Examples
You can find examples of how to interact with Sui wallets in the examples section:
* [Send a Sui Transaction](/wallets/using-wallets/sui/send-sui-transaction)
)
```
### Socials
#### Show users linked social accounts, allow linking/unlinking
How: useSocialAccounts hook from sdk-react-core
Hook/Component: [useSocialAccounts](/react-sdk/hooks/usesocialaccounts)
Notes: None
```jsx
import { useSocialAccounts } from "@dynamic-labs/sdk-react-core";
import { SocialIcon } from '@dynamic-labs/iconic';
const Avatar = ({ avatarUrl }) => {
return (
);
};
const Icon = ({ provider }) => {
return (
{isProviderLinked ? (
) : (
)}
);
};
const Socials = () => {
const providers = [
"discord",
"facebook",
"github",
"google",
"instagram",
"twitch",
"twitter",
];
return (
{providers.map((provider) => (
);
};
```
# Headless Wallet Management
Source: https://docs.dynamic.xyz/headless/headless-wallet-management
This guide covers how to implement the wallet aspect of the Dynamic Widget UI Component but using only our SDK hooks and your own UI implementation.
## Prerequisites
Like with all this series of headless guides, "headless" is defined a way to use the Dynamic SDK without the need for Dynamic UI components (i.e. DynamicWidget, DynamicUserProfile).
You still need to add the SDK and set up the Dynamic Context Provider (complete [the quickstart](/quickstart) if you haven't done so already, or refer to [an example app](/example-apps))
## Signup/Login
### Fetch available wallets
You can find the list of available wallets in the `walletOptions` prop returned by the [useWalletOptions hook](/react-sdk/hooks/usewalletoptions).
When browsing wallets in the Dynamic Widget, you might see labels beside them like "Last Used", "Multichain" or "Recommended".
Last used comes from the "dynamic\_last\_used\_wallet" value in localstorage.
"Multichain" comes from the `chainGroup` node in each wallet (Remember to also add [the WalletConnectors](/chains/enabling-chains#enabling-a-chain-network) for each chain).
"Recommendeded" from [the Recommended Wallets feature](/wallets/advanced-wallets/recommend-wallets).
### Display a wallet icon
Use the `@dynamic-labs/wallet-book` library to display a wallet icon using the exported `WalletIcon` component. This component takes a `walletKey` prop, which is the key of the wallet you want to display.
```tsx
import { WalletIcon } from '@dynamic-labs/wallet-book'
const WalletIconComponent = () => {
return
// Per wallet setting
```
### How do I control whether the user must have an enabled network available in their wallet before connecting?
You can control how the SDK enforces wallet networks using the `networkValidationMode` prop. Available options are:
* `'always'` - requires the wallet to be on an enabled network while connecting and during the session
* `'sign-in'` - only enforces the network on connect
* `'never'` - turns off network validation
```jsx
```
### How do I hide something in the Dynamic Widget?
The easiest way to hide something is to use [custom CSS directly](/design-customizations/css/custom-css).
### How do I control what wallets are shown for wallet login?
1. Via the [chains/networks you enable in the dashboard](/chains/enabling-chains) (don't forget to add the correct wallet connectors too).
2. Filter or sort the wallets using [our various sort and filter methods](/wallets/advanced-wallets/sort-and-filter-wallets).
3. Create tabs using [the Wallet List feature](/react-sdk/objects/views#wallet-list) (see what this looks like on Magic Eden!).
### How do I track visitors in the dashboard when using connect-only mode?
This commonly happens when you have not set
[enableVisitTrackingOnConnectOnly](/react-sdk/providers/dynamiccontextprovider#enablevisittrackingonconnectonly) to true.
### How can I change the order of my social login options?
You can change the order of your social login options by using [the `socialProvidersFilter` prop](/react-sdk/providers/dynamiccontextprovider#socialprovidersfilter). This is a function that takes an array of social providers and returns a new array with the providers in the order you want.
### How can I trigger social login via redirect vs a popup?
[The `social` prop](/react-sdk/providers/dynamiccontextprovider#social) on the `DynamicContextProvider` take a `strategy` field whose value can be set to `'redirect'` or `'popup'`.
### How can I hide specific tokens from the balance view
Use [the tokenFilter prop](/react-sdk/providers/dynamiccontextprovider#tokenfilter) on the DynamicContextProvider
### How do I know when to move from Sandbox to Production?
Stay on sandbox while in testing, when you are ready to launch to your first users, move to Production.
Remember that Production comes with a blank slate of settings, and a new environmentId, so don't forget to update them.
# Welcome
Source: https://docs.dynamic.xyz/introduction/welcome
Welcome to Dynamic! We're so excited that you're here!
Our TSS-MPC offering is currently in closed alpha - [contact us](https://www.dynamic.xyz/join-slack) for early access or to learn more.
### Versioning
This documentation is for V4 of the SDK. Therefore we assume you have [the latest version of V4](https://www.npmjs.com/package/@dynamic-labs/sdk-react-core?activeTab=versions) installed.
If you are looking for V3, please go [here](https://v3.docs.dynamic.xyz)
Please also make sure you have all @dynamic/labs packages on exactly the same version to avoid any issues, and use [Dynamic Doctor](/troubleshooting/dynamic-doctor) for easy debugging. Happy building!
### What is Dynamic?
Dynamic offers smart and beautiful login flows for crypto-native users, simple
onboarding flows for everyone else, and powerful developer tools that go beyond
authentication.
Watch a product walkthrough
Play around with the SDK
Get up and running in minutes
Be part of the Dynamic Slack group
#### Common Docs
Some of the common next steps after completing the quickstart etc. above are:
* [Configuring the Signup page](/design-customizations/signup-login)
* [Start interacting with wallets](/wallets/using-wallets/interacting-with-wallets)
* [Customizing the look and feel of the UI](/design-customizations)
* [Adding custom EVM Networks](/chains/evmNetwork)
* [Collecting custom information](/custom-fields/overview)
* [Adding smart wallet support](/smart-wallets/add-smart-wallets)
#### Support & Feedback
You can reach out to us at any time for questions, issues, concerns, product
ideas, or random thoughts. Here are some ways to do so:
Join our Slack community
Send us a tweet or DM us any time.
Email us at [hello@dynamic.xyz](mailto:hello@dynamic.xyz)
Bug our founders at any point at [founders@dynamic.xyz](mailto:founders@dynamic.xyz) (tell us anything that's on your mind - the good and the bad).
# Migrating to Dynamic
Source: https://docs.dynamic.xyz/migrations/migration-guide
Migration from one auth and embedded wallet provider to another can seem daunting. You have users, they might have wallets, and a subset of them will have assets in their wallets, making it a fun adventure of a migration. But have no fear! We can help. Below, we put together a guide on migration strategies you can think through depending on your use case. At the end of the guide you'll also find some helpful tips and techniques to ensure the migration all goes smoothly.
When in doubt, talk to us. Migrations can get complex, and we'd love to help
guide you through them. You can [set up a call with us
here](https://www.dynamic.xyz/talk-to-us)
If you don't want to migrate yet, but want to take advantage of Dynamic on top of your existing provider, you can also use [our Third Party Authentication feature](/authentication-methods/third-party-auth).
We put together a simple flow chart to help you identify the right migration strategy:
## Migration Path A: You only have a front-end "connect wallet" flow
### Common scenarios
You built your own front end wallet connector or use Rainbowkit/ConnectKit. There is no SIWE, no issuing JWTs, and mostly just a front end.
### Recommended approach
You pretty much just swap out the modals. If you use wagmi, add our [wagmi connector](/react-sdk/using-wagmi#-install-wagmi) and follow our [rainbowkit guide](/migrations/tutorials/rainbowkit), but in general, no migration needed. After the initial update to the Dynamic modal, you can stay on our [connect-only mode](/wallets/advanced-wallets/connect) and not store any user info with Dynamic, or alternatively start adding more sophisticated features.
## Migration Path B: You store wallet info somewhere and a wallet is a user
### Common scenarios
You built your own front end wallet connector or use Rainbowkit/ConnectKit, and in addition implemented a SIWE on your own, authenticating users and creating sessions for them.
### Recommended approach
For front end changes, you can follow path A above. In addition, you can use our [create wallet](https://docs.dynamic.xyz/api-reference/wallets/createWallet) endpoint to generate users and add wallet records to them. When they first log in, they will verify wallet ownership via SIWE (we provide that and return a JWT - you don't need to do this), and you're done.
## Migration Path C: You have users, but no embedded wallets
### Common scenarios
You use Auth0, Firebase or another web2 user management system, or alternatively created something on your own. You store your users' emails and basic info.
### Recommended approach
You'll need to import your users into Dynamic
1. [Bulk upsert your users into Dynamic](https://docs.dynamic.xyz/api-reference/users/bulkCreateUser), including their info capture/kyc information and their data
2. For any profile information that Dynamic does not yet explicitly support, you can add these in the user.metadata, which is a key-value object
3. When they log in, we verify their emails
And that's it. You're done. When your users log in next time around, we will verify their email addresses/social login information independently as part of the auth flow, and issue a JWT once you have successfully logged in.
## Migration Path D: You have users, and they have embedded EOA wallets
### Common scenarios
You use an embedded wallets provider, or have built a simple KMS-based key management system on your own
### Recommended approach
**There are really two options here:**
1. Keep current users in their existing embedded wallets and generate Dynamic wallets for new users
2. Migrate existing wallet users to Dynamic
**Keep current users:**
1. Switch to Dynamic auth
2. When user logs in with email, check if they have an existing account:
* If so, redirect them to old login flow
* If they don't, create a Dynamic-powered embedded wallet for them
```typescript
import { useEmbeddedWallet } from "@dynamic-labs/sdk-react-core";
// component declaration and all other logic you might need
const { createEmbeddedWallet } = useEmbeddedWallet();
const onCreateWalletHandler = async () => {
try {
await createEmbeddedWallet();
} catch (e) {
console.error(e);
}
};
```
**Migrate users:**
1. You'll need to import your users into Dynamic (the previous section)
2. When a user logs in, check if they have a wallet in the previous system
3. Check if wallet was ever used/is empty
4. If it isn't, prompt user to transfer funds to new Dynamic wallet (this can feel like an account upgrade flow for the users)
5. Next time that the user logs in, they go to their Dynamic wallet
## Migration Path E: You have users, and they have AA wallets
### Considerations
1. Your users have an EOA embedded wallet, but it only serves as a signer for an AA layer (safe, zerodev etc).
2. Hence, you'll want to add the Dynamic-powered embedded wallet as a second signer to the AA layer, or alternatively swap signers from the old embedded wallet one to the Dynamic one
**Main activities**
You'll want to have the end user add their new Dynamic wallet as a second signer to the smart contract wallet, or alternatively have them replace the current signer with a second signer
**Steps**
This is non-trivial, and we recommend that we chat before starting this
process. [You can book time here](https://www.dynamic.xyz/talk-to-us)
## Extra Migration Techniques/Tips
### Asset Transfers
If your users have assets in their existing embedded wallets, then you'll want to ensure they move those over to their new Dynamic-powered embedded wallets. To do this, you'll want to build a migration flow for your users either using your own UI to prompt asset transfer (recommended), or by sending them to a tool such as [BulkSender](https://bulksender.app/).
### Webhooks
As you import your users into Dynamic, you may want to notify other systems and take further action - webhooks allow you to do exactly this. We have events such as user.created, user.updated, wallet.created and many more (find the full list [here](/developer-dashboard/eventTypes)).
Setting them up is as simple as providing a URL to post to [in the Dynamic Dashboard](https://app.dynamic.xyz/dashboard/developer/webhooks) and selecting which events you'd like to subscribe to (there's a full guide [here](/developer-dashboard/webhooks)).
# Migrating Users via CSV
Source: https://docs.dynamic.xyz/migrations/tutorials/importing
Dynamic.xyz offers a versatile platform for managing users and their associated data. If you're transitioning from another system, dynamic.xyz's API simplifies the process of migrating these users. The API is flexible and does not require any specific field to create a user, you only need at least one field. This guide will demonstrate how to migrate users from a data source, such as a CSV file, into dynamic.xyz's user management system using TypeScript.
### Step 1: Get an API Token
You'll first need to obtain an API token from the dynamic.xyz dashboard. Follow the instructions provided in the [API reference](https://docs.dynamic.xyz/api-reference/overview#get-an-api-token-from-dashboard) to get your token.
### Step 2: Prepare Your Data Source
Prepare a data source, such as a CSV file, with your users' data. In this guide, we'll use a CSV file as an example, but remember that you can use any data source that you can read programmatically. The file needs to contain at least one field for each user.
### Step 3: Write a Script to Send Requests
You can use a script to read from your data source and send POST requests to the dynamic.xyz create user API endpoint. Here's an example script in TypeScript using `axios` and `csv-parser`:
```typescript
import axios from "axios";
import fs from "fs";
import csv from "csv-parser";
// Replace with your actual API token and environment ID
const API_TOKEN = "YOUR_API_TOKEN";
const ENVIRONMENT_ID = "<>";
// URL for the API endpoint
const url = `https://app.dynamic.xyz/api/v0/environments/${ENVIRONMENT_ID}/users`;
// Set up headers for the request
const headers = {
"Content-Type": "application/json",
Authorization: `Bearer ${API_TOKEN}`,
};
// Open the CSV file and read the data
fs.createReadStream("users.csv")
.pipe(csv())
.on("data", async (row) => {
// Prepare the user data for the request
const user_data = {
field: row["field"], // replace 'field' with the actual field name from your CSV
};
// Send the POST request to the API
try {
const response = await axios.post(url, user_data, { headers });
console.log(
`User created successfully: ${JSON.stringify(response.data)}`
);
} catch (error) {
console.error(`Failed to create user. Error: ${error}`);
}
});
```
In the above TypeScript code, replace `'users.csv'` with the path to your actual data source, and replace `'YOUR_API_TOKEN'` and `'YOUR_ENVIRONMENT_ID'` with your actual API token and environment ID. Also, replace `'field'` with the name of the actual field you're using from your data source.
Please note that this is a basic script and does not handle errors robustly. In a production environment, you'd want to add error handling code to deal with potential issues such as network errors, API rate limits, and incorrect data in your data source.
Remember to install the necessary libraries if you haven't already done so:
```shell
npm install axios csv-parser
```
For more information on the user creation API endpoint, refer to the [API reference](https://docs.dynamic.xyz/api-reference/users/createUser).
# Migration from RainbowKit
Source: https://docs.dynamic.xyz/migrations/tutorials/rainbowkit
Rainbowkit is a popular wallet adapter library built on Wagmi. That said, it has several limitations in terms of flexibility, customizability etc. As your company scales, it makes sense to explore transitioning to Dynamic for wallet auth. In this guide, we'll cover how you can quickly swap out Rainbowkit for Dynamic.
### A few notes
1. Rainbowkit uses wagmi for all functions. Dynamic can leverage wagmi as well, requiring a quick connector to coordinate between the libraries.
2. Rainbowkit requires that you manage your own authentication. Dynamic, on the other hand, comes with auth built in and will return a JWT if you select the connect and auth option.
### Overview
To start, we will assume your current setup looks similar to this:
```jsx
const App = () => {
return (
);
};
```
In this setup, you have 3 dependencies:
1. Ethers.js
2. Wagmi
3. Rainbowkit
### Step 1: Set up the Dynamic SDK
```bash Shell
npm install @dynamic-labs/sdk-react-core
```
> 📘 Note: Dynamic comes with ethers.js as part of its package, meaning you can remove any independent ethers.js installation.
You can read the full Dynamic set up guide [here](/quickstart).
### Step 2: Set up the Dynamic Wagmi connector
```bash Shell
npm install @dynamic-labs/wagmi-connector
```
You can read the full wagmi guide [here](/react-sdk/using-wagmi).
### Step 3: Configure Dynamic instead of Rainbowkit
#### Replace `RainbowKitProvider` with `DynamicContextProvider`
> 📘 Note: you'll need to grab a Dynamic environment ID from your [developer dashboard](https://app.dynamic.xyz)
First, we will swap out the Rainbowkit provider with the Dynamic one.
```jsx
const App = () => {
return (
);
};
```
#### Replace `WagmiConfig` with `DynamicWagmiConnector`
As mentioned in the full wagmi guide above, the `DynamicWagmiConnector` replaces `wagmiConfig` in the Dynamic setup. Note that the Dynamic provider wraps the Wagmi connector, vs wagmi wrapping the Rainbowkit adapter.
```jsx
const App = () => {
return (
);
};
```
#### Replace `ConnectButton` with `DynamicWidget`
Dynamic uses the Dynamic widget to manage wallets, connect, user profile etc. We will replace the Rainbowkit ConnectButton with it:
```jsx
export const App = () => {
return (
);
};
```
**That's it! you should now have Dynamic working instead of Rainbowkit.**
### Things to know
#### Authenticating with Dynamic vs Rainbowkit
As mentioned above, Dynamic comes built in with authentication. That means that as part of a Dynamic setup, you receive optional access to user management functions, as well as a JWT that contains verified credentials for the user.
Optionally, you can chose to keep the only connect-only experience of Rainbowkit. To do so, you can add to the settings \`initialAuthenticationMode: 'connect-only'. You can read more about connect-only vs authentication[here.](/wallets/advanced-wallets/connected-vs-authenticated)
#### Chains and customization
Rainbowkit configures chains within code using wagmi. Dynamic, on the other hand, pulls its configuration from your [developer dashboard](https://app.dynamic.xyz/dashboard/configurations).
# Customizing the Onramp Experience
Source: https://docs.dynamic.xyz/money-and-funding/customizing-the-onramp-experience
## Introduction
If you're reading this, you've probably already followed the instructions in [Default Onramps](/money-and-funding/default-onramps) and have enabled at least one onramp.
Here we'll learn how to customize the experience further and bring your own.
Before continuing, please make sure you're using the latest version of the Dynamic SDK packages.
## OnrampOptions
Each onramp is represented by an `OnrampOption` object in the SDK, which has the following properties:
| Property | Type | Required | Default | Description |
| ----------------- | ------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `displayName` | string | Yes | - | The name of the onramp provider to be displayed in UI.
Example: "Coinbase" | | `iconUrl` | string | Yes | - | The icon URL of the onramp provider to be displayed in UI.
Example: "[https://www.coinbase.com/assets/coinbase-logo-2020-09-09-1024x1024.png](https://www.coinbase.com/assets/coinbase-logo-2020-09-09-1024x1024.png)" | | `id` | string | Yes | - | The id of the onramp provider, ideally based off its name.
Example: "coinbase" | | `url` | string | No | - | The URL of the onramp provider. For iframe mode, this is displayed directly in the UI. For popup mode, this is opened in a new window when the provider is selected.
Example: "[https://widget.coinbase.com/iframe/onramp?apiKey=YOUR\_API\_KEY\&walletAddress=YOUR\_WALLET\_ADDRESS](https://widget.coinbase.com/iframe/onramp?apiKey=YOUR_API_KEY\&walletAddress=YOUR_WALLET_ADDRESS)" | | `openMode` | 'iframe' \| 'popup' | No | 'iframe' | The display mode for the onramp provider.
'iframe' - The provider will be displayed in an iframe within the UI
'popup' - The provider will be opened in a new window when selected | | `onClick` | function | Yes | - | The onClick handler for when the onramp provider is selected.
Signature: `({ wallet }: { wallet: Wallet }) => void` | | `description` | string | No | - | The description of the onramp provider to be displayed in UI.
Example: "Buy crypto with a credit card" | | `isPaymentMethod` | boolean | No | false | Whether the option is for a specific payment method within the onramp provider. If true, the SDK will display the option as a payment method in the UI. |
It's important to note that the `onClick` handler is not customizable, but rather it takes the current URL defined in the `url` field and opens it in a new window.
These onrampOptions are accessible via the `onrampOptions` prop in the `overrides` prop of the `DynamicContextProvider` component which provides the current options and allows you to return a new array of options.
```tsx
defaultOnrampOptions
}}>
```
## Customization Examples
### Example 1: Customizing the existing Coinbase Onramp URL
Let's say you want to customize the current Coinbase onramp URL to include a custom parameter. You can do this by simply returning the same array of onramp options but with the `url` field updated.
```tsx
const onrampOptions = (defaultOnrampOptions) => {
return defaultOnrampOptions.map((option) => {
if (option.id === "coinbaseOnramp") {
option.url = `${option.url}&customParam=123`;
}
return option;
});
};
```
### Example 2: Adding a payment method option
Taking Coinbase as an example, you'll see that there are [multiple payment methods available for the onramp](https://docs.cdp.coinbase.com/onramp/docs/api-onramp-initializing#onramp-url-parameters). You might want to give these options to the user in the widget.
In this case, you'll want to return a new array of onramp options with the `displayName` field set to the payment method name as well as the URL adapted to include the payment method parameter.
```tsx
const onrampOptions = (defaultOnrampOptions) => {
return defaultOnrampOptions.map((option) => {
if (option.id === "coinbaseOnramp") {
return {
...option,
displayName: "Credit Card",
id: "coinbaseOnrampCreditCard",
url: `${option.url}&defaultPaymentMethod=CARD`,
};
}
return option;
});
};
```
The result should look like this:
### Example 3: Bring Your Own Onramp
Instead of changing the existing onramp options, you can also add your own option, which can be as simple as this:
```tsx
const onrampOptions = (defaultOnrampOptions) => {
return [
...defaultOnrampOptions,
{
id: 'myNewOnramp',
url: 'https://dynamic.xyz',
displayName: 'My New Onramp',
iconUrl: 'https://my-company.com/icon.png',
openMode: 'popup',
},
];
};
```
The result should look like this:
# Default Onramp Experiences
Source: https://docs.dynamic.xyz/money-and-funding/default-onramps
## Summary
At Dynamic, we make it incredibly simple to add a Fiat onramp solution to your SDK integration. We are currently working with [Coinbase](https://www.coinbase.com/en-gb/developer-platform/products/onramp) and [Banxa](https://banxa.com/). Other great onramp solutions will be made available soon.
Before continuing, please make sure you're using the latest version of the Dynamic SDK packages.
### Usage
To enable an onramp solution:
1. Go to [the Funding tab in your Dynamic developer dashboard](https://app.dynamic.xyz/dashboard/funding).
2. Under "Fiat on-ramps", toggle on whichever onramp you'd like to enable (add confirm any additional terms and conditions).
For Banxa, if you enable it on Sandbox, then you'll be using Test Order. Reference Banxa's test information so you can easily [test in sandbox.](https://docs.banxa.com/docs/order-flow)
You're done! In the Dynamic widget after logging in, users will now see a "Deposit" button that will open up the various deposit options, including those you've enabled.
To learn how to customize the experience, check out the [Customizing the Onramp Experience](/money-and-funding/customizing-the-onramp-experience) doc.
# Fund from External Wallet
Source: https://docs.dynamic.xyz/money-and-funding/fund-from-external-wallet
## Introduction
As one of the funding options for users, you may want to allow them to fund their wallet from an external wallet.
To do so, all you need to do is turn it on in the [Funding tab in your Dynamic developer dashboard](https://app.dynamic.xyz/dashboard/funding).
If you open the configuration section for this option, you'll also be able to configure the following:
* The default currency/token to fund
* The suggested minimum amount to fund
* Whether the amount is a suggestion or a requirement
All of the above configurations are extra and optional.
Once enabled, you'll see "Fund from External Wallet" as an option in the deposit screen.
In the initial step, users will be able to select the external wallet they want to fund their wallet from, and following this, they can choose the amount and token:
# Quickstart
Source: https://docs.dynamic.xyz/quickstart
Let's get you up and running with a full signup/login UI! Just [sign up](https://app.dynamic.xyz) and follow the guide below!
You can also refer to one of [our sample apps](/example-apps) if you want to
clone a full application rather than embed into an existing one!
## Select your SDK
## Install the SDK
EthereumWalletConnectors also includes all EVM compatible chains including
layer 2's i.e. Base as well as [Dynamic Embedded
Wallets](/wallets/embedded-wallets/dynamic-embedded-wallets). Learn more about WalletConnectors [here](/react-sdk/providers/dynamiccontextprovider#walletconnectors).
## Initialize the SDK
If you are using Wagmi, make sure to read our [full Wagmi
guide](/react-sdk/using-wagmi) for more setup instructions.
If you're using Vite, you'll need to check out [the polyfills guide](/troubleshooting/react/vitejs-polyfills-necessary-for-dynamic-sdk).
If you see any other errors, it's worth checking out [Dynamic Doctor](/troubleshooting/dynamic-doctor) for quick debugging tips!
To quickly test the login flow, you can enable [Test
Accounts](/developer-dashboard/test-accounts) in Sandbox mode.
## Celebrate & Learn More!
That's it! You should now have an initial working version of the Dynamic login flow. You can now configure different kinds of signup flows including [Embedded wallets](/wallets/embedded-wallets/dynamic-embedded-wallets) and [Email, Social & SMS](/authentication-methods/email-social-sms).
You can also [join our Slack Community](https://www.dynamic.xyz/slack) to ask us
anything on your mind.
# Account Abstraction with ZeroDev
Source: https://docs.dynamic.xyz/react-native/account-abstraction
When using account abstraction in your project to sponsor gas, batch transactions, or any other account abstraction features, you will likely want to get a ZeroDev kernel client to perform these operations.
You can use the `@dynamic-labs/zerodev-extension` package to create a ZeroDev kernel client for a wallet.
Here is how you can set up and create a kernel client.
The `@dynamic-labs/zerodev-extension` depends on the Viem Extension, so before
going through this setup, make sure to have the Viem Extension set up and
working. [Viem Extension Setup](/react-native/viem)
# Setup
## Install ZeroDevExtension
Install the @dynamic-labs/zerodev-extension package:
`bash Shell npx expo install @dynamic-labs/zerodev-extension `
`bash Shell npm install @dynamic-labs/zerodev-extension `
`bash Shell yarn add @dynamic-labs/zerodev-extension `
## Resolve File Resolution Error (Optional)
When running the ZeroDevExtension in your React Native application, you might encounter an error where Metro cannot resolve the `paymasterClient.js` file. This issue occurs because Metro tries to load `paymasterClient.js`, but the actual file is named `paymasterClient.ts`.
To fix this, you need to customize Metro’s resolver in your `metro.config.js` file to handle TypeScript file extensions properly.
### Generate metro.config.js for Expo Projects
If you don’t have a `metro.config.js` file in your project, you can generate one using the following command:
```bash
npx expo customize metro.config.js
```
### Customize Metro Resolver
Add the following code to your `metro.config.js` file to instruct Metro to resolve `.ts` files when it cannot find the corresponding `.js` files:
```js
// metro.config.js
/**
* Custom resolver to handle ZeroDev imports
*/
config.resolver.resolveRequest = (context, moduleName, platform) => {
try {
return context.resolveRequest(context, moduleName, platform)
} catch (error) {
if (moduleName.endsWith('.js')) {
const tsModuleName = moduleName.replace(/\.js$/, '.ts')
return context.resolveRequest(context, tsModuleName, platform)
}
throw error
}
}
```
This modification allows Metro to attempt to resolve `.ts` files when it fails to find `.js` files, which fixes the resolution error for the `paymasterClient` file.
## Events Polyfill
ZeroDevExtension requires a polyfill for the Node.js events module. You can install the [events](https://www.npmjs.com/package/events) polyfill using one of the following commands:
`bash Shell npx expo install events `
`bash Shell npm install events `
`bash Shell yarn add events `
## Integrate with your Dynamic client
To include the ZeroDev module in your Dynamic client, you need to extend the client with the ZeroDev extension:
```typescript
import { createClient } from '@dynamic-labs/client'
import { ViemExtension } from '@dynamic-labs/viem-extension'
import { ZeroDevExtension } from '@dynamic-labs/zerodev-extension'
const dynamicClient = createClient({
environmentId: '',
})
.extend(ViemExtension())
.extend(ZeroDevExtension())
```
Now your setup is complete, and you have the ZeroDev module available in your Dynamic client.
# Usage
Now that you have the ZeroDev module in your Dynamic client, you can get the ZeroDev kernel client by using the `dynamicClient.zeroDev.createKernelClient` method. Here is an example:
```typescript
// dynamicClient.ts
const dynamicClient = createClient({
environmentId: '',
})
.extend(ViemExtension())
.extend(ZeroDevExtension())
// getPrimaryWalletKernelClient.ts
const getPrimaryWalletKernelClient = async () => {
const primaryWallet = dynamicClient.wallets.primaryWallet
if (!primaryWallet) {
throw new Error('No primary wallet')
}
const kernelClient = await dynamicClient.zeroDev.createKernelClient({
wallet: primaryWallet,
})
return kernelClient
}
```
# Examples
## Batch transaction example
This example demonstrates how you can use a ZeroDev kernel client to perform a batched transaction:
```typescript
import { encodeFunctionData } from 'viem'
const contractAddress = '0x123'
const contractABI = [
{
inputs: [{ internalType: 'address', name: '_to', type: 'address' }],
name: 'mint',
outputs: [],
stateMutability: 'nonpayable',
type: 'function',
},
]
const sendBatchedTransactions = async () => {
const primaryWallet = dynamicClient.wallets.primaryWallet
if (!primaryWallet) {
throw new Error('No primary wallet')
}
const kernelClient = await client.zeroDev.createKernelClient({
wallet: primaryWallet,
})
const { account } = kernelClient
const hash = await kernelClient.sendUserOperation({
account,
callData: await account.encodeCalls([
{
data: encodeFunctionData({
abi: contractABI,
args: [primaryWallet.address],
functionName: 'mint',
}),
to: contractAddress,
value: BigInt(0),
},
{
data: encodeFunctionData({
abi: contractABI,
args: [primaryWallet.address],
functionName: 'mint',
}),
to: contractAddress,
value: BigInt(0),
},
]),
})
return hash
}
```
# Setting up the Dynamic Client
Source: https://docs.dynamic.xyz/react-native/client
The Dynamic Client is a vanilla javascript package that allows users to quickly set up all the configurations
needed to get an interface that allows them to interact with our features.
It provides a very simple, bare bones client object through the call to `createClient`.
This client can then be extended with many other features, like React Native support and viem integration.
## Installation
Simply run the following in your terminal:
```bash Shell
npx expo install @dynamic-labs/client
```
```bash Shell
npm install @dynamic-labs/client
```
```bash Shell
yarn install @dynamic-labs/client
```
## Set up
Now create your client with the following code:
```typescript
import { createClient } from '@dynamic-labs/client'
export const dynamicClient = createClient({
environmentId: 'YOUR-ENVIRONMENT-ID',
// Optional:
appLogoUrl: 'https://demo.dynamic.xyz/favicon-32x32.png',
appName: 'Dynamic Demo',
})
```
You can read more about our client package [here](/react-native/package-references/client).
# Deeplink URLs
Source: https://docs.dynamic.xyz/react-native/deeplink-urls
In order to use most of our react native features (such as social connections), you will first
have to set up the list of mobile deeplink URLs dynamic may use to redirect back to your app.
For security reasons, when deeplinking back to your app, we must verify whether the app's deeplink URL
is included in this list. If it isn't, Dynamic will not perform the deeplink.
## How to set up your app for deeplinking
### Configuring your app's custom scheme
First, you should follow Expo's guide on enabling deeplinking for your app
[here](https://docs.expo.dev/guides/linking/#linking-to-your-app).
### Registering your app's deeplink URL with Dynamic
Afterwards, head to your Dynamic dashboard's
[Security page](https://app.dynamic.xyz/dashboard/security) and enable "Whitelist Mobile Deeplink".
Click "Save changes".
Next, click the cog in this same section to open up the
[Mobile Deeplink URL page](https://app.dynamic.xyz/dashboard/security#mobile-deeplink-urls), and there
you must add your app's deeplink URL with the same custom scheme you configured in the previous step.
It might look something like this: `myappcustomscheme://`.
### Creating a new app bundle
After configuring the deeplink URL, you need to create a new app bundle that includes the deeplink configuration. This is necessary because the native modules and configurations need to be properly set up in the app bundle.
For Expo projects, you have two options:
1. Use [expo prebuild](https://docs.expo.dev/guides/adopting-prebuild/) to generate the native code and then build your app
2. Use [EAS (Expo Application Services)](https://expo.dev/easg) to build your app bundle
For React Native projects without Expo, you'll need to rebuild your native app with the updated configuration.
## Troubleshooting
You can check if the deeplink is working by:
* installing the app in the simulation
* opening safari
* paste the deeplink they configured in the dashboard
* your app should open as a result of opening the deeplink in safari
If this fails, it means the app bundle does not have the deeplink correctly setup.
To fix it, check the app.json file and look for the schema and slug fields, and make sure you have properly built a new app bundle.
Note that you cannot use the EXPO GO app, you have to build the app using expo prebuild or using EAS to build the app bundle for you.
# Using Dynamic's UI
Source: https://docs.dynamic.xyz/react-native/dynamic-ui
Besides all of our headless methods, we also provide a compreehensive set of UI modals that can be easily leveraged
to achieve the same functionalities.
## Using Dynamic's modals
You can leverage our authentication flow modal to sign your users in — this will bring our sign in modal on top of
your app, and once the user has successfully signed in, it will automatically close.
You can show the authentication modal by calling:
```typescript
dynamicClient.ui.auth.show()
```
To hide the authentication modal programmatically, you can use:
```typescript
dynamicClient.ui.auth.hide()
```
After the user has signed in successfully, you can also bring up our user profile interface, which allows your user
to view their wallet's address and balance, as well as editing their fields like email and phone number.
To show the user profile modal, call:
```typescript
dynamicClient.ui.userProfile.show()
```
To hide the user profile modal programmatically, use:
```typescript
dynamicClient.ui.userProfile.hide()
```
You can read more about our UI modules [here](/react-native/package-references/client#ui-module).
# Email and SMS verification
Source: https://docs.dynamic.xyz/react-native/email-and-sms-verification
The dynamic client authentication module enables user authentication via email or SMS.
Notice that email and SMS login methods **must be respectively enabled** in
your environment's dashboard settings first!
## Sending and verifying OTPs
The methods below can be used to send/resend and verify one time passwords
```typescript
// Send, retry and then verify OTP to an email
await dynamicClient.auth.email.sendOTP('someone@gmail.com')
await dynamicClient.auth.email.resendOTP()
await dynamicClient.auth.email.verifyOTP('received-token')
// Send, retry and then verify OTP to a phone number
await dynamicClient.auth.sms.sendOTP({
dialCode: '1',
iso2: 'us',
phone: '2793334444',
})
await dynamicClient.auth.sms.resendOTP()
await dynamicClient.auth.sms.verifyOTP('received-token')
```
### Example
The example below demonstrates a React component that can send, resend and verify OTPs through email.
You can follow the same pattern for phone numbers but collect phone number, iso2 and dial code instead
of email address.
```typescript
import { dynamicClient } from '';
const EmailSignIn: FC = () => {
const [email, setEmail] = useState('')
const [otp, setOtp] = useState('')
const [otpSent, setOtpSent] = useState(false)
const handleSendOTP = async () => {
await dynamicClient.auth.email.sendOTP(email)
setOtpSent(true)
}
const handleResendOTP = () => {
dynamicClient.auth.email.resendOTP()
}
const handleVerifyOTP = () => {
dynamicClient.auth.email.verifyOTP(otp)
}
return (
{!otpSent ? (
) : (
)}
)
}
```
You can read more about these modules [here](/react-native/package-references/client#auth-email-submodule).
# Embedded wallets
Source: https://docs.dynamic.xyz/react-native/embedded-wallets
The dynamic client provides an interface to easily interact with and create embedded wallets for your users.
Notice that embedded wallets **must be enabled** in your environment's
dashboard settings first!
## Creating and Getting the Wallet
This interface allows you to create new embedded wallets, check if any already exist and fetch the current wallet.
See the following example which renders a prompt to create a wallet or renders its address if it already exists:
```typescript
import { dynamicClient } from '';
import { useReactiveClient } from '@dynamic-labs/react-hooks';
const EmbeddedWallet: FC = () => {
const { wallets } = useReactiveClient(dynamicClient)
const wallet = wallets.userWallets[0]
return (
{wallet && wallets.embedded.hasWallet ? (
Your wallet address: {wallet.address}
) : (
)}
)
}
```
## Creating a Wallet for a Specific Chain
The `createWallet` method also allows you to create an embedded wallet for a specific chain
See the example below:
```typescript
import { dynamicClient } from '';
import { useReactiveClient } from '@dynamic-labs/react-hooks';
const AddEvmWalletButton: FC = () => {
return (
)
}
```
This is the wallet list view with the tabs
| All chains tab selected | Ethereum selected |
| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| | |
# Wallet
Source: https://docs.dynamic.xyz/react-sdk/objects/wallet
An object containing the attributes about the user wallets.
### Props
| Field | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| additionalAddresses: WalletAdditionalAddress\[] | Additional addresses associated to the wallet (e.g. ordinals and payment addresses for bitcoin wallets) |
| address: string | Public address of the connected wallet |
| chain: string | Current BlockChain name (e.g: 'ETH', 'SOL', 'BTC', etc) |
| connector: WalletConnector | The wallet connector object |
| id: string | The wallet's unique id (matches thw wallet verified credential on connect-anf-sign) |
| isAuthenticated: boolean | True if the user is authenticated, otherwise it's false |
| key: string | The wallet key (e.g. metamask, phantom, etc) |
### Methods
| Method | Description |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| getBalance(): Promise\ | Retrieves the balance of the wallet. |
| getNameService(): Promise\ | Retrieves the name service data associated with the wallet. |
| isConnected(): Promise\ | If the wallet is connected. |
| proveOwnership(messageToSign: string): Promise\ | Proves ownership of the wallet by signing a message. |
| signMessage(messageToSign: string): Promise\ | Signs a message using the wallet. |
| switchNetwork(networkChainId: number \| string): Promise\ | Switches the network that the wallet is connected to. |
| sync(): Promise\ | Prompts the user to reconnect the wallet if not connected and only resolves when the wallet is connected and active. |
# WalletOption
Source: https://docs.dynamic.xyz/react-sdk/objects/wallet-option
A WalletOption type is used to represent a wallet option in the wallet selection modal. This is as opposed to a [Wallet](/react-sdk/objects/wallet) type, which is used to represent a wallet that is currently connected.
| Field | Optional/Required | Type | Description |
| -------------------- | ----------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| isInstalledOnBrowser | | boolean | Is this wallet installed via a browser extension |
| key | | string | Normalization of the wallet name |
| name | | string | The name of the given wallet |
| walletConnector | | [WalletConnector](/react-sdk/objects/walletconnector) | The wallet connector interface for the given wallet |
| group | Optional | string | The wallet which can connect to multiple chains, not present if the wallet is not multi-chain compatible, or if multiple chains are not enabled |
| groupedWallets | Optional | WalletOption\[] | Where a wallet supports multiple chains, this array contains t |
## Example
```jsx
isInstalledOnBrowser: true;
key: 'phantom';
name: 'Phantom';
walletConnector: WalletConnector;
group: 'phantom';
groupedWallets: [
{
isInstalledOnBrowser: true;
key: '';
name: 'phantom EVM';
walletConnector: WalletConnector;
},
{
isInstalledOnBrowser: true;
key: '';
name: 'phantom Solana';
walletConnector: WalletConnector;
},
{
isInstalledOnBrowser: true;
key: '';
name: 'phantom Ledger';
walletConnector: WalletConnector;
},
];
```
# WalletConnectConnector
Source: https://docs.dynamic.xyz/react-sdk/objects/walletconnect-connector
This is Dynamic's WalletConnect connector over the basic wallet interface. This can be used to interact with the users WalletConnect wallets. It has all methods available in the [WalletConnector](https://docs.dynamic.xyz/react-sdk/objects/walletconnector) and some additional method specific to WalletConnect wallets.
IWalletConnectConnector is available in SDK v2.0.0+.
| Field | Description |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| getSupportedNetworks: Promise\ | A method to retrieve the supported/approved networks for the WalletConnect wallet. Some wallets will only allow approve a network if the user manually switches in the wallet app first. |
## Interface definition
```ts
interface IWalletConnectConnector {
getSupportedNetworks: Promise
};
```
### How to use it
In this example, we are going to return all supported networks for the wallet connector.
```JavaScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isWalletConnectConnector } from '@dynamic-labs/wallet-connector-core';
const MyComponent = () => {
const { primaryWallet } = useDynamicContext();
const getWCSupportedNetworks = async () => {
if (!isWalletConnectConnector(primaryWallet?.connector)) {
return;
}
const supportedNetworks = await primaryWallet.connector.getSupportedNetworks();
console.log('supportedNetworks', supportedNetworks);
return supportedNetworks;
};
...
};
```
# WalletConnector
Source: https://docs.dynamic.xyz/react-sdk/objects/walletconnector
This is Dynamic's abstraction over the wallet interface. This can be used to interact with the users wallet.
| Field | Description |
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fetchPublicAddress: Promise\ | A method to fetch the public address (alternatively the address could be fetched from useDynamicContext's user object) |
| getPublicClient(): Viem Public Client \| undefined | The provider should be used for read only actions on the block chain.Ethereum - A [Viem Public Client](https://viem.sh/docs/clients/public.html) SOLANA -[solana/web3js.Connection](https://solana-labs.github.io/solana-web3.js/classes/Connection.html) |
| getWalletClient() : Promise\\\ | Representation of the signer (the wallet) for actions that require signatures with the private key.Ethereum - [Viem Wallet Client](https://viem.sh/docs/clients/wallet.html), Solana - The active wallet |
| name: string | The wallet name |
| signMessage(messageToSign: string): Promise\ | A method to sign a message |
| supportedChains: Chain\[] | The chains that the wallet supports |
| getDeepLink(): string | A method to get a deep link to a wallet for mobile |
| getAccountAbstraction(): Smart Wallet Provider | A method to get the smart wallet provider for more advanced usage |
| supportsNetworkSwitching(): boolean | Whether the connector supports network switching. |
| switchNetwork(\{ networkChainId, networkName }: \{ networkChainId?: number; networkName?: string; }): Promise\ | Switch to another network by provider either the network name or chain id specified in the list of EvmNetwork |
# WalletsByChain
Source: https://docs.dynamic.xyz/react-sdk/objects/wallets-by-chain
## Description
An Array of objects, in which each object contains the chain name to be connected for the chain. Primarily used for [bridging](/building-bridges/dynamic-bridge-widget) purposes.
| Field | Description |
| ------------- | ----------- |
| chain: string | Chain name |
## Example
```jsx
[
{
chain: "EVM",
},
{
chain: "STARK",
},
];
```
# Introduction to the SDK
Source: https://docs.dynamic.xyz/react-sdk/overview
The SDK allows you to build authentication and authorization into your application in a few lines of code.
The SDK is compatible with React 18, and shortly, React 19.
## Getting Started
We provider step by step guides on getting started with the SDK [here](/quickstart).
You'll also want to check out the [UI components customization guides](/ui-components), or [the headless guides](/headless/headless-overview) if you need to use your own UI components.
Below we'll introduce you to the main parts of the SDK and how they can be used.
## Main Concepts
### Loading States
[Our Loading/Login States guide](/react-sdk/loading-login-states) show you how do everything from wait for the SDK to be loaded to checking if a user is authenticated.
### Components
[Components](/react-sdk/components/components-introduction) exist as three main types:
1. UI components (create UI for different parts of the onboarding flow)
2. Context providers (wrap your app in a React context to access SDK functionality)
3. Connectors (help integrate different parts of the SDK i.e. Wagmi or specific chains)
### Handlers
[Handlers](/react-sdk/handlers/handlers-introduction) are a way to programmatically customize synchronous behaviors of the SDK (i.e. run a blocking fraud check during wallet connection).
### Events
[Events](/react-sdk/events/events-introduction) are a way to listen for SDK events and run your own asynchronous code at certain points.
### Hooks
[Dynamic hooks](/react-sdk/hooks/hooks-introduction) are custom React hooks that allow you to access SDK functionality in your React components.
### Utilities
[Utilities](/react-sdk/utilities/utilities-introduction) are functions that allow you to do certain tasks in your application quickly i.e. check the network of a wallet.
# DynamicContextProvider
Source: https://docs.dynamic.xyz/react-sdk/providers/dynamiccontextprovider
## Settings
Passed in using the "settings" prop, available when you first initialize `DynamicContextProvider` in your App.
### accessDeniedMessagePrimary
**Type:** `string`
**Description:** Custom main error message used when a wallet attempts to authenticate via Dynamic and is rejected because it does not have access. Defaults to "Access denied"
### accessDeniedMessageSecondary
**Type:** `string`
**Description:** Custom secondary error message used when a wallet attempts to authenticate via Dynamic and is rejected because it does not have access. Defaults to "We couldn't find your wallet address on our access list of customers."
### accessDeniedButton
**Type:** `AccessDeniedCustomButton`
**Description:** Custom secondary error button text and action when a wallet attempts to authenticate via Dynamic and is rejected because it does not have access. Defaults to "Try another method" and allow user to choose another login option. Please see: [AccessDeniedCustomButton](/react-sdk/objects/access-denied-custom-button)
### coinbaseWalletPreference
**Type:** `'all' | 'smartWalletOnly' | 'eoaOnly'`
**Description:** Determines which connection options users will see. Defaults to all. Please see: [https://www.smartwallet.dev/sdk/makeWeb3Provider#options-optional](https://www.smartwallet.dev/sdk/makeWeb3Provider#options-optional)
### cssOverrides
**Type:** `string | JSX.Element`
**Description:** Allows for custom CSS overrides via ShadowDom. Please see: [Custom CSS](/design-customizations/css/custom-css)]
### debugError
**Type:** `boolean`
**Description:** When enabled, errors caught during the authentication step and their stack trace will be set in a state and displayed in the front end.
### deepLinkPreference
**Type:** `'native' | 'universal'`
**Description:** Controls the type of deep link used when connecting a mobile wallet. Defaults to 'native'. This is useful for example if your app is running in a webview of a native mobile app, and you want to be able to link out to any wallet without having to modify your iOS build config. In this case, you can set this to 'universal'.
### displaySiweStatement
**Type:** `boolean`
**Description:** When enabled, this will show a message on terms of service and privacy policy in the signing message on the authentication step.
### enableVisitTrackingOnConnectOnly
**Type:** `boolean`
**Description:** When the Dynamic SDK is being used with auth mode = connect-only, we require this to be set to "true" to track visits of connected wallets in this environment.
### environmentId
**Type:** `string`
**Description:** You will need to specify your app's environment ID, which refers to a unique environment and its settings in Dynamic. To get your environment ID, go to [dashboard's API tab](https://app.dynamic.xyz/dashboard/api)
### events
**Type:** `DynamicEvents`
**Description:** This prop allows custom event callbacks after important events during the authentication flows for Dynamic's React SDK. For more information, please see [the main React SDK reference](/react-sdk)
### initialAuthenticationMode
**Type:** `AuthModeType`
**Description:** Sets the initial SDK authentication mode to either connect-only or connect-and-sign. connect-only does not require users to authenticate to prove ownership of their wallet. connect-and-sign will require an additional step for users to prove ownership of their wallet. Defaults to connect-and-sign. See also the [setAuthMode](/react-sdk/hooks/usedynamiccontext) method, which allows you to toggle this after the app has loaded.
### logLevel
**Type:** `keyof typeof LogLevel`
**Description:** The log level to use for client side logging with our SDK. Defaults to WARN
### mobileExperience
**Type:** `'in-app-browser' | 'redirect'`
**Description:** This setting determines how users connect on mobile devices. By default, it is set to 'in-app-browser', which means the connection will open within the wallet's in-app browser. If you prefer to have users connect via WalletConnect, set this option to 'redirect'. This will prompt users to accept connection requests in their wallet app and, for Phantom users, automatically redirect them back to their mobile browser. [See here for examples](#setting-mobile-experience)
### newToWeb3WalletChainMap
**Type:** `ChainToWalletMap`
**Description:** When provided, this is used in the Get your first wallet view in the wallet list modal. This can be helpful to steer initial customers who do not have a wallet to download and use a specific chain and wallet.
### networkValidationMode
**Type:** `'always' | 'sign-in' | 'never'`
**Description:** Note: Supported only in connect-only. Defines how the Dynamic SDK will enforce the wallet network.
* **always** - requires the wallet to be on an enabled network while connecting and while the session is active
* **sign-in** - will only enforce the network on connect
* **never** - completely turn off the network validation. Defaults to `sign-in`.
### onboardingImageUrl
**Type:** `string`
**Description:** When provided, this image will be shown during the customer information capture step after a wallet successfully authenticates with Dynamic and the environment requires additional information from the user.
### policiesConsentInnerComponent
**Type:** `ReactNode | ReactNode[]`
**Description:** For environments with the username setting enabled, you will need to pass in a value for this prop to show a custom prompt or label for the policies contest checkboxes displayed during customer information capture after signing.
### privacyPolicyUrl
**Type:** `string`
**Description:** When provided, this will display a privacy policy URL on the signing step. This should be set to a URL of your organization's privacy policy web page.
### recommendedWallets
**Type:** `RecommendedWallet[]`
**Description:** Available from V1.2 only. An array of wallet keys that will be recommended to the user. See more in [our section on recommending wallets](/wallets/advanced-wallets/recommend-wallets).
### redirectUrl
**Type:** `string`
**Description:** When provided, this will redirect the user to the specified URL after the user has successfully gone through an oauth flow (social login or social account linking).
### shadowDOMEnabled
**Type:** `boolean`
**Description:** Shadow DOM allows the SDK to look as intended wherever it is hosted and it plays nicely with your existing styling system. For more information, please see: [Custom CSS](/design-customizations/css/custom-css)
### siweStatement
**Type:** `string`
**Description:** When provided, this custom message will be shown on the message to sign for the wallet signing step.
### termsOfServiceUrl
**Type:** `string`
**Description:** When provided, this will display a terms of service URL on the signing step. This should be set to a URL of your organization's terms of service web page.
### walletConnectors
**Type:** `[]walletConnector`
**Description:** When provided, will enable whatever connectors you pass so that your end user can signup/login using those wallets. For the list of available connectors, see the walletConnectors section below.
### walletConnectPreferredChains
**Type:** Not specified
**Description:** Relevant to Wallet Connect only, used to determine which chains to establish a connection with first. The value must be an array containing [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) chain ID's. The format for this is `{namespace-goes-here}:{reference-goes-here}`. Currently we only support Ethereum, so it will always be `eip155:{reference-goes-here}`. For example, Ethereum mainnet being \['eip155:1']
### walletsFilter
**Type:** `(options: WalletOption[]) => WalletOption[]`
**Description:** When specified, this is a custom function that allows clients of Dynamic SDK to filter out wallet options based on a function on the wallet options. For example: `walletsFilter: (wallets) => wallets.filter((w) => w.key !== 'walletx')` will exclude walletx from showing up on the wallet list.
### bridgeChains
**Type:** `WalletsByChain`
**Description:** (Only use with bridging) Which chains should be used for bridging.
### socialProvidersFilter
**Type:** `(providers: SocialOAuthProvider[]) => SocialOAuthProvider[]`
**Description:** When specified, this is a custom function that allows clients of Dynamic SDK using social auth to filter or modify the order of the social options displayed to the user. For example, we can only show github oauth option: `socialProvidersFilter: (providers) => (['github'])`.
### overrides
**Type:** `{ views: SdkView[], evmNetworks: EvmNetwork[] }`
**Description:** Used for passing in [Views](/react-sdk/objects/views) or [evmNetworks](/chains/network-switching#evmnetworks).
### enableConnectOnlyFallback
**Type:** `boolean`
**Description:** When `true`, enables the SDK to fallback to wallet connect-only auth mode if connection to Dynamic's servers is not possible. Available in version 1.1 and above
### defaultPhoneInputIso2
**Type:** `string`
**Description:** Used to define which phone number country code should be used as the default in all phone inputs, ex: `defaultPhoneInputIso2: "fr"`
### social
**Type:** `{ strategy: 'redirect' | 'popup' }`
**Description:** Allow to customize the default social behavior from 'redirect' to 'popup'
### tokenFilter
**Type:** `(tokens: TokenBalance[]) => TokenBalance[]`
**Description:** Allows filtering which tokens show in the widget balance view. Hidden tokens will not count towards the total balance.
## walletConnectors
Here are the possible options for the walletConnectors array. For each one, you must make sure you have installed the package first:
Please note that @dynamic-labs/ethereum (EthereumWalletConnectors) contains
all EVM chains, not just Ethereum. It also includes Dynamic-powered embedded
wallets, as these are EVM based too.
| Package Name | Chain | WalletConnector to include |
| :--------------------- | :----- | -------------------------- |
| @dynamic-labs/ethereum | EVM | `EthereumWalletConnectors` |
| @dynamic-labs/algorand | ALGO | `AlgorandWalletConnectors` |
| @dynamic-labs/solana | SOL | `SolanaWalletConnectors` |
| @dynamic-labs/flow | FLOW | `FlowWalletConnectors` |
| @dynamic-labs/starknet | STARK | `StarknetWalletConnectors` |
| @dynamic-labs/cosmos | COSMOS | `CosmosWalletConnectors` |
##### EVM Addon Wallets
| Package Name | Which Wallets | WalletConnector to include |
| :------------------- | :------------ | :-------------------------- |
| @dynamic-labs/magic | *magic* | `MagicWalletConnectors` |
| @dynamic-labs/blocto | *blocto* | `BloctoEvmWalletConnectors` |
## Locale
This prop is for editing copy and adding translations to the SDK. For more information, please see [the customizing copy guide](/design-customizations/customizing-copy-translations) and [reference](/react-sdk/objects/locale).
## Examples
#### Initiate Dynamic using only defaults
```JavaScript
```
#### Initiate Dynamic with Ethereum and Starknet wallets enabled
```JavaScript
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import { StarknetWalletConnectors } from "@dynamic-labs/starknet";
```
#### Initiate Dynamic using all available methods
```JavaScript
{
console.log('in onAuthFlowClose');
},
onAuthFlowOpen: () => {
console.log('in onAuthFlowOpen');
},
onAuthSuccess: () => {
navigate('/dashboard/overview');
},
onLogout: () => {
console.log('in onLogout');
},
},
initialAuthenticationMode: 'connect-only',
logLevel: 'DEBUG',
newToWeb3WalletChainMap: {
1: ['metamask', 'walletconnect'],
137: ['metamask', 'walletconnect'],
56: ['metamask', 'walletconnect'],
80001: ['metamask', 'walletconnect'],
},
onboardingImageUrl: 'https://i.imgur.com/3g7nmJC.png',
policiesConsentInnerComponent: (
),
privacyPolicyUrl: 'https://www.dynamic.xyz/privacy-policy',
shadowDOMEnabled: true,
siweStatement: 'Custom message to sign',
termsOfServiceUrl: 'https://www.dynamic.xyz/terms-of-service',
walletsFilter: (wallets) => wallets.filter((w) => w.key !== 'walletx'),
}}>
```
#### Do not show `walletx` on the wallet list
```JavaScript
>'
walletsFilter: (wallets) => wallets.filter((w) => w.key !== 'walletx'),
}}
>
```
#### With events callbacks
```JavaScript
>',
events: {
onAuthFlowClose: () => {
console.log('in onAuthFlowClose');
},
onAuthFlowOpen: () => {
console.log('in onAuthFlowOpen');
},
onAuthSuccess: () => {
navigate('/dashboard/overview');
},
onLogout: () => {
console.log('in onLogout');
},
},
}}>
```
#### Setting mobile experience
##### Globally for all wallets
```JavaScript
>',
mobileExperience: 'redirect' | 'in-app-browser'
}}>
```
##### On a wallet by wallet basis with optional default for all non-specified wallets
**Note**: The walletKey can be found on the chains and networks page of the dashboard [here](https://app.dynamic.xyz/dashboard/chains-and-networks#evm)
```JavaScript
>',
mobileExperience: {
'<>': 'redirect' | 'in-app-browser',
default: 'in-app-browser'
}
}}>
```
# DynamicWagmiConnector
Source: https://docs.dynamic.xyz/react-sdk/providers/dynamicwagmiconnector
The `DynamicWagmiConnector` component integrates your Dynamic project settings with Wagmi
# Usage
```typescript
import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector";
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
function App() {
return (
);
}
```
# Props
## evmNetworks
You can pass a static `evmNetworks` array. This will be passed down to the [Wagmi client config](https://wagmi.sh/react/client#configuration).
The reference for an EvmNetwork can be found [here](/react-sdk/objects/evmNetwork).
Example:
```typescript
const evmNetworks: EvmNetwork[] = [
{
blockExplorerUrls: ["https://etherscan.io/"],
chainId: 1,
chainName: "Ethereum Mainnet",
iconUrls: ["https://app.dynamic.xyz/assets/networks/eth.svg"],
nativeCurrency: { decimals: 18, name: "Ether", symbol: "ETH" },
networkId: 1,
privateCustomerRpcUrls: ["https://mainnet.infura.io/v3/your-api-key"],
rpcUrls: ["https://cloudflare-eth.com"],
vanityName: "Ethereum",
},
];
```
### WebSocket
For webSocket support with Wagmi, you can pass an object as the privateCustomerRpcUrls with your webSocket url configuration
```typescript
const evmNetworks: EvmNetwork[] = [
{
...
privateCustomerRpcUrls: [
{
url: "https://mainnet.infura.io/v3/your-api-key",
webSocket: "wss://mainnet.infura.io/v3/your-api-key"
}
],
...
},
];
```
# Providers and Connectors Introduction
Source: https://docs.dynamic.xyz/react-sdk/providers/providers-introduction
You can see the full UI implemented at any time in our demo environment:
[https://demo.dynamic.xyz](https://demo.dynamic.xyz)
#### Dynamic Context Provider
The [**DynamicContextProvider**](/react-sdk/providers/dynamiccontextprovider) is a provider component provides the context for the rest of the components to work. It must wrap all Dynamic related components of your application.
#### Dynamic Wagmi Connector
The [**DynamicWagmiConnnector**](/react-sdk/providers/dynamicwagmiconnector) is responsible for helping your Dynamic application to integrate with Wagmi out of the box.
# Upgrade from V0 to V1
Source: https://docs.dynamic.xyz/react-sdk/upgrade/v1
## From V0.19 to V1
This upgrade guide is specific to implementing the SDK itself.
### Breaking Changes
#### userWallets hooks
* connectedWallets , secondaryWallets and linkedWallets all been removed in favor of userWallets hook. See [here](/react-sdk/hooks/useuserwallets) for more info.
```jsx
import { useDynamicContext, getNetwork } from '@dynamic-labs/sdk-react-core';
const App = () => {
const { connectedWallets } = useDynamicContext();
useEffect(() => {
connectedWallets.forEach(async ({ connector }) => {
const network = await getNetwork(connector);
...
});
}, [connectedWallets]);
...
}
```
```jsx
import { useUserWallets, getNetwork } from '@dynamic-labs/sdk-react-core';
const App = () => {
const userWallets = useUserWallets();
useEffect(() => {
userWallets.forEach(async ({ connector }) => {
const network = await getNetwork(connector);
...
});
}, [userWallets]);
...
}
```
#### EthereumSmartWalletConnectors -> ZeroDevSmartWalletConnectors
* (v1 alpha -> v1) EthereumSmartWalletConnectors is now renamed to ZeroDevSmartWalletConnectors. You use this connector when you want to use AA wallets.
```jsx
import {DynamicContextProvider} from "@dynamic-labs/sdk-react-core";
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';
import { ZeroDevSmartWalletConnectors } from '@dynamic-labs/ethereum-aa';
const App = () => (
);
export default App;
```
```jsx
import {DynamicContextProvider} from "@dynamic-labs/sdk-react-core";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import { EthereumSmartWalletConnectors } from "@dynamic-labs/ethereum-aa";
const App = () => (
);
export default App;
```
#### wallets -> walletConnectorOptions
* Wallets property returned by useDynamicContext now renamed to walletConnectorOptions
`````jsx
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
const App = () => {
const { walletConnectorOptions } = useDynamicContext();
return (
```jsx
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
const App = () => {
const { wallets } = useDynamicContext();
return (
#### walletsByChain -> bridgeChains
* walletsByChain has been renamed to bridgeChains
```jsx
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
const App = () => {
return (
); };
export default App;
```
```jsx
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
const App = () => {
return (
); };
export default App;
```
### Non Breaking Changes
* Turnkey wallets are now created as Turnkey HD wallets.
### New Features
* eip6963 is now fully supported without any need for changes on your end!
* Listening to changes in wallet connectors is now supported via a hook called useWalletConnectorEvent. See [here](/react-sdk/hooks/usewalletconnectorevent) for more info.
* You can now trigger the onramp flow programmatically using the useOnramp hook. See [here](/react-sdk/hooks/useonramp) for more info.
* Support for account recovery via a hook has been added. See [here](/react-sdk/hooks/usepasskeyrecovery) for more info.
* We now generate HD wallets by default, there is nothing you need to do to take advantage of this.
* You can now generate smart contract wallets (SCWs) using our Smart Wallet integrations. See [here](/smart-wallets/add-smart-wallets) for more info.
* All of the copy which is used in the UI from the SDK is now completely editable. See [here](/design-customizations/customizing-copy-translations) for more info.
* You can control what kind of signup/login options are shown in your UI on a programmatic basis regardless of what is enabled in the dashboard. See [here](/design-customizations/views) for more info.
* Embedded wallets has been split up into the generation step and the claim step which means you can now give a user a wallet but without them adding a passkey until they make their first transaction.
* Along the same lines as above, you can also pregenerate a wallet for a user without any interaction from them by using our API directly. See [here](https://docs.dynamic.xyz/api-reference/wallets/createWallet) for more info.
* Webhooks are now offered out of the box! You do not need to make any SDK changes to take advantage of this. See [here](/developer-dashboard/webhooks) for more info.
## From V0.18 to V0.19
### *Summary*
This upgrade guide is specific to implementing the SDK itself.
There are a number of breaking changes in v0.19, mainly to the way the SDK is structured. To upgrade you should follow three steps, which are outlined in the breaking changes section below.
Uninstall sdk-react (if used) and [install the latest sdk-react-core](/react-sdk/upgrade#sdk-react-sdk-react-core).
[Install the WalletConnectors you need](/react-sdk/upgrade#walletconnectors)
alongside the SDK and [use them in the
DynamicContextProvider](/react-sdk/upgrade#using-walletconnectors).
If you're happy for Viem to be the default instead of Ethers, do nothing. Otherwise, [use the Ethers extension](/react-sdk/upgrade#ethers-viem).
### Breaking Changes
#### sdk-react -> sdk-react-core
Previously you could use the SDK in two ways. The first was by installing `sdk-react` which came with all of the possible WalletConnectors pre-bundled. The second was by installing `sdk-react-core` and then adding WalletConnectors yourself alongside it.
While the first was helpful in getting started, the general feedback was that the bundle size was too large. So we've decided to remove the `sdk-react` package and make `sdk-react-core` the main way of installing the SDK.
To get started in this way, you should uninstall `sdk-react` and install `sdk-react-core` instead. If you're already using `sdk-react-core`, it's worth upgrading it to the latest version.
```bash
npm uninstall @dynamic-labs/sdk-react
npm install @dynamic-labs/sdk-react-core
```
#### WalletConnectors
As mentioned above, `sdk-react-core` doesn't come with any WalletConnectors pre-bundled.
There are also no more `all` packages available.
You should install them according to the table below.
| Package Name | Chain | WalletConnector to include |
| :--------------------- | :----- | -------------------------- |
| @dynamic-labs/ethereum | EVM | `EthereumWalletConnectors` |
| @dynamic-labs/algorand | ALGO | `AlgorandWalletConnectors` |
| @dynamic-labs/solana | SOL | `SolanaWalletConnectors` |
| @dynamic-labs/flow | FLOW | `FlowWalletConnectors` |
| @dynamic-labs/starknet | STARK | `StarknetWalletConnectors` |
| @dynamic-labs/cosmos | COSMOS | `CosmosWalletConnectors` |
##### EVM Addon Wallets
| Package Name | Which Wallets | WalletConnector to include |
| :----------------------- | :------------ | :-------------------------- |
| @dynamic-labs/magic | *magic* | `MagicWalletConnectors` |
| @dynamic-labs/blocto-evm | *blocto* | `BloctoEvmWalletConnectors` |
Magic and Blocto were previously available via the `ethereum-all` package
which is now deprecated, please note that you will no longer get Magic &
Blocto with the `ethereum` package - use the above packages instead.
Here's an example for Ethereum & Flow:
```bash
npm install @dynamic-labs/ethereum @dynamic-labs/flow
```
#### Using WalletConnectors
Using WalletConnectors looks like the following (ethereum and flow example):
```jsx
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import { FlowWalletConnectors } from "@dynamic-labs/flow";
const App = () => (
);
export default App;
```
#### Ethers -> Viem
We've also changed the way we interact with the BlockChain RPC and the Wallet. Previously we used Ethers.js by default and gave you a Viem version if you needed, but with Viem now rising further in popularity and functionality, we've now moved to Viem as the default library.
Please not that since Viem is now a peer dependancy of the SDK, it will be
installed even if you use Ethers.
If you're happy to use Viem, this should not have much of an effect on you. If you would still like to use Ethers or do not want to migrate your own application to using Viem, we have provided an extension for accessing Ethers within our Connectors:
```bash
npm i @dynamic-labs/ethers-v5
```
```jsx
import { EthersExtension } from '@dynamic-labs/ethers-v5'
return (
)
```
You can then access the signer like so:
```jsx
const signer = await primaryWallet.connector.ethers?.getSigner()
```
If you want to use Ethers V6 instead of V5, it's as simple as using
`@dynamic-labs/ethers-v6` instead of `@dynamic-labs/ethers-v5`.
#### WalletConnector methods naming
Since the move to Viem, we have also updated the method names on the WalletConnector as they previously used Ethers Terminology.
| V0.18 | V0.19 |
| :------------------ | :------------------ |
| `getWeb3Provider()` | `getPublicClient()` |
| `getRpcProvider()` | `getWalletClient()` |
#### onConnectSuccess -> onConnect
We've also renamed the `onConnectSuccess` callback to `onConnect`.
#### WalletIcon
| V0.18 | V0.19 |
| :------------------------------------------------------------------- | :-------------------------------------------- |
| `
```jsx Before
```
```jsx After
```
##### *Multiwallet prop has been removed.* If you have multiwallet enabled please enable it in your dashboard:
```jsx Before
{...}
```
```jsx After
{/* Enable multiwallet in your dashboard */}
{/* (Advanced wallet options) section of Configurations tab*/}
{...}
```
#### *Changes to DynamicContext*
##### *ConnectedWallets*
connectedWallets now represents all the wallets that are actually connected
```jsx
const { connectedWallets } = useDynamicContext()
```
##### *LinkedWallets*
Used to be called ConnectedWallets now only represents that wallets that are linked to the account (only relevant to connect-and-auth flow)
```jsx
const { linkedWallets } = useDynamicContext()
```
#### *Updates to Walletbook*
If you have a dependancy on [@dynamic-labs/walletbook](https://www.npmjs.com/package/@dynamic-labs/wallet-book?activeTab=versions) \< v0.19, please remove it from your dependancies as it should now be included by default alongside the sdk-react package.
## From V0.16 to V0.17
### Breaking Changes
* In favor of supporting MagicLink Wallets we removed the support for Fortmatic.
* `chainName` on EvmNetwork is deprecated in favor of `name`. If you're passing `evmNetworks` to `DynamicContextProvider` or `DynamicWagmiConnector`, you should update your code like so:
```ts
```
{' '}
`chainName` is a deprecated field on the EVMchain (and will be removed on v18),
but if you pass a custom EVM network you will need to change to `name`.
* the `multiWallet` prop on DynamicContextProvider is deprecated in favor of the Dashboard settings. See [here](/wallets/advanced-wallets/multi-wallet) for more info.
## From V0.15 to V0.16
### Breaking Change
* With the introduction of email login and social verification we moved to `verifiedCredentials` instead of `blockchainAccounts`. `blockChainAccounts` was removed from the [user's object](/react-sdk/objects/userprofile).
## From V0.14 to V0.15
### Breaking Change
* Based on your feedback, our team has been hard at work to completely redesign our SDK UI and move it to ShadowDom. Now in addition, to the default customizations that we provide in the our admin dashboard, you have full control and ability to customize any element in the Dynamic's SDK to your liking. If you previously used any CSS Classes to override our previous SDK modal you will need to update them to the current CSS classes.
For more info see: [Custom CSS](/design-customizations/css/custom-css).
* As we introduced more callbacks, we now require all the callbacks to be nested under events. See [Callbacks](/react-sdk/events) for more info.
* We removed user.walletPublicKey, instead please use primaryWallet.address, which you can access from [useDynamicContext](/react-sdk/hooks/usedynamiccontext).
# Upgrade from V1 to V2
Source: https://docs.dynamic.xyz/react-sdk/upgrade/v2
### Breaking changes
* `setShowAuthFlow` opens dynamic profile in non-multi-wallet, logged in states
#### Packages
* sdk-api to sdk-api-core
The Dynamic SDK uses a number of other Dynamic packages, among them is the sdk-api library which contains several internal APIs that are not relevant to making the SDK communicate properly with Dynamic's backend.
Therefore we've created a new package called sdk-api-core which only contains endpoints and models relevant for the SDK, and this is what the V2 SDK uses.
If you need to interact with Dynamic's backend for admin-related API calls or bulk work, among other things, you should explicitly install sdk-api, otherwise the only effect this has is lowering your bundle size!
* Wagmi V2
We now use Wagmi V2 by default as opposed to V1 in V1 of our SDK, you can find the implementation guide [here](/react-sdk/using-wagmi) to upgrade that package implementation and integration.
* Viem V2
Viem V2 is now the default, generally you don't need to do anything as the SDK will install it for you but if you have Viem installed manually alongside the SDK, you'll want to either uninstall it or ensure you're using the latest version.
#### Renamed variables/props
* useConnectWithEmailOtp to useConnectWithOtp
With the introduction of sms based login in addition to email we've adjusted some method naming to reflect this. Thus, useConnectWithEmailOtp becomes useConnectWithOtp.
* fetchPublicAddress to getAddress
This renaming is simply to align with standard terminology.
* hideEmbeddedWalletUIs prop to hideEmbeddedWalletTransactionUIs
This prop was not specific enough so we renamed it to include "Transaction" as this is exactly what it hides - the transaction confirmation screens.
* canConnectViaEmail to requiresNonDynamicEmailOtp
This flag is actually used to decide whether a wallet connector requires an external OTP provider instead of Dynamic's default email OTP and therefore it made sense to rename it as such.
#### Removed variables/props
* isVerificationInProgress
This was a boolean, available from useDynamicContext, which indicated whether any verifications are in progress for the current user (ex. connect, sign and email login verifications). However, this leads to the need for useEffects, which [the React team recommends avoiding](https://react.dev/learn/you-might-not-need-an-effect). Therefore we've remove this state and request that you add listeners to [our callbacks](/react-sdk/events/events-introduction) in order to trigger functionalities in an event driven manner.
* isFullyConnected
You can now use [useIsLoggedIn](/react-sdk/hooks/useisloggedin) instead of isFullyConnected to check the user's login status.
#### Replaced variables/props
* enableForcedNetworkValidation -> networkValidationMode
The type looks like the following:
```typescript
export type NetworkValidationMode = 'always' | 'sign-in' | 'never'
```
Use looks like this:
```jsx
const settings = {
enableForcedNetworkValidation: true,
}
```
```jsx
const settings = {
networkValidationMode: 'always'
}
```
* onEmailVerificationSuccess & onEmailVerificationFailure -> onOtpVerificationResult
With the introduction of SMS authentication as well as pre-existing email authentication, it makes more sense to generalise the verification callbacks for you, rather than having 4 individual ones. Therefore we've created `onOtpVerificationResult` so you can easily listen to success and failure for email and sms.
The signature of this new callback looks like the following
```typescript
export type OnOtpVerificationResult = (
isSuccess: boolean,
destination:
| {
type: Extract
value: string
}
| {
type: Extract
value: PhoneEventData
}
) => void
```
The usage of the callback is outlined as such:
```jsx
const DynamicSettings = {
eventsCallbacks: {
onEmailVerificationSuccess: (email) => handleSuccess(email),
onEmailVerificationFailure: (email) => handleFailure(email),
},
};
```
```jsx
const DynamicSettings = {
eventsCallbacks: {
onOtpVerificationResult: (isSuccess, destination) => {
if (destination.type !== "email") return;
if (isSuccess) handleSuccess(destination.value);
else handleFailure(destination.value);
},
},
};
```
#### Moved variables/props
* setShowLinkNewWalletModal
setShowLinkNewWalletModal is not part of DynamicContext anymore, but is available as part of the new useDynamicModals hook.
`const {setShowLinkNewWalletModal} = useDynamicContext();`
`const {setShowLinkNewWalletModal} = useDynamicModals();`
* evmNetworks
[evmNetworks](/react-sdk/objects/evmNetwork) now lives inside the `overrides` prop on the DynamicContextProvider settings object, whereas before it lived directly in the settings object.
```jsx
```
```jsx
### ERC 1155 support
Our NFT Gating feature helps you gate by NFT ownership. We've now added support for ERC 1155 tokens, so you can now gate by NFT ownership for both ERC 721 and ERC 1155 token types!
### New [webhooks](/developer-dashboard/webhooks) added
* user.passkeyRecovery.started
* user.passkeyRecovery.completed
* user.social.linked
* user.social.unlinked
* wallet.transferred
* visit.created
### userId in all webhook payloads
You wanted an easier way to always have the userId of the user that triggered the event - now we also include the userId of the trigger in all webhook event objects!
### New hooks & methods
* [showDynamicUserProfile](https://docs.dynamic.xyz/react-sdk/components/dynamicuserprofile#callback-at-closing-or-opening)
Currently the setShowDynamicUserProfile method exists on useDynamicContext which helps you trigger the user profile modal, however you had no way of knowing if the modal was open or not. Now you can use the showDynamicUserProfile boolean to get this information.
```jsx
export const Example = () => {
const { showDynamicUserProfile } = useDynamicContext()
React.useEffect(() => {
if (showDynamicUserProfile) {
/* On widget opens */
} else {
/* On widget closes */
}
}, [showDynamicUserProfile])
return null
}
```
* [useConnectWithEmailOtp](https://docs.dynamic.xyz/react-sdk/hooks/useconnectwithemailotp)
Now you can handle headless email signup with the useConnectWithEmailOtp hook! It exposes `connectWithEmail` and `verifyOneTimePassword` functions. It supports both Dynamic native login and our Magic integration.
* [setShowLinkNewWalletModal](https://docs.dynamic.xyz/react-sdk/hooks/usedynamiccontext#setshowlinknewwalletmodal-use-it-to-link-a-new-wallet-when-the-user-is-logged-in)
This new method comes as part of `useDynamicContext` and allows you to trigger the link new wallet method programmatically.
```jsx
const LinkNewWalletButton = () => {
const { setShowLinkNewWalletModal } = useDynamicContext()
return (
)
}
```
* [setAuthMode](https://docs.dynamic.xyz/react-sdk/hooks/usedynamiccontext)
Previously, you could set the auth mode via the `initialAuthenticationMode` prop on `DynamicContextProvider` but this would be set in stone once the app loads. Now you can also set it programmatically via the `setAuthMode` method on `useDynamicContext`.
```jsx
const Example = () => {
const { setAuthMode } = useDynamicContext()
return (
)
}
```
### New callbacks
* [onAuthFlowCancel](https://docs.dynamic.xyz/react-sdk/events/onauthflowcancel)
This callback is triggered when the user cancels the auth flow before successful completion. It will get called alongside [onAuthFlowClose](https://docs.dynamic.xyz/react-sdk/events/onauthflowclose).
### Extra text in the signup/login UI
* Additional views section for extra text in the signup/login UI
If you use [Programmable Views](/design-customizations/views), you can now insert extra text:
```js
views: [
{
type: 'login',
sections: [
{ type: 'text', label: 'Intro Text', alignment: 'center' },
...
],
},
],
```
### Multi-wallet prompts without userProfile widget
* New [multiWalletPromptsWidget](https://docs.dynamic.xyz/react-sdk/components/dynamicmultiwalletpromptswidget)
This allows you to use the multi wallet prompts without needing the full user profile which in which these prompts are normally bundled.
# Upgrade from V2 to V3
Source: https://docs.dynamic.xyz/react-sdk/upgrade/v3
## Changes in 3.0.0-alpha.53 -> latest
See [here](/react-sdk/upgrade/v3#2-x-x-to-3-0-0-alpha-52) for changes from 2.x.x to 3.0.0-alpha.52
### Wallet and WalletConnectors
#### No undesired prompting
No more undesired prompting to reconnect or switch wallets when not required!
Now a wallet can be made primary at any time without extra prompting, even if the wallet is not connected or unlocked.
Users will only be prompted to connect/unlock when sending/signing a transaction if the wallet is not connected or unlocked already.
#### Wallet object has changed
* wallet.authenticated changed to wallet.isAuthenticated
* wallet.connected is now an async method wallet.isConnected()
* wallet.network is now an async method wallet.getNetwork()
* wallet.chain valid values have changed
We used to use values like 'eip155' for wallet.chain. This is no longer the case. The new valid values for wallet.chain are the following:
```
'ALGO' | 'BTC' | 'COSMOS' | 'EVM' | 'FLOW' | 'SOL' | 'STARK'
```
The Wallet object has changed and now contains some methods that were previously on the WalletConnector object. Each chain specific wallet has its own methods. The methods specific to the main chains on the wallet object are:
* EthereumWallet
* getPublicClient
* getWalletClient
* SolanaWallet
* getConnection
* getSigner
* BitcoinWallet
* sendBitcoin
* sendRawTransaction
* signMessageWithAddress
* signPsbt
* signPsbts
* CosmosWallet
* getOfflineSigner
* getProvider
* StarknetWallet
* getProvider
* getWalletAccount
* AlgorandWallet
* getSigner
### Wallet type checking
You should always use our utilities to check that you're dealing with the correct wallet type before calling the wallet specific methods.
```tsx
import { isEthereumWallet } from '@dynamic-labs/ethereum';
import { isSolanaWallet } from '@dynamic-labs/solana';
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
const { primaryWallet } = useDynamicContext();
if (isEthereumWallet(primaryWallet)) {
console.log('call any ethereum wallet method')
}
if (isSolanaWallet(primaryWallet)) {
console.log('call any solana wallet method')
}
if (isBitcoinWallet(primaryWallet)) {
console.log('call any bitcoin wallet method')
}
```
Learn more in the [Wallet Interactions section](/wallets/using-wallets/interacting-with-wallets).
#### Wallet connector object has changed
Since we have moved some methods from the connector to the wallet object, the wallet connector object is now slimmed down, you can find the methods and props available on both the connector and the wallet object in the [Wallet Interactions section](/wallets/using-wallets/interacting-with-wallets).
As with the wallet object, each chain specific wallet connector has its own methods so we recommend checking out the appropriate section for the chain you are working with.
```jsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
const { primaryWallet } = useDynamicContext()
const fetchBalance = async () => {
const balance = await primaryWallet?.connector.getBalance()
}
```
```jsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
const { primaryWallet } = useDynamicContext()
const fetchBalance = async () => {
const balance = await primaryWallet?.getBalance()
}
```
### Return value type changes
In V2, you needed to type method return values on specific wallet methods like fetching the Viem public client, Viem wallet client, Solana connection etc. In V3, you no longer need to do this.
All you have to do is check for the wallet type (as shown in the previous section), and all the methods will come typed for you.
```tsx
import { WalletClient, Transport, Chain, Account } from 'viem'
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
const { primaryWallet } = useDynamicContext()
const walletClient = await primaryWallet.connector.getWalletClient<
WalletClient
> ();
```
```tsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
import { isEthereumWallet } from '@dynamic-labs/ethereum'
const { primaryWallet } = useDynamicContext()
if (!isEthereumWallet(primaryWallet)) {
throw new Error('This wallet is not a Ethereum wallet');
}
const walletClient = await primaryWallet.getWalletClient()
```
### Smart Wallet connector updates
* getEOAConnector has been removed
The `getEOAConnector` method is no longer available, you can use [the useSmartWallets hook](/react-sdk/hooks/usesmartwallets) to get the EOA wallet.
```tsx
import { isZeroDevConnector } from "@dynamic-labs/ethereum-aa";
const Component = () => {
const { primaryWallet } = useDynamicContext()
const { connector } = primaryWallet
if (!isZeroDevConnector(connector)) {
return;
}
const signerConnector = connector.getEOAConnector()
if (!signerConnector) {
return;
}
// Do your thing!
};
```
```tsx
import { useSmartWallets } from '@dynamic-labs/sdk-react-core'
const Component = () => {
const { getEOAWallet } = useSmartWallets()
const { primaryWallet } = useDynamicContext()
const signer = getEOAWallet(primaryWallet)
// Do your thing!
};
```
### Ethers support refactored
Instead of using the `EthersExtension` on the Context Provider, you now need to use the `ethers-v6` package directly, which exports all of the Ethers specific methods.
```jsx
// App.tsx
import { EthersExtension } from '@dynamic-labs/ethers-v6'
// Main.tsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
const { primaryWallet } = useDynamicContext()
const signer = primaryWallet?.connector.ethers?.getSigner();
```
```jsx
// App.tsx
// Main.tsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
import { getSigner } from '@dynamic-labs/ethers-v6'
const { primaryWallet } = useDynamicContext()
const signer = await getSigner(primaryWallet)
```
### Helper method removed
* createWalletClientFromWallet has been removed
The createWalletClientFromWallet function is no longer available, you can use the `getWalletClient` method on the wallet object instead.
```tsx Before
import { createWalletClientFromWallet } from '@dynamic-labs/sdk-react-core';
```
```tsx After
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
const { primaryWallet } = useDynamicContext()
const walletClient = await primaryWallet?.getWalletClient()
```
### SignWithEmailWalletName has been removed
Instead please use the available email login flows
## 2.X.X to 3.0.0-alpha.52
### Packages restructuring
#### Solana Utils
@dynamic-labs/solana-utils has been renamed to @dynamic-labs/solana-core
#### Viem Utils
@dynamic-labs/viem-utils has been renamed to @dynamic-labs/ethereum-core
#### Ethereum RPC provider
@dynamic-labs/rpc-provider-ethereum has been removed. You can now use @dynamic-labs/ethereum-core to get the RPC provider.
#### Solana RPC provider
@dynamic-labs/rpc-provider-solana has been removed. You can now use @dynamic-labs/solana-core to get the RPC provider.
#### Starknet RPC provider
@dynamic-labs/rpc-provider-starknet has been removed. You can now use @dynamic-labs/starknet-core to get the RPC provider.
### UserProfile
Removed props that should be retrieved from the primaryWallet: `chain`, `ens`, `wallet`
Remove `isAuthenticatedWithAWallet` as a prop and added it as a helper method.
See [isAuthenticatedWithAWallet](/react-sdk/utilities/isauthenticatedwithawallet)
### Removed props from `useDynamicContext`
`hideEmbeddedWalletTransactionUIs` has been removed from useDynamicContext. This is now [a toggle in the dashboard](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic).
`setPrimaryWallet` has been removed. You should use [useSwitchWallet](/react-sdk/hooks/useswitchwallet#useswitchwallet) instead.
`isAuthenticated` has been removed. Please refer to [this page](/react-sdk/loading-login-states) for other ways to check the login state.
`walletConnector` has been removed. You can get access to it by getting the primary wallet prop and doing `primaryWallet?.connector`.
`walletConnectorOptions` has been removed. You can get access to the available wallet options from the [useWalletOptions hook](/react-sdk/hooks/usewalletoptions).
### Replaced props
* `setDefaultTabIndex` replaced with `setSelectedTabIndex` in useDynamicContext
This function is used to create [wallet list views](/design-customizations/tutorials/wallet-list-views-guide).
```tsx Before
const { setDefaultTabIndex } = useDynamicContext()
const onChangeTab = (index: number) => {
setDefaultTabIndex(index)
}
```
```tsx After
const { setSelectedTabIndex } = useDynamicContext()
const onChangeTab = (index: number) => {
setSelectedTabIndex(index)
}
```
### Package restructuring
* ethers-v5 no longer available
We no longer support ethers v5. If you are using ethers v5 and wish to keep using ethers with Dynamic,
please upgrade to ethers v6 by following [this guide](https://docs.ethers.org/v6/migrating/), and then switch
to using our `ethers-v6` package. They have the same usability.
* rpcProviders no longer available in the sdk-react-core packages
The type DynamicRPCProviders that used to be exported from @dynamic-labs/sdk-react-core is no longer available and has been replaced with individual packages i.e. `@dynamic-labs/ethereum-core` & `@dynamic-labs/solana-core`:
```tsx Before
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const App = () => {
const { rpcProviders } = useDynamicContext();
console.log(rpcProviders.evmProviders);
console.log(rpcProviders.solanaProviders);
}
```
```tsx After
import { useRpcProviders } from '@dynamic-labs/sdk-react-core';
import { evmProvidersSelector } from '@dynamic-labs/ethereum-core';
import { solanaProvidersSelector } from '@dynamic-labs/solana-core';
const App = () => {
const { providers: evmProviders } = useRpcProviders(evmProvidersSelector);
const { providers: solanaProviders } = useRpcProviders(solanaProvidersSelector);
console.log(evmProviders);
console.log(solanaProviders);
}
```
* ITurnkeySolanaSigner renamed to IEmbeddedWalletSolanaSigner and import path changed
```tsx Before
import { ITurnkeySolanaSigner } from '@dynamic-labs/turnkey';
```
```tsx After
import { IEmbeddedWalletSolanaSigner } from '@dynamic-labs/solana'
```
### Events arguments
* [onAuthSuccess](/react-sdk/events/onauthsuccess) doesn't return an authToken anymore
* onEmbeddedWalletCreated returns the user instead of the authToken
You can call [getAuthToken](/react-sdk/utilities/getauthtoken) to access the authToken at any time!
### Other
* Polyfill for Solana Embedded Wallet users
You may need to polyfill the 'crypto' module.
webpack.config.js:
```typescript
config.resolve.fallback = {
...config.resolve.fallback,
crypto: require.resolve('crypto-browserify'),
}
```
vite.config.ts
```typescript
import { nodePolyfills } from 'vite-plugin-node-polyfills';
plugins: [
nodePolyfills({
globals: {
global: true,
},
include: [],
}),
],
```
### Renamed Hooks
`useSelectWalletOption` has been renamed to `useWalletOptions`
### New Hooks
* Re-initialize the SDK (useReinitialize)
```tsx
import {
DynamicContextProvider,
useReinitialize,
} from '@dynamic-labs/sdk-react-core';
const ReInitButton = () => {
const reinitialize = useReinitialize();
return (
);
}
const App = () => {
return (
)
}
```
* Trigger state refresh (useRefreshUser)
```tsx
import {
DynamicContextProvider,
useRefreshUser,
} from '@dynamic-labs/sdk-react-core';
const RefreshButton = () => {
const refresh = useRefreshUser();
return (
);
}
const App = () => {
return (
)
}
```
```
```
# Upgrade from V3 to v4
Source: https://docs.dynamic.xyz/react-sdk/upgrade/v4
Below are the breaking changes in V4 so far. If you don't see anything you'll be affected by, you can skip this guide and simply update your SDK package to [the latest V4](https://www.npmjs.com/package/@dynamic-labs/sdk-react-core?activeTab=versions). Just make sure to also upgrade all your other dynamic packages too!
### Breaking changes
#### Starknet V6
We upgraded to Starknet v6 See this guide for more details: [https://starknetjs.com/docs/guides/migrate/](https://starknetjs.com/docs/guides/migrate/)
There are no code changes required on the Dynamic SDK side, however if you have installed the starknet package, you will need to upgrade to >= v6.11.0.
#### Walletbook methods
isWalletMethodSupported and isWalletEventSupported have been removed from wallet-book as part of a refactor to improve the way the SDK operates.
### eventsCallbacks removed
In V2, we deprecated the eventsCallbacks prop on the DynamicContextProvider in favour of a prop called `events` which has the same purpose. In V4 we are removing the old prop entirely.
### authToken and minAuthToken
In V4 we stopped exporting authToken and minAuthToken from the dynamic context. You can still get these values by calling `getAuthToken` and `getMinAuthToken`.
Note that if you just want to know if the user is logged in or not, you can use the `useIsLoggedIn` hook.
### useFunding hook method changed
In V4, we changed the `openFunding` method exported from `useFunding` hook to `openExternalFunding` which now takes in a required parameter of `onrampProvider`.
#### ZeroDev package upgraded to 5.4.5
In V4, we updated the ZeroDev package to 5.4.5 which contains some breaking changes regarding the kernel client. [Learn more here](https://docs.zerodev.app/sdk/getting-started/migration#sdk-53x--54x)
### New features
#### Events
[`useDynamicEvents`](/react-sdk/hooks/usedynamicevents) which allows you to listen to events emitted by the SDK now exposes more events. The full list of available events is now:
*Auth Events*
authFailure
authFlowCancelled
authFlowClose
authFlowOpen
authInit
logout
*Wallet Events*
walletAdded
walletRemoved
embeddedWalletCreated
primaryWalletChanged
primaryWalletNetworkChanged
userWalletsChanged
*OTP/MFA Events*
emailVerificationResult
smsVerificationResult
mfaCompletionFailure
mfaCompletionSuccess
# Using Ethers
Source: https://docs.dynamic.xyz/react-sdk/using-ethers
The SDK and above ships with Viem by default as it is much lighter than Ethers and is generally more performant.
We have also made viem a peerDependency to avoid bundling it multiple times, as other packages such as wagmi also need it.
For the above reason, viem will be installed as a peerDependency when you install the SDK with npm, even if you want to use Ethers.
If you are using yarn instead of npm, even if you want to use Ethers, you will need to install viem manually:
```bash
yarn i viem
```
Dynamic only supports version v6+ of Ethers. In order to use it, simply import the ethers methods you need from `@dynamic-labs/ethers-v6` directly in the component where you are using them.
```bash
npm i @dynamic-labs/ethers-v6
```
```jsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
import { getWeb3Provider,getSigner, } from '@dynamic-labs/ethers-v6'
const { primaryWallet } = useDynamicContext()
const provider = await getWeb3Provider(primaryWallet)
const signer = await getSigner(primaryWallet)
// do your thing
```
# Using Wagmi
Source: https://docs.dynamic.xyz/react-sdk/using-wagmi
The default SDK implementation does not use Wagmi, but you can add full support for it by following the steps below.
#### Installing packages
First, you want to install the DynamicWagmiConnector package using `npm` or `yarn`
```shell npm
npm install viem wagmi @tanstack/react-query @dynamic-labs/wagmi-connector @dynamic-labs/sdk-react-core @dynamic-labs/ethereum
```
```shell yarn
yarn add viem wagmi @tanstack/react-query @dynamic-labs/wagmi-connector @dynamic-labs/sdk-react-core @dynamic-labs/ethereum
```
```shell pnpm
pnpm add viem wagmi @tanstack/react-query @dynamic-labs/wagmi-connector @dynamic-labs/sdk-react-core @dynamic-labs/ethereum
```
#### Configure Wagmi and Dynamic
Here's a full code snippet with all the setup code required.
```TypeScript
import {
DynamicContextProvider,
DynamicWidget,
} from '@dynamic-labs/sdk-react-core';
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';
import { DynamicWagmiConnector } from '@dynamic-labs/wagmi-connector';
import {
createConfig,
WagmiProvider,
useAccount,
} from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { http } from 'viem';
import { mainnet } from 'viem/chains';
const config = createConfig({
chains: [mainnet],
multiInjectedProviderDiscovery: false,
transports: {
[mainnet.id]: http(),
},
});
const queryClient = new QueryClient();
export default function App() {
return (
);
}
function AccountInfo() {
const { address, isConnected, chain } = useAccount();
return (
);
};
```
Two things to note here:
1. `multiInjectedProviderDiscovery` is set to `false` – this is because Dynamic implements the multi injected provider discovery protocol itself. If you'd like to keep this enabled on Wagmi, please do, but you might see some undefined behavior and we might not be able to debug.
2. While this example configures mainnet as the only chain, you can pass in all your supported chains to the `chains` array. For more info, see the "Chain Configuration" section below.
Throughout your app, you can now use Wagmi hooks like `useAccount` and they will automatically sync to the wallet that you logged in with via Dynamic.
Make sure to call `createConfig` at the top-level of your app. If you call it
inside of a component, it will be called during each render, which can lead to
unexpected behavior.
#### Chain Configuration
If you are upgrading from Dynamic + Wagmi v1, then this config will look new to you. Previously, Dynamic was automatically updating the Wagmi config with the chains that you configured in your Dynamic Dashboard.
This behavior has changed in v2 to give you more control over your Wagmi config and for a simpler integration. What this means is that you will need to pass to Wagmi all of the chains you have configured with Dynamic.
For example, if in Dynamic you have enabled Ethereum Mainnet, Optimism and Base, you will need to update your Wagmi config to look like this:
```TypeScript
import {
createConfig,
WagmiProvider,
} from 'wagmi';
import { http } from 'viem';
import { mainnet, optimism, base } from 'viem/chains';
const config = createConfig({
chains: [mainnet, optimism, base],
multiInjectedProviderDiscovery: false,
transports: {
[mainnet.id]: http(),
[optimism.id]: http(),
[base.id]: http(),
},
});
```
### Adding Custom Networks
As you probably already know, you can add a custom EVM network through Dynamic using [the evmNetworks prop](/chains/evmNetwork). If you want to use these custom networks with Wagmi, you will need to declare it in your Wagmi config.
You can use our util function called [getOrMapViemChain](/react-sdk/utilities/getormapviemchain) to convert the EVM network object to a Viem chain object.
Here's an example of adding the Morph network to both Dynamic and to the Wagmi config:
```tsx
import {
createConfig,
WagmiProvider,
} from 'wagmi';
import { http } from 'viem';
import { getOrMapViemChain } from '@dynamic-labs/ethereum-core';
const customEvmNetworks = [
{
blockExplorerUrls: ["https://explorer-holesky.morphl2.io/"],
chainId: 2810,
name: "Morph",
rpcUrls: ["https://rpc-quicknode-holesky.morphl2.io"],
iconUrls: ["https://avatars.githubusercontent.com/u/132543920?v=4"],
nativeCurrency: {
name: "Ethereum",
symbol: "ETH",
decimals: 18,
},
networkId: 2810,
},
]
export const wagmiConfig = createConfig({
chains: [
mainnet,
...customEvmNetworks.map(getOrMapViemChain),
],
client({ chain }) {
return createClient({
chain,
transport: http(),
});
},
});
```
### Adding Private RPCs
Note that if you are using [a private RPC in Dynamic](/chains/rpc-urls#dashboard-configuration), you will also need to declare that in your Wagmi config. Luckily this is as simple as passing it into your http transport in Wagmi:
```tsx
import {
createConfig,
WagmiProvider,
} from 'wagmi';
export const wagmiConfig = createConfig({
chains: [mainnet],
multiInjectedProviderDiscovery: false,
transports: {
[mainnet.id]: http('your-private-rpc-url'),
},
});
```
### Further Resources
For docs on `createConfig`, see: [https://wagmi.sh/react/api/createConfig](https://wagmi.sh/react/api/createConfig)
For more general information on what you can do with Wagmi, check out their getting started docs: [https://wagmi.sh/react/getting-started](https://wagmi.sh/react/getting-started)
# getAuthToken
Source: https://docs.dynamic.xyz/react-sdk/utilities/getauthtoken
This utility can be used to get a JWT token generated by Dynamic which is stored inside of localStorage.
```TypeScript
import { getAuthToken } from "@dynamic-labs/sdk-react-core";
const App = () => {
const dynamicJwtToken = getAuthToken()
...
}
```
# getNetwork
Source: https://docs.dynamic.xyz/react-sdk/utilities/getnetwork
### Summary
This utility function should be used to find the current network used by a wallet. It receives the wallet connector and returns a promise that will resolve with the network.
### Annotation
TypeScript
`const getNetwork: (walletConnector: WalletConnector | null) => Promise
`
### Examples
##### Get primary wallet network
TypeScript
```TypeScript
import { useDynamicContext, getNetwork } from '@dynamic-labs/sdk-react-core';
const App = () => {
const { primaryWallet } = useDynamicContext();
useEffect(() => {
primaryWallet.connector.getNetwork().then((network) => {...});
}, [primaryWallet]);
...
}
```
##### Get a network for all wallets
TypeScript
```TypeScript
import { useUserWallets, getNetwork } from '@dynamic-labs/sdk-react-core';
const App = () => {
const userWallets = useUserWallets();
useEffect(() => {
userWallets.forEach(async ({ connector }) => {
const network = await getNetwork(connector);
...
});
}, [userWallets]);
...
}
```
# getOrMapViemChain
Source: https://docs.dynamic.xyz/react-sdk/utilities/getormapviemchain
## Summary
This utility gets the Viem chain object for a given chain id, it is imported from `@dynamic-labs/ethereum-core`.
## Annotation
```TypeScript
export declare const getOrMapViemChain: (network: EvmNetwork) => Chain;
```
## Example
A common usage is when you declare your own [custom EVM networks](/chains/evmNetwork) for Dynamic, and you want to get the Viem chain objects for each so that you can pass them to your Wagmi config:
```tsx
import { DynamicContextProvider, mergeNetworks } from "@dynamic-labs/sdk-react-core";
import { getOrMapViemChain } from "@dynamic-labs/ethereum-core";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector";
import { createConfig, WagmiProvider } from "wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { http, createClient } from "viem";
import { mainnet } from "viem/chains";
import Main from "./Main";
const customEvmNetworks = [
{
blockExplorerUrls: ["https://explorer-holesky.morphl2.io/"],
chainId: 2810,
name: "Morph",
rpcUrls: ["https://rpc-quicknode-holesky.morphl2.io"],
iconUrls: ["https://avatars.githubusercontent.com/u/132543920?v=4"],
nativeCurrency: {
name: "Ethereum",
symbol: "ETH",
decimals: 18,
},
networkId: 2810,
},
];
const config = createConfig({
chains: [mainnet, ...customEvmNetworks.map(getOrMapViemChain)],
multiInjectedProviderDiscovery: false,
client({ chain }) {
return createClient({
chain,
transport: http(),
});
},
});
const queryClient = new QueryClient();
export default function App() {
return (
mergeNetworks(customEvmNetworks, networks),
}
}}
>
);
}
```
# isZeroDevConnector
Source: https://docs.dynamic.xyz/react-sdk/utilities/is-zero-dev-connector
### Summary
Utility to determine if a wallet connector is a ZeroDev connector.
This is useful for interacting with ZeroDev and keep typesafety.
### Annotation
TypeScript
```ts
isZeroDevConnector(connector: WalletConnector): boolean
```
### Examples
Get the ZeroDev ECDSAProvider from the connector
```tsx
import { isZeroDevConnector } from '@dynamic-labs/ethereum-aa';
const App = () => {
const { primaryWallet } = useDynamicContext();
useEffect(() => {
const { connector } = primaryWallet;
if (isZeroDevConnector(connector)) {
const ecdsaProvider = connector.getAccountAbstractionProvider();
}
}, [primaryWallet]);
...
}
```
# isAuthenticatedWithAWallet
Source: https://docs.dynamic.xyz/react-sdk/utilities/isauthenticatedwithawallet
This utility can be used check if the user has authenticated with a wallet.
```TypeScript
import { isAuthenticatedWithAWallet } from "@dynamic-labs/sdk-react-core";
const App = () => {
const authenticatedWithAWallet = isAuthenticatedWithAWallet(user)
...
}
```
# isLedgerSolanaWallet
Source: https://docs.dynamic.xyz/react-sdk/utilities/isledgersolanawallet
Determine if a given wallet is connected as a Ledger Solana wallet.
```TypeScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
import { isLedgerSolanaWallet } from "@dynamic-labs/solana-core";
const App = () => {
const { primaryWallet } = useDynamicContext()
if (primaryWallet && isLedgerSolanaWallet(primaryWallet)) {
/**
* This block will execute if the primaryWallet was connected
* as a Ledger wallet on the Solana blockchain during the
* Dynamic UI connection process.
*/
}
}
```
# mergeNetworks
Source: https://docs.dynamic.xyz/react-sdk/utilities/mergenetworks
## Summary
This utility function merges two arrays of `GenericNetwork` objects, with the first array taking precedence in case of a conflict. It is imported from `@dynamic-labs/sdk-react-core`.
## Annotation
```TypeScript
export declare const mergeNetworks: (priorityNetworks: GenericNetwork[], secondaryNetworks: GenericNetwork[]) => GenericNetwork[];
```
## Example
It is commonly used when you declare [custom EVM networks](/chains/evmNetwork) or [custom SVM networks](/chains/solNetwork) for Dynamic, and you want to merge them with the networks you get from the dashboard configurations:
```TypeScript
import { mergeNetworks } from "@dynamic-labs/sdk-react-core";
const myEvmNetworks = [
...
]
const mySolNetworks = [
...
]
const DynamicSettings = {
overrides: {
evmNetworks: (networks) => mergeNetworks(myEvmNetworks, networks),
solNetworks: (networks) => mergeNetworks(mySolNetworks, networks),
}
};
```
# overrideNetworkRpcUrl
Source: https://docs.dynamic.xyz/react-sdk/utilities/overridenetworkrpcurl
## Summary
This utility function overrides the rpc urls in the array of `GenericNetwork` with the new rpc url specified per network. If no rpc url is specified for a given network, it will use the default rpc url from the dashboard. This function is imported from `@dynamic-labs/sdk-react-core`.
## Annotation
```TypeScript
export declare const overrideNetworkRpcUrl: (networks: GenericNetwork[], rpcUrlOverrides: Record) => GenericNetwork[];
```
## Example
It is commonly used when you set rpc urls for a networks in the dashboard, and you want to override them for a specific network in certain implementations of your environment.
```TypeScript
import { overrideNetworkRpcUrl } from "@dynamic-labs/sdk-react-core";
const evmRpcUrlOverrides = {
"1": ["https://eth.customrpc.com"],
"137": ["https://polygon.customrpc.com"]
}
const solRpcUrlOverrides = {
"101": ["https://sol.customrpc.com"],
"201": ["https://eclipse.customrpc.com"]
}
const DynamicSettings = {
overrides: {
evmNetworks: (networks) => overrideNetworkRpcUrl(networks, evmRpcUrlOverrides),
solNetworks: (networks) => overrideNetworkRpcUrl(networks, solRpcUrlOverrides),
}
};
```
# Utilities Introduction
Source: https://docs.dynamic.xyz/react-sdk/utilities/utilities-introduction
You can think of utilities as helper functions on top of the SDK. You could implement them yourself, but we've found that these are common tasks and so have done the legwork for you.
You can import them directly from the @dynamic-labs/sdk-react-core package, for example:
```jsx
import { getAuthToken } from "@dynamic-labs/sdk-react-core";
```
[**getAuthToken**](/react-sdk/utilities/getauthtoken): Used to get a JWT token generated by Dynamic which is stored inside of localStorage
[**getNetwork**](/react-sdk/utilities/getnetwork): Used to find the current network used by a wallet. It receives the wallet connector and returns a promise that will resolve with the network.
[**isZeroDevConnector**](/react-sdk/utilities/is-zero-dev-connector): Used to type check if a wallet connector is a ZeroDev connector
[**isAuthenticatedWithAWallet**](/react-sdk/utilities/isauthenticatedwithawallet): Used to check is the user has authenticated with a wallet
[**isLedgerSolanaWallet**](/react-sdk/utilities/isledgersolanawallet): Determine if a given wallet is connected as a Ledger Solana wallet
# Overview
Source: https://docs.dynamic.xyz/security/overview
At Dynamic, security is foundational to everything we do. We believe in transparency and collaboration with our developer community to ensure robust protection for both developers and users. Both of which are fundamental when building secure systems and addressing potential threats head on. Our approach is guided by the following principles:
* **Proactive security:** We conduct regular top-tier audits, continuous testing, and operate a bug bounty program to identify and remediate potential vulnerabilities before they can be exploited.
* **Active monitoring and defensive measures:** We have real-time monitoring and automated response mechanisms that allow us to swiftly mitigate emerging threats and suspicious activities.
* **Multi-layered security:** We implement multiple layers of security, including Trusted Execution Environments (TEEs), Threshold Signature Scheme Multi-Party Computation (TSS-MPC), encryption, authentication safeguards, and strict code-review and state management policies. These measures are designed to provide comprehensive protection of wallets or software created by Dynamic.
* **SOC 2 compliance:** As a SOC 2 Type II compliant organization, we affirm the effectiveness of our security processes and controls. This certification underscores our commitment to maintaining the highest standards of security and trustworthiness.
* **Disaster recovery and mitigation strategies:** We conduct regular disaster scenarios and readiness to assist developers in protecting applications and wallets. If there are disruptions or issues, we are here and with you.
* **Trust, transparency and collaboration:** Threats and attacks in web3 are a common occurrence. By prioritizing transparency and collaboration with our Developer community, we ensure that security remains a shared responsibility, reinforcing trust and resilience in our offering.
**Important note:** Dynamic will never request login codes, secrets, or any information that could be used for impersonation. If you receive requests, it is likely a scam, and should be reported.
# Best Practices
Source: https://docs.dynamic.xyz/security/recommendedpaths
## Overview
At Dynamic, we prioritize flexibility and choice. While we offer a range of tools to enhance security for your applications and wallets, we recognize that not every feature may align with your risk profile and use case. For instance, you can require an MFA at sign-up, but this extra step might be unnecessary for users who haven’t yet built up many assets. That's why MFA is recommended rather than required for using Dynamic.
As a developer, you have the freedom to evaluate what best suits your risk profile, business requirements, and user preferences. We encourage you to implement the highest security practices that align with your application and UX requirements Dynamic powered Embedded Wallets are self-custodial by design. It is important that you determine how to use them and evaluate what structure works best for your business and users.
While we prioritize flexibility and choice, we maintain certain requirements and recommended best practices to ensure the security for all developers, regardless of their level of sophistication.
| Security Measure | Requirement Level | Description |
| -------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Allowed domains (CORS origin) | Recommended | Prevents malicious domain impersonation. Required in certain scenarios. |
| Content Security Policies (CSP) | Recommended | Mitigates Cross-Site Scripting (XSS) attacks. |
| Third Party App connection checks (Global Wallet Kit specific) | Required for Global Wallets | Helps prevent users from connecting to malicious third party applications |
| Multi-Factor Authentication (MFA) | Recommended | Enhances account security, excluding SMS as a sole method. |
| Recovery Shares & Cloud backups | Recommended | Ensures secure and accessible backup options for account recovery. |
| Passcode | Recommended | Adds an additional security factor on the user-share for Dynamic Embedded wallets with TSS-MPC. |
| Transaction security checks | Recommended | Provides added protection for users by checking if a transaction may interact with a known malicious address or is requesting permissions beyond what is expected. If using Dynamic Global wallets, this is required. |
| Transaction simulation | Recommended | Simulates the transaction to ensure users double check the asset amounts and destinations prior to completing an activity. |
| Cookie-based authentication | Recommended | This can mitigate certain types of attacks, such as session hijacking by making the JWT not directly accessible or modifiable by client-side scripts. |
| Roles & Permissions (Dynamic Dashboard) | Recommended | Limit who in your organization can perform read, write or administrative privileges in your account. |
## Shared Responsibilities
Security is a collaborative effort between Dynamic, developers and end-users. While Dynamic implements robust security measures to safeguard user assets and ensure a secure infrastructure, it also requires developers to actively contribute and continuously improve security practices.
Dynamic provides foundational security measures such as mitigating XSS attacks, preventing phishing attempts, and utilizing Secure Enclaves for sensitive operations. However, developers play a crucial role in enhancing security by implementing additional measures like multi-factor authentication, continuous transparent communication, and proactive monitoring. Developers should give Dynamic a heads up ahead heightened traffic periods so we can recommend or enhance protections
Together, we work towards creating a resilient ecosystem that prioritizes user protection and maintains trust in our services.
# Mitigating Attack Vectors
Source: https://docs.dynamic.xyz/security/threatvectors
This section highlights some of the primary threats developers and users may encounter along with recommended strategies to mitigate these risks. It's important to recognize that this is not exhaustive; rather, it aims to outline key areas and proactive steps to bolster security.
## Cross-site scripting (XSS) attacks
Dynamic mitigates XSS attacks by utilizing Content Security Policies (CSPs) and iFrames, preventing unauthorized scripts from accessing wallet shares or modifying user sessions.
## Phishing and Social Engineering attacks
Phishing and social engineering are the most common threats in software and financial applications. While no single solution can fully prevent these attacks, Dynamic employs multiple strategies:
1. Domain binding to restrict JWTs and wallet interactions to approved domains
2. We do not allow SMS as a secondary MFA method
### Recommendations to developers to mitigate phishing attacks
1. Wherever possible warn users when performing sensitive actions for example, Dynamic includes a message in the developer console advising users to never copy and paste code into their browser; and requires active user acknowledgment during any export activity
2. Leverage transaction simulation to prompt users before they transact
3. Leverage transaction security checks which scans for malicious address involvement
4. Add additional authentication layers like MFA, or require a Passcode for a user-share
## Supply chain attacks
Dynamic uses automated tools for continuous monitoring and scanning of third-party packages for vulnerabilities and enforces integrity checks on all external dependencies.
Additionally, for Dynamic powered Embedded Wallets, Trusted Execution Environments (TEE) are used to further ensure security and controls around sensitive user data. All secure enclave deployments are attested to guarantee integrity of the software running and ensure that only authorized code runs within our infrastructure. Multi-person reviews with scanned, signed, and verified artifacts are strictly enforced to prevent tampering in the software supply chain.
## Brute-force attacks
Dynamic enforces rate limiting on authentication attempts and supports additional measures like hCAPTCHA and domain blocking. We have active monitoring on all endpoints and projects to alert us if we see increases above the norm.
### Recommendations to protect against brute force attacks
1. Notify us ahead of major traffic events. Dynamic will be able to add rate limit rules that help block bot traffic
2. Place your entire site behind cloudflare turnstile
3. Add hCAPTCHA during heavy traffic periods such as a network launch, airdrop, TGE or quest program
4. Add email Domain Blocking if you determine a specific domain is carrying out an attack
5. Enforce MFA such as TOTP
## Man-in-the-Middle (MITM) attacks
Dynamic strictly enforces TLS/SSL encryption for all network traffic to prevent any unauthorized access to data in transit to or from Dynamics servers. CORS origin is a requirement for any web application using Dynamic.
For Dynamic powered Embedded wallets, we implement session key chaining, which requires a properly registered session key on sensitive authenticated requests. Dynamic powered Embedded wallets with TSS-MPC includes using a secure relay mechanism to apply an additional layer of encryption between parties involved in MPC ceremonies. This prevents unauthorized interception of key share material between devices and Dynamic servers.
### Recommendations to protect against man-in-the-middle attacks
1. Enable cookie-based authentication. When properly enabled, Dynamic will write an httpOnly cookie from the server response which helps prevent malicious hackers from stealing a legitimate user's JWT
2. Enforce MFA. This will help prevent a malicious actor from using a compromised email/social to impersonate a user, even if they are able to collect this information in a malicious way
# Overview
Source: https://docs.dynamic.xyz/smart-wallets/add-smart-wallets
Dynamic integrates with multiple account abstraction providers so you can choose your optimal setup to convert wallets into smart contract wallets, leveraging [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337) (the official account abstraction specification).
## What can you do with a smart contract wallet?
Smart wallets offer a myriad of benefits. Four specific ones are:
1. **Gas fee sponsorship** - you can choose to allow your users to conduct “gasless” transactions that will be sponsored by you.
2. **Transaction bundling** - you can collect a single signature which is used for a bundle of transactions vs having to ask a user for signature on every independent action.
3. **Sophisticated recovery and transfer options** - because the wallet is a smart contract, you can define sophisticated recovery methods for the wallet signer, as well as options to transfer ownership from one private key owner to another.
4. **Session keys** - you can create session keys with permissions to send specific transactions for your users, so that you can execute transactions without asking your users to sign, and even execute transactions while they are offline.
## How does smart wallet creation work?
Once a user logs in with email and an embedded wallet is created for them, a key pair is generated for that wallet. The key pair is then used to generate a smart contract wallet that uses the private key as the owner. In essence, you use the private key from the embedded wallet to control a more sophisticated smart wallet.
The resulting wallet can be interacted with using the same standard interface as native wallets, with the ability to add features such as gas sponsorship, session keys and batched transactions.
## Getting started with Smart Wallets
To get started with smart wallets, you will need to choose an account abstraction provider. Dynamic currently supports the following providers:
Note that ZeroDev is the only provider integrated natively into Dynamic.
* [ZeroDev](/smart-wallets/smart-wallet-providers/zerodev)
* [Alchemy](/smart-wallets/smart-wallet-providers/alchemy)
* [Pimlico](/smart-wallets/smart-wallet-providers/pimlico)
* [Biconomy](/smart-wallets/smart-wallet-providers/biconomy)
* [Safe](/smart-wallets/smart-wallet-providers/safe)
* [Circle](/smart-wallets/smart-wallet-providers/circle)
* [ZKsync SSO](/smart-wallets/smart-wallet-providers/zksyncsso)
* [Crossmint](/smart-wallets/smart-wallet-providers/crossmint)
# EIP-7702
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/7702
EIP-7702 is now live on Ethereum mainnet! 🎉
We’re excited to bring EIP-7702 to production and are focused on making the integration as seamless and developer-friendly as possible. Please share your feedback—we’re committed to working closely with you to meet your needs.
## What is EIP-7702?
EIP-7702 enables Externally Owned Accounts (EOAs) to seamlessly upgrade into smart accounts, unlocking the full power of AA (Account Abstraction). With Dynamic's integration, both EOAs and AA wallets can access advanced smart account capabilities.
***
## Key Features
* **Gasless Transactions & Policies**\
Define and manage sponsorship rules via provider dashboards.
* **Batch Transactions**\
Execute multiple operations in a single, atomic transaction.
* **Smart Account Capabilities**\
Use powerful AA features like automation and chain abstraction directly from EOAs.
* **Rhinestone EIP-7579 Support (Coming Soon)**\
Enhanced modular smart account standard.
***
## How It Works
EIP-7702 introduces a new transaction type that allows an EOA to delegate execution to an address with a deployed smart account. This means:
* No need to switch or manage multiple accounts and wallets.
* Users retain their existing EOA and gain smart account functionality.
* The transition is smooth and invisible to the end user.
***
## Implementing with ZeroDev
To add EIP-7702 support using Dynamic and ZeroDev, follow our [ZeroDev integration guide](/smart-wallets/smart-wallet-providers/zerodev#complete-eip-7702-example). We natively support EIP-7702 with ZeroDev but you can also use other providers listed in the [Smart Wallet Providers](smart-wallets/add-smart-wallets#getting-started-with-smart-wallets) section.
***
## Common questions
### When does the delegation (authorization) signing happen?
The delegation authorization is signed automatically behind the scenes on the first transaction. If a paymaster is used, the paymaster will pay for the transaction.
### How long does the delegation remain active?
The delegation stays active until the user delegates to a new address.
### How does this work for existing EOAs (e.g. MetaMask)?
At the moment, delegation is a feature exclusive to embedded wallets. That's because we need to sign the authorization in a very specific way that requires access to the private key. From what we've heard, branded wallets like MetaMask are unlikely to expose the `signAuthorization` method, making it unclear how (or if) this flow will work with them.
## How to delegate to a custom smart account?
To delegate to a custom smart account, you need to sign the delegation authorization manually.
```typescript
import { useDynamicContext} from '@dynamic-labs/sdk-react-core';
import { isTurnkeyWalletConnector } from '@dynamic-labs/wallet-connector-core';
const { primaryWallet } = useDynamicContext();
const handleAuthorize = async () => {
const connector = primaryWallet?.connector;
if (!primaryWallet || !isEthereumWallet(primaryWallet)) {
console.log('Primary wallet is not available or not an Ethereum wallet');
return null;
}
if (!connector || !isTurnkeyWalletConnector(connector)) {
console.log('Connector is not a Turnkey wallet connector');
return null;
}
try {
console.log('Starting authorization process...');
const smartAccountAddress = '0xd6CEDDe84be40893d153Be9d467CD6aD37875b28';
const sepoliaChainId = 11155111;
console.log('Signing authorization for', smartAccountAddress);
const authorization = await connector.signAuthorization({
address: smartAccountAddress,
chainId: sepoliaChainId,
nonce: 0,
});
console.log('Authorization signed:', authorization);
const connectorAddress = await connector.getAddress();
console.log('Connector address:', connectorAddress);
const walletClient = await primaryWallet.getWalletClient();
const hash = await walletClient.sendTransaction({
authorizationList: [authorization],
to: connectorAddress as `0x${string}`,
value: BigInt(0),
});
console.log('Transaction hash:', hash);
return hash;
} catch (err) {
console.error('Error during authorization:', err);
return null;
}
};
```
## Resources
* [EIP-7702 Specification](https://eips.ethereum.org/EIPS/eip-7702)
* [ZeroDev Documentation](https://docs.zerodev.app/)
* [Ithaca Odyssey Testnet](https://www.ithaca.xyz/updates/odyssey)
* [Dynamic Dashboard](https://app.dynamic.xyz/dashboard)
# Alchemy
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/alchemy
This guide shows you how to use Dynamic as a signer for Alchemy Smart Accounts.
## Install the sdk
By default, the latest version of the Dynamic SDK ships with Viem. If you need to use Ethers, please refer to [this guide](/react-sdk/using-ethers).
In this example, we are installing only the Ethereum connectors in order to
keep bundle size light. If you need any others, you can find the references
[here](react-sdk/providers/dynamiccontextprovider#walletconnectors).
```bash
npm i -s @dynamic-labs/sdk-react-core @dynamic-labs/ethereum
```
## Add Dynamic to your application
In order to use Dynamic, you should wrap your app with DynamicContextProvider at the highest possible level i.e.
```jsx
import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core'
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum'
import Home from './Home'
// Found in your Dynamic dashboard (https://app.dynamic.xyz/dashboard/developer/api)
const DYNAMIC_ENVIRONMENT_ID = 'XXXXX'
const App = () => {
return (
)
}
export default App
```
## Create a SmartAccountSigner
Next, inside any component which is wrapped by the above DynamicContextProvider, use the useDynamicContext hook to fetch your provider, and create a SmartAccountSigner:
```tsx
import { WalletClientSigner, type SmartAccountSigner } from '@alchemy/aa-core'
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
import { isEthereumWallet } from '@dynamic-labs/ethereum'
// eslint-disable-next-line react-hooks/rules-of-hooks
const { primaryWallet } = useDynamicContext()
if (!isEthereumWallet(primaryWallet)) {
throw new Error('This wallet is not a Ethereum wallet');
}
const dynamicProvider = await primaryWallet?.getWalletClient()
// a smart account signer you can use as an owner on ISmartContractAccount
export const dynamicSigner: SmartAccountSigner = new WalletClientSigner(
dynamicProvider,
'dynamic' // signer type
)
```
## Use it with Light Account
Let's see it in action with aa-alchemy and LightSmartContractAccount from aa-accounts:
```tsx example.ts
import { AlchemyProvider } from '@alchemy/aa-alchemy'
import {
LightSmartContractAccount,
getDefaultLightAccountFactoryAddress,
} from '@alchemy/aa-accounts'
import { sepolia } from 'viem/chains'
import { dynamicSigner } from './dynamic'
const chain = sepolia
const provider = new AlchemyProvider({
apiKey: 'ALCHEMY_API_KEY',
chain,
}).connect(
(rpcClient) =>
new LightSmartContractAccount({
chain,
owner: dynamicSigner,
factoryAddress: getDefaultLightAccountFactoryAddress(chain),
rpcClient,
})
)
```
```tsx dynamic.ts
import { WalletClientSigner, type SmartAccountSigner } from '@alchemy/aa-core'
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
import { isEthereumWallet } from '@dynamic-labs/ethereum'
// eslint-disable-next-line react-hooks/rules-of-hooks
const { primaryWallet } = useDynamicContext()
if (!isEthereumWallet(primaryWallet)) {
throw new Error('This wallet is not a Ethereum wallet');
}
const dynamicProvider = await primaryWallet?.getWalletClient()
// a smart account signer you can use as an owner on ISmartContractAccount
export const dynamicSigner: SmartAccountSigner = new WalletClientSigner(
dynamicProvider,
'dynamic' // signer type
)
```
# Biconomy
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/biconomy
This guide will walk you through how to use Biconomy's smart accounts with Dynamic. You can find more info on how Biconomy works here: [https://docs.biconomy.io/account](https://docs.biconomy.io/account). We will use Ethereum Sepolia, so make sure your paymaster etc. is set up for that, and also make sure your user is on this network once logged in.
This guide and example is for V4 of the Biconomy packages and V4 of Dynamic.
## Install Dynamic and Biconomy
In your app's repository, install `@dynamic-labs/sdk-react-core`, `@dynamic-labs/ethereum` and `@biconomy/{account, bundler}`:
```bash
yarn add @dynamic-labs/sdk-react-core @biconomy/account @biconomy/bundler
```
## Initialize & configure Dynamic
### Add the DynamicContextProvider
All you need to get started is the DynamicContextProvider - you will want to wrap your app with this component at the highest possible level, like so:
```jsx
import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core'
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum'
{/* Your app's components */}
```
To enable embedded wallets for your users, [toggle it
on](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic) along with
[email/social auth](https://app.dynamic.xyz/dashboard/log-in-user-profile) in
the dashboard.
## Configure your Biconomy bundler and paymaster
Go to the Biconomy Dashboard and configure a Paymaster and a Bundler for your app. Make sure these correspond to the desired network for your user's smart accounts.
Make sure to set the paymaster URL as the value for REACT\_APP\_BICONOMY\_PAYMASTER\_URL in your env file, and do the same with your bundler URL for REACT\_APP\_BICONOMY\_BUNDLER\_URL.
### Create our Biconomy constants
Let's introduce a new `biconomy.js` file to house our Biconomy methods. Here we'll initialize the paymaster, the bundler, the validation module, and the method to create a smart account using createSmartAccountClient.
The validation module allows the user to authorize actions from their Biconomy smart account by signing messages with their Dynamic wallet.
```js biconomy.js
import { Bundler } from "@biconomy/bundler";
import { Paymaster, createSmartAccountClient, DEFAULT_ENTRYPOINT_ADDRESS, ECDSAOwnershipValidationModule, DEFAULT_ECDSA_OWNERSHIP_MODULE } from "@biconomy/account";
import { sepolia } from "viem/chains";
const bundler = new Bundler({
bundlerUrl: process.env.REACT_APP_BICONOMY_BUNDLER_URL,
chainId: sepolia.id, // Replace this with your desired network
entryPointAddress: DEFAULT_ENTRYPOINT_ADDRESS, // This is a Biconomy constant
});
const paymaster = new Paymaster({
paymasterUrl: process.env.REACT_APP_BICONOMY_PAYMASTER_URL,
});
const createValidationModule = async (signer) => {
return await ECDSAOwnershipValidationModule.create({
signer: signer,
moduleAddress: DEFAULT_ECDSA_OWNERSHIP_MODULE, // This is a Biconomy constant
});
};
export const createSmartAccount = async (walletClient) => {
const validationModule = await createValidationModule(walletClient);
console.log('creating')
return await createSmartAccountClient({
signer: walletClient,
chainId: sepolia.id, // Replace this with your target network
bundler: bundler, // Use the `bundler` we initialized above
paymaster: paymaster, // Use the `paymaster` we initialized above
entryPointAddress: DEFAULT_ENTRYPOINT_ADDRESS, // This is a Biconomy constant
defaultValidationModule: validationModule, // Use the `validationModule` we initialized above
activeValidationModule: validationModule, // Use the `validationModule` we initialized above
});
};
```
### Create our custom hook
We'll create a custom hook to fetch the wallet client from Dynamic, and then initialize the Biconomy smart account using the methods we created above.
```jsx useBiconomyAccount.js
import { useState, useEffect, useCallback } from 'react';
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { createSmartAccount } from "./biconomy.js";
export function useBiconomyAccount() {
const { primaryWallet } = useDynamicContext();
const [smartAccount, setSmartAccount] = useState(null);
const createAndSetSmartAccount = useCallback(async () => {
if (!primaryWallet) {
setSmartAccount(null);
return;
}
if(!primaryWallet.connector.isEmbeddedWallet) {
alert('No embedded wallet selected');
return;
}
try {
const walletClient = await primaryWallet.getWalletClient();
if (walletClient && !smartAccount) {
const newSmartAccount = await createSmartAccount(walletClient);
setSmartAccount(newSmartAccount);
}
} catch (error) {
console.error('Error fetching wallet clients or creating smart account:', error);
}
}, [primaryWallet, smartAccount]);
useEffect(() => {
createAndSetSmartAccount();
}, [createAndSetSmartAccount]);
return { smartAccount };
}
```
## Create Main component
Since we're calling dynamic hooks, we need to do this inside the component tree, above where the DynamicContextProvider wrapper lives. For our purposes, let's create a Main.js component, and this is also where we can place or signup and login UI (DynamicWidget):
```jsx Main.js
import { useEffect } from "react";
import { useBiconomyAccount } from "./useBiconomyAccount.js";
const Main = () => {
const { smartAccount } = useBiconomyAccount();
useEffect(() => {
console.log('My Biconomy smart account', smartAccount)
}, [smartAccount])
return <>;
};
export default Main;
```
As you can see, we're looking the now initialized smart account in Main, and you can then do whatever you want with it!
## End to end flow
You can find a complete example of the integration here: [https://github.com/dynamic-labs/dynamic-biconomy-example](https://github.com/dynamic-labs/dynamic-biconomy-example)
# Circle
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/circle
This tutorial guides you through using Dynamic as a signer for Circle Smart Accounts. You can refer to [this doc to learn more about Circle’s Modular Wallets offering](https://developers.circle.com/w3s/modular-wallets-quickstart).
## Setup
1. Register [a Circle Developer account](https://console.circle.com/signup). In [the Configurator section of the Circle Developer Console under Modular Wallets](https://console.circle.com/wallets/modular/configurator), grab your Client URL, and create a new Client Key.
2. Register [a Dynamic account](https://app.dynamic.xyz/). Grab your environment ID from [the SDK & API keys page of the Dynamic Dashboard](https://app.dynamic.xyz/dashboard/developer/api).
3. In [the Chains and Networks page of the Dynamic Dashboard](https://app.dynamic.xyz/dashboard/chains-and-networks), enable the EVM network(s) you want to use with Circle. In this example we use Polygon Amoy, so please make sure that's enabled.
## Code Implementation
For this guide, we'll be using React and typescript, but this can easily be adapted to other frameworks.
If you don't already have an app created, check out our [Quickstart](/quickstart) guide or [Create dynamic app](/example-apps).
1. You'll need to install the Circle SDK dependency by running:
```bash Shell
npm install @circle-fin/modular-wallets-core
```
```bash Shell
yarn add @circle-fin/modular-wallets-core
```
```bash Shell
pnpm add @circle-fin/modular-wallets-core
```
```bash Shell
bun add @circle-fin/modular-wallets-core
```
2. Create a `.env` file in the project directory and add the following environment variables:
```
REACT_APP_CIRCLE_CLIENT_KEY=your_circle_client_key
REACT_APP_CIRCLE_CLIENT_URL=your_circle_client_url
```
Note: If you're using Next.js, replace `REACT_APP_` with `NEXT_PUBLIC_` and for Vite, use `VITE_`.
3. In `src/App.js`, replace the value for the `environmentId` with your own Dynamic environment ID.
4. Navigate to `src/Main.js`, and replace the current contents with the following:
```jsx
import React, { useEffect, useState } from "react"
import { createPublicClient, parseEther } from "viem";
import { createBundlerClient } from "viem/account-abstraction";
import { polygonAmoy } from "viem/chains";
import { isEthereumWallet } from "@dynamic-labs/ethereum";
import { useDynamicContext, DynamicWidget } from "@dynamic-labs/sdk-react-core";
import {
toCircleSmartAccount,
toModularTransport,
walletClientToLocalAccount,
} from "@circle-fin/modular-wallets-core";
const clientKey = process.env.REACT_APP_CIRCLE_CLIENT_KEY!;
const clientUrl = process.env.REACT_APP_CIRCLE_CLIENT_URL!;
// Create Circle transports
const modularTransport = toModularTransport(
`${clientUrl}/polygonAmoy`,
clientKey
);
// Create a public client
const client = createPublicClient({
chain: polygonAmoy,
transport: modularTransport,
});
// Create a bundler client
const bundlerClient = createBundlerClient({
chain: polygonAmoy,
transport: modularTransport,
});
export const Main = () => {
const { primaryWallet } = useDynamicContext();
const [account, setAccount] = useState(undefined);
const [hash, setHash] = useState(undefined);
const [userOpHash, setUserOpHash] = useState(undefined);
useEffect(() => {
setSigner();
async function setSigner() {
if (!primaryWallet) {
// Reset the account if the wallet is not connected
setAccount(undefined);
return;
}
if (!isEthereumWallet(primaryWallet)) {
throw new Error("This wallet is not an Ethereum wallet");
}
const dynamicProvider = await primaryWallet.getWalletClient();
toCircleSmartAccount({
client,
owner: walletClientToLocalAccount(dynamicProvider), // Transform the wallet client to a local account
}).then(setAccount);
}
}, [primaryWallet]);
const sendUserOperation = async (event: React.FormEvent) => {
try {
event.preventDefault();
if (!account) return;
const formData = new FormData(event.currentTarget);
const to = formData.get("to") as `0x${string}`;
const value = formData.get("value") as string;
const hash = await bundlerClient.sendUserOperation({
account,
calls: [
{
to,
value: parseEther(value),
},
],
});
setUserOpHash(hash);
const { receipt } = await bundlerClient.waitForUserOperationReceipt({
hash,
});
setHash(receipt.transactionHash);
} catch (error) {
if (error instanceof Error) {
alert(error.message);
console.error(error);
}
}
};
if (!primaryWallet) return
```bash Shell
npm start
```
```bash Shell
yarn start
```
```bash Shell
pnpm start
```
```bash Shell
bun run start
```
Check out the UI; once you sign up/login, you should see the following:
6. Add a valid address to send to, and an amount that is within your wallet's balance plus a reasonable gas fee. Click on the "Send" button, and you should see the transaction hash in the UI!
## Troubleshooting
**Problem:** `Execution reverted for an unknown reason`
**Solution:** This is most likely due to the account not having enough ETH to pay for the transfer, make sure your smart wallet is funded!
# Crossmint
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/crossmint
## Step-by-Step Guide
This guide shows you how to use Dynamic for authentication and as a signer for Crossmint Smart Wallets.
The first step is to obtain a client-side API key from Crossmint.
1. Navigate to the "Integrate" section on the left navigation bar of [the Crossmint console](https://www.crossmint.com/console), and ensure you're on [the "API Keys" tab](https://www.crossmint.com/console/projects/apiKeys).
2. Within the **Client-side keys** section, click the "Create new key" button in the top right.
3. On the authorized origins section, enter `http://localhost:3000` and click "Add origin".
4. Next, check the scopes labeled `wallets.create`, `wallets.read`, `users.create`.
5. Check the "JWT Auth" box.
6. Finally, create your key and save it for subsequent steps.
After the key is generated, you need to set it to require Dynamic auth tokens for authorization.
1. Go to the Dynamic dashboard at [https://app.dynamic.xyz/](https://app.dynamic.xyz/)
2. Select an existing project or create a new one
You need to make sure you're using live keys for mainnets and sandbox keys for staging/testnets.
3. Expand the "Developers" section in the left-hand navigation and select "SDK and API Keys" to find your Dynamic Environment ID.
4. Copy the Dynamic Environment ID and return to the Crossmint developer console
5. Within the JWT authentication section, select "3P Auth providers" option, and then select Dynamic
6. Add your Environment ID and save changes
To integrate Crossmint Smart Wallets with Dynamic as the auth provider, you need to configure the chain you want to use:
1. With the same project selected, select the "Chains and Networks" option in the left-hand navigation
2. Click the EVM option to reveal a drawer where you can toggle chain support on and off
3. Enable the desired chain for smart wallet support (in this example, we'll use `polygon-amoy`)
Install the Crossmint React UI SDK and dynamic packages:
```bash npm
npm install @crossmint/client-sdk-react-ui @dynamic-labs/sdk-react-core @dynamic-labs/ethereum
```
```bash yarn
yarn add @crossmint/client-sdk-react-ui @dynamic-labs/sdk-react-core @dynamic-labs/ethereum
```
```bash pnpm
pnpm add @crossmint/client-sdk-react-ui @dynamic-labs/sdk-react-core @dynamic-labs/ethereum
```
Then, set up shadcn UI components:
```bash
npx shadcn-ui@latest init -d
```
Install the button and card components:
```bash
npx shadcn-ui@latest add button card
```
Add your Crossmint client-side API key and Dynamic Environment ID to your environment file:
```shell
NEXT_PUBLIC_DYNAMIC_ENV_ID=_YOUR_DYNAMIC_ENV_ID_
NEXT_PUBLIC_CROSSMINT_DYNAMIC_API_KEY=_YOUR_CROSSMINT_API_KEY_
```
First, create a CrossmintDynamicProvider component that will wrap your application:
```tsx components/providers/CrossmintDynamicProvider.tsx
'use client';
import {
CrossmintProvider,
CrossmintWalletProvider,
} from '@crossmint/client-sdk-react-ui';
import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';
const dynamicEnvId = process.env.NEXT_PUBLIC_DYNAMIC_ENV_ID ?? '';
const crossmintApiKey = process.env.NEXT_PUBLIC_CROSSMINT_DYNAMIC_API_KEY ?? '';
if (!dynamicEnvId || !crossmintApiKey) {
throw new Error(
'NEXT_PUBLIC_DYNAMIC_ENV_ID or NEXT_PUBLIC_CROSSMINT_DYNAMIC_API_KEY is not set'
);
}
export default function CrossmintDynamicProvider({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
Now create a custom hook that connects Dynamic with Crossmint:
```tsx hooks/useDynamicConnector.tsx
'use client';
import {
useCrossmint,
useWallet as useCrossmintSmartWallet,
} from '@crossmint/client-sdk-react-ui';
import { isEthereumWallet } from '@dynamic-labs/ethereum';
import {
getAuthToken,
useDynamicContext,
useIsLoggedIn,
} from '@dynamic-labs/sdk-react-core';
import { useEffect, useState } from 'react';
export function useDynamicConnector() {
const { setJwt } = useCrossmint();
const { primaryWallet: dynamicPrimaryWallet, sdkHasLoaded } =
useDynamicContext();
const isDynamicUserLoggedIn = useIsLoggedIn();
const {
getOrCreateWallet: getOrCreateCrossmintSmartWallet,
status: crossmintSmartWalletStatus,
error: crossmintSmartWalletError,
wallet: crossmintWallet,
} = useCrossmintSmartWallet();
// State to track loading status
const [isLoading, setIsLoading] = useState(true);
// Step 1: Sync Dynamic JWT with Crossmint
useEffect(() => {
const syncDynamicJwt = async () => {
try {
const dynamicJwt = getAuthToken();
setJwt(dynamicJwt ?? undefined);
} catch (error) {
setJwt(undefined);
console.error('Failed to get Dynamic JWT:', error);
}
};
if (isDynamicUserLoggedIn) {
syncDynamicJwt();
}
}, [isDynamicUserLoggedIn, setJwt]);
// Step 2: Get Dynamic wallet and create Crossmint wallet
useEffect(() => {
const createWalletWithDynamicSigner = async () => {
setIsLoading(true);
if (!dynamicPrimaryWallet || !isDynamicUserLoggedIn || !sdkHasLoaded) {
setIsLoading(false);
return;
}
try {
if (!isEthereumWallet(dynamicPrimaryWallet)) {
setIsLoading(false);
return;
}
// Get the wallet client from Dynamic
const dynamicWalletClient = await dynamicPrimaryWallet.getWalletClient();
// Create a Crossmint Smart Wallet using the Dynamic wallet as signer
await getOrCreateCrossmintSmartWallet({
type: 'evm-smart-wallet',
signer: dynamicWalletClient,
});
} catch (error) {
console.error('Failed to create Crossmint wallet:', error);
} finally {
setIsLoading(false);
}
};
createWalletWithDynamicSigner();
}, [dynamicPrimaryWallet, isDynamicUserLoggedIn, sdkHasLoaded, getOrCreateCrossmintSmartWallet]);
return {
dynamicWallet: dynamicPrimaryWallet,
crossmintWallet,
crossmintSmartWalletStatus,
crossmintSmartWalletError,
isLoading: isLoading || crossmintSmartWalletStatus === 'in-progress' || !sdkHasLoaded,
};
}
```
Update your app's layout to use the CrossmintDynamicProvider:
```tsx app/layout.tsx
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';
import CrossmintDynamicProvider from '@/components/providers/CrossmintDynamicProvider';
const inter = Inter({ subsets: ['latin'] });
export const metadata: Metadata = {
title: 'Crossmint + Dynamic Integration',
description: 'Example of using Crossmint with Dynamic Auth',
};
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
{children}
);
}
```
Create a component that uses the Dynamic connector and displays wallet information:
```tsx components/WalletCard.tsx
'use client';
import { DynamicWidget } from '@dynamic-labs/sdk-react-core';
import { Card, CardContent } from '@/components/ui/card';
import { useDynamicConnector } from '@/hooks/useDynamicConnector';
export function WalletCard() {
const {
dynamicWallet,
crossmintWallet,
crossmintSmartWalletStatus,
crossmintSmartWalletError,
isLoading,
} = useDynamicConnector();
return (
);
}
```
Create your main page that uses the WalletCard component:
```tsx app/page.tsx
import { WalletCard } from '@/components/WalletCard';
export default function Home() {
return (
1. Start your development server:
```bash npm
npm run dev
```
```bash yarn
yarn dev
```
```bash pnpm
pnpm dev
```
2. Visit [http://localhost:3000](http://localhost:3000) in your browser
3. Click the Dynamic widget to start the authentication flow
4. Follow the prompts to authenticate using Dynamic
5. Once logged in, you should see both your Dynamic wallet address and your Crossmint Smart Wallet address
## How It Works
```mermaid
sequenceDiagram
participant User
participant App
participant Dynamic
participant Crossmint
User->>App: Log in
App->>Dynamic: Authenticate user
Dynamic->>App: Create embedded wallet & return JWT
App->>Crossmint: Connect with Dynamic JWT
App->>Crossmint: Create Crossmint smart wallet using Dynamic wallet as signer
Crossmint->>App: Return Crossmint smart wallet
Note over App: User now has:
Note over App: 1. Dynamic embedded wallet (signer)
Note over App: 2. Crossmint smart wallet
```
The integration between Dynamic and Crossmint involves these key components:
1. **Authentication Flow**:
* User connects wallet using Dynamic's authentication
* Dynamic provides the wallet and authentication token (JWT)
* The Crossmint SDK uses the JWT from Dynamic to authenticate with Crossmint
2. **Wallet Creation**:
* The `useDynamicConnector` hook retrieves the primary wallet from Dynamic
* It gets the wallet client from the Dynamic wallet to use as a signer
* It creates a Crossmint Smart Wallet using the Dynamic wallet as the signer
3. **Key Benefits**:
* Users leverage their existing Dynamic authentication
* No new key management required
* The Dynamic wallet serves as a signer for the Crossmint Smart Wallet
* Cross-chain support through Crossmint's infrastructure
* **Dynamic Wallet**: The primary signer that controls the Crossmint Smart Wallet
* **Crossmint Smart Wallet**: A fully-featured EVM wallet with gas sponsorship capabilities
* The user authenticates with Dynamic, but gains access to Crossmint's advanced wallet infrastructure
The integration relies on JWT tokens for secure authentication:
1. Dynamic issues a JWT token upon user authentication
2. The Crossmint SDK uses this JWT to authenticate the user with Crossmint
3. The JWT handling is abstracted away in the `useCrossmint` hook
4. Tokens are automatically refreshed as needed
**Module not found: Can't resolve `rpc-websockets/dist/lib/client`**
Add this to your `package.json`:
```json
"resolutions": {
"rpc-websockets": "7.11.0"
}
```
**Chain mismatch errors between Dynamic and Wagmi**
Ensure your Dynamic environment is configured for the same chain you're using in your app. Check the Dynamic.xyz dashboard and make sure the chain is enabled.
# Pimlico
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/pimlico
## How to use a Dynamic signer with permissionless.js
Permissionless.js allows you to plug in custom signers to control the accounts that you create. It is possible to use Dynamic as a signer with permissionless.js, allowing you to use Dynamic to create and control smart accounts and sign transactions.
### Install the dependencies
```bash
npm i @dynamic-labs/sdk-react-core @dynamic-labs/wagmi-connector @dynamic-labs/ethereum permissionless viem wagmi
```
### Create the Dynamic provider
Following Dynamic's quickstart guide, set up the Dynamic provider in your app. Also integrate the DynamicWagmiConnector, which will allow you to use Dynamic as a signer with permissionless.js.
```jsx
import {
DynamicContextProvider,
DynamicWidget,
} from "@dynamic-labs/sdk-react-core";
import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
export const App = () => {
return (
);
};
```
### Create the SmartAccountClient
Create the smart account client using the Dynamic signer. Note: DynamicWagmiConnector internally sets up the WagmiConfig, so there is no need to do it separately. This is where you would configure what smart account implementation (e.g. Safe, Kernel, Biconomy, SimpleAccount) and what paymaster logic you want to use.
```jsx
import {
createSmartAccountClient,
walletClientToCustomSigner,
} from "permissionless";
import { signerToSimpleSmartAccount } from "permissionless/accounts";
import { useWalletClient } from "wagmi";
const { data: walletClient } = useWalletClient();
const customSigner = walletClientToCustomSigner(walletClient);
const simpleSmartAccountClient = await signerToSimpleSmartAccount(
publicClient,
{
entryPoint: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
signer: customSigner,
factoryAddress: "0x9406Cc6185a346906296840746125a0E44976454",
}
);
const smartAccountClient = createSmartAccountClient({
account: simpleSmartAccountClient,
chain: sepolia, // or whatever chain you are using
transport: http(""),
sponsorUserOperation: pimlicoPaymaster.sponsorUserOperation, // if using a paymaster
});
```
### Send a transaction
You can now send transactions as normal. The sponsorUserOperation function will be called before each transaction is signed and sent, applying the custom paymaster logic you have set.
```js
const txHash = await smartAccountClient.sendTransaction({
to: zeroAddress,
data: "0x",
value: BigInt(0),
});
```
# Safe
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/safe
Let's deploy a Safe account on top of any wallet through Dynamic! First we'll make sure signup/login are enabled, then we'll fetch the walletClient once logged in before deploying the Safe account.
## Enable signup/login
Once you've signed up for Dynamic, integrating it is as easy as either `npx create-dynamic-app`, or simply following the [Quickstart](/quickstart) guide.
When that's done you should have an app which is wrapped with the [DynamicContextProvider](react-sdk/providers/dynamiccontextprovider).
```jsx
import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
import Main from './Main';
const App = () => {
return (
);
}
```
Before we work on Main, let's declare a function that can help us deploy the Safe account, taking a walletClient and wallet address as arguments:
We're using a few dependancies below, you might want to first install them:
```bash
npm i viem permissionless @dynamic-labs/wallet-connector-core
```
```jsx
// src/utils/safe.ts
import { isEthereumWallet } from "@dynamic-labs/ethereum";
import { WalletClient, PublicClient, http } from "viem";
import { ENTRYPOINT_ADDRESS_V07, createSmartAccountClient, walletClientToSmartAccountSigner } from "permissionless";
import { createPimlicoBundlerClient, createPimlicoPaymasterClient } from "permissionless/clients/pimlico";
import { signerToSafeSmartAccount } from "permissionless/accounts";
import { Wallet } from '@dynamic-labs/wallet-connector-core';
const transportUrl = (chain: Chain) =>
`https://api.pimlico.io/v2/${chain.id}/rpc?apikey=${process.env.NEXT_PUBLIC_PIMLICO_API_KEY}`;
export const pimlicoBundlerClient = (chain: Chain) =>
createPimlicoBundlerClient({
transport: http(transportUrl(chain)),
entryPoint: ENTRYPOINT_ADDRESS_V07,
});
export const paymasterClient = (chain: Chain) =>
createPimlicoPaymasterClient({
transport: http(transportUrl(chain)),
entryPoint: ENTRYPOINT_ADDRESS_V07,
});
export const getPimlicoSmartAccountClient = async (
wallet: Wallet
) => {
if (!isEthereumWallet(wallet)) return;
const address = wallet.address as `0x${string}`;
const publicClient = await wallet.getPublicClient() as PublicClient;
const walletClient = wallet.getWalletClient() as WalletClient;
const chain = walletClient.chain;
const signer = walletClientToSmartAccountSigner(walletClient);
const safeSmartAccountClient = await signerToSafeSmartAccount(publicClient(chain), {
entryPoint: ENTRYPOINT_ADDRESS_V07,
signer: signer,
safeVersion: "1.4.1",
});
return createSmartAccountClient({
account: safeSmartAccountClient,
entryPoint: ENTRYPOINT_ADDRESS_V07,
chain,
bundlerTransport: http(transportUrl(chain)),
middleware: {
gasPrice: async () => (await pimlicoBundlerClient(chain).getUserOperationGasPrice()).fast, // use pimlico bundler to get gas prices
sponsorUserOperation: paymasterClient(chain).sponsorUserOperation, // optional
},
});
};
```
Let's walk through what we just wrote step by step:
This is the RPC URL for the Pimlico API which we will use in multiple places, so better to extract it. It depends on your Pimlico API key so make sure you have that set under `NEXT_PUBLIC_PIMLICO_API_KEY` in your `.env` file.
The Bundler is the node that can help us batch our user operations and submit them as a single transaction to the blockchain. The client we are creating here is an interface to that Bundler, and it comes with a load of helpful methods related to those userops, such as Gas estimations. Specifically, we are going to need `getUserOperationGasPrice` later.
You can see that as well as the transport (i.e. how it should communicate which in this case is via HTTP using the Transport URL we defined earlier), it needs something called the entrypoint address. This is imported as a static variable via `ENTRYPOINT_ADDRESS_V07` from the `permissionless` package. This is an address of a smart contract (deployed on every chain) that acts as a gateway for user operations. [This article](https://blog.smart-contracts-developer.com/entrypoint-v0-7-0-the-new-era-of-account-abstraction-854f9f82912e) helps describe what the V07 version is compared to previous.
You can learn more about the Bundler Client [here](https://docs.pimlico.io/permissionless/reference/clients/pimlicoBundlerClient).
This Paymaster is where we handle the sponsoring of user operations. It's optional, but we are going to use it in our middleware later.
This client also needs the transport method and entrypoint address as we described in the previous step.
You can learn more about the Paymaster Client [here](https://docs.pimlico.io/permissionless/reference/clients/pimlicoPaymasterClient).
We are going to need to make some read actions and write actions onchain, and Viem provides a Public Client (for read actions) and Wallet Client (for write actions). We are going to need both of these, so we are going to extract them from the wallet object we get passed in as an argument.
Dynamic makes it super easy to return these clients from the wallet object. We can use the `getPublicClient` and `getWalletClient` methods on the wallet connector respectively.
You can learn more about interacting with Wallets (covers all kinds of actions) [here](/wallets/using-wallets/interacting-with-wallets).
Something needs to sign the user operations we are going to send to the Bundler. This function takes the Wallet Client and returns a signer that can be used to sign those operations.
In normal transactions, the walletClient is enough to sign with, and you can use methods like `signTransaction` or `signMessage` directly on the walletClient. But for Smart Accounts, we need a specific type of signer that can handle the extra complexity of Smart Accounts.
You can learn more about this specific Signer type [here](https://docs.pimlico.io/permissionless/how-to/signers#signers-for-permissionlessjs).
While we now have something that can sign for user operations, we don't have a Smart Account yet to actually use it with. That's the purpose of `signerToSafeSmartAccount`. It takes the Public Client, the signer we just created, and some other options, and returns a Safe Account.
You can learn more about this method [here](https://docs.pimlico.io/permissionless/reference/accounts/signerToSafeSmartAccount).
With our signer and Safe account now in hand, the last step is to create an interface where we can start to take actions on the Safe Account. This is what `createSmartAccountClient` does.
You can see we are defining some extra middleware here, such as the gas price and the sponsorUserOperation. These are optional but can be helpful in certain situations.
In our case we're going to use the paymaster we created earlier to sponsor the user operations, and the bundler to get the gas prices.
You can learn more about the signerToSafeSmartAccount method [here](https://docs.pimlico.io/permissionless/reference/accounts/signerToSafeSmartAccount).
In `Main.js`, we can now fetch the walletClient once logged in and then create that Safe account using the function we just created. To learn how to handle loading states, visit the [Loading States guide](/react-sdk/loading-login-states).
```jsx
import { useState } from 'react';
import { useDynamicContext, primaryWallet } from '@dynamic-labs/sdk-react-core';
import { getOrMapViemChain } from "@dynamic-labs/ethereum-core";
import { getPimlicoSmartAccountClient } from '../utils/safe';
const Main = () => {
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const [safeAddress, setSafeAddress] = useState(null);
const [safeDeployed, setSafeDeployed] = useState(false);
const { user } = useDynamicContext();
const handleDeploySafe = async () => {
setLoading(true);
setError(null);
try {
if(!primaryWallet) {
setError("No wallet found");
return;
};
if (!process.env.NEXT_PUBLIC_PIMLICO_API_KEY) {
console.error("Please set NEXT_PUBLIC_PIMLICO_API_KEY in .env file and restart");
return;
}
const { account } = await getPimlicoSmartAccountClient(primaryWallet);
setSafeAddress(account.address);
setSafeDeployed(true);
} catch (err) {
setError("Failed to deploy Safe account.");
console.error(err);
} finally {
setLoading(false);
}
};
if (!user) {
return
);
} else if (user && safeDeployed) {
return (
);
}
}
export default Main;
```
That's it! You now have the ability to create a Safe account on top of any wallet used with Dynamic, including embedded wallets! To learn how to interact with the Safe account, check out our Hackathon starter kit which handles ERC20 token transfers and cross chain ERC20 token transfers.
* [Hacker Starter Kit Overview Video](https://www.youtube.com/watch?v=dkONR9dJD2g)
* [Hacker Starter Kit Codebase](https://github.com/dynamic-labs/hackathon-starter-kit/tree/main)
# ZeroDev
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/zerodev
The first iteration of account abstraction from Dynamic uses [ZeroDev](https://zerodev.app/) and embedded wallets.
This guide will walk you through setting up ZeroDev and Dynamic so that you can sponsor transactions. While we're using Base Sepolia for this guide, you can use any network that has implemented the Ethereum Petra upgrade.
### Initial setup
Sign up for a free account at [https://dashboard.zerodev.app/](https://dashboard.zerodev.app/) and create a project, configure your project name and network (we'll use Base Sepolia for this example, but you can choose any supported network) and copy your new ZeroDev project ID.
Note that the network you select in your ZeroDev project will be the network
that the smart contract wallet is deployed on and cannot be changed without
creating a new project. Choose a network that aligns with your application's needs.
In [the EVM section of your Dynamic Dashboard](https://app.dynamic.xyz/dashboard/chains-and-networks#evm), toggle on the network you selected in the previous step (we're using Base Sepolia in this guide) and click Save.
Now, go to [the Account Abstraction section](https://app.dynamic.xyz/dashboard/configurations#accountabstraction), enable ZeroDev and paste in your ZeroDev project id.
You must be using at least SDK version 3.3.0 or 4.0.0-alpha.8 to have access to this feature
Click on "Add another chain". You can input 1 ZeroDev project ID per chain you would like enabled.
If you would like to remove a multichain ZeroDev provider, hover your mouse over the network icon and you should be able to click the "Trash icon" to remove.
Click "Yes" to save and add another provider if desired.
On the same configuration page as the step above, you'll see there are two different types of configuration for issuing Smart Contract Wallets (SCWs) in Dynamic - the wallet level and the user level.
* Wallet level
Choose whether to issue SCWs to all wallets, or only to embedded wallets. Note that for the former, you will need to handle the UI and frontend yourself.
* User level
Choose whether to issue SCWs to all your users (existing included next time they log in), or just new users.
On the same configuration page as the 2 steps above, you'll see there is a setting for how the Dynamic SDK treats the signer and the smart wallet - only the smart wallet or both the smart wallet and signer.
* Show Smart Wallet Only
Only allows you to interact with the smart wallet directly.
* Show Smart Wallet & Signer
Treats the smart wallet and signer as separate wallets which you can switch between.
Back in your Dynamic Dashboard, go to [the Embedded Wallets section](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic) and enable Dynamic-powered embedded wallets.
Lastly, in [the Log in & User Profile section](https://app.dynamic.xyz/dashboard/log-in-user-profile), enable Email sign up (optionally, enable social sign up and configure oauth)
Note that we currently only create smart wallets for embedded wallets. You
will see native web3 wallets in your Dynamic widget, and can still use one to
sign in, but only new embedded wallets will have a smart wallet.
For this guide, we'll be using React and TypeScript, but this can easily be adapted to other frameworks.
If you don't already have an app created, check out our [Quickstart](/quickstart) guide or [Create dynamic app](/example-apps).
In your existing project, make sure to install the account abstraction package:
```bash Shell
npm install @dynamic-labs/ethereum-aa
```
```bash Shell
yarn add @dynamic-labs/ethereum-aa
```
```bash Shell
pnpm add @dynamic-labs/ethereum-aa
```
```bash Shell
bun add @dynamic-labs/ethereum-aa
```
Then add the `ZeroDevSmartWalletConnectors` to your existing `walletConnectors` array in the `DynamicContextProvider`:
To use ZeroDev v5.2, use Dynamic SDK version `^2.0.5`. For newer versions, use the latest compatible Dynamic SDK.
```tsx
import { DynamicContextProvider, DynamicWidget } from "@dynamic-labs/sdk-react-core";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import { ZeroDevSmartWalletConnectors } from "@dynamic-labs/ethereum-aa";
const App = () => (
)
export default App;
```
Make sure to grab your Dynamic environment id from the Dynamic Dashboard
under Developer > SDK & API Keys, and replace it in the `environmentID`
setting.
Now we will set up a basic gas sponsorship policy in the ZeroDev
dashboard
In the Gas Policies tab, click on the button labeled "New" in the Project Policies section
Select "Amount" as the Type, "0.1" as the value and "Day" as the interval. This is saying that we will sponsor up to 0.1 ETH total per day
Click Create Project Policy, and that's it! Now start your app, log in and try sending some ETH out. The Dynamic SDK will check if a transaction meets your gas policies and will automatically hide the gas in the transaction confirmation step if the gas is sponsored, if not the gas will be displayed.
Since you will be creating a brand new wallet when you log in, you will need to fund it with the native token of your chosen network. If you're using Base Sepolia as in this guide, you can access a free ETH faucet here: [https://www.alchemy.com/faucets/base-sepolia](https://www.alchemy.com/faucets/base-sepolia)
To interact with the wallet, you will need to interact with the kernel client. This allows you to send user operations and transactions through your smart wallet.
```typescript
const connector = primaryWallet?.connector;
const kernelClient = connector.getAccountAbstractionProvider({
withSponsorship: true,
});
const userOpHash = await kernelClient.sendUserOperation({
callData: await kernelClient.account.encodeCalls([
{
data: "0x",
to: zeroAddress,
value: BigInt(0),
},
{
data: "0x",
to: zeroAddress,
value: BigInt(0),
},
]),
});
```
Note that there is a delay between loading the page and the ZeroDev kernel client
being available. To ensure that the kernel client is available,
please await one of the following methods: `getAddress()`, `getConnectedAccounts()` or `getNetwork()`
before calling `getAccountAbstractionProvider()`.
### Complete EIP-7702 Example
The only bundler that supports EIP-7702 is Pimlico. So you will need to use the `ZeroDevSmartWalletConnectorsWithConfig` connector and pass in the `bundlerProvider` prop with the value `PIMLICO`.
```typescript
ZeroDevSmartWalletConnectorsWithConfig({ bundlerProvider: 'PIMLICO' })
```
If you're planning to use EIP-7702 (which allows EOAs to upgrade to smart accounts), the same kernel interaction principles apply. To learn more about EIP-7702, see our [EIP-7702 guide](/smart-wallets/smart-wallet-providers/7702).
```typescript
import { EthereumWalletConnectors, } from '@dynamic-labs/ethereum';
import { DynamicContextProvider, DynamicWidget, useDynamicContext} from '@dynamic-labs/sdk-react-core';
import { ZeroDevSmartWalletConnectors, isZeroDevConnector } from '@dynamic-labs/ethereum-aa';
import { zeroAddress } from 'viem';
import { useState } from 'react';
// Note: You'll need to import or create Button and Typography components
// import { Button, Typography } from 'your-ui-library';
function App() {
return (
)
}
function Sign7702Transaction() {
const { primaryWallet } = useDynamicContext();
const [error, setError] = useState("");
const [txHash, setTxHash] = useState("");
const [isSendingTransaction, setIsSendingTransaction] = useState(false);
if (!primaryWallet) {
return null;
}
const handleSendTransaction = async () => {
const connector = primaryWallet?.connector;
if (!connector) {
setError("No connector found");
return;
}
if (!isZeroDevConnector(connector)) {
setError("Connector is not a ZeroDev connector");
return;
}
const params = {
withSponsorship: true,
};
const kernelClient = connector.getAccountAbstractionProvider(params);
if (!kernelClient) {
setError("No kernel client found");
return;
}
try {
setIsSendingTransaction(true);
const userOpHash = await kernelClient.sendUserOperation({
callData: await kernelClient.account.encodeCalls([
{
data: "0x",
to: zeroAddress,
value: BigInt(0),
},
{
data: "0x",
to: zeroAddress,
value: BigInt(0),
},
]),
});
const { receipt } = await kernelClient.waitForUserOperationReceipt({
hash: userOpHash,
});
setTxHash(receipt.transactionHash);
setError("");
} catch (err: unknown) {
setError(
err instanceof Error ? err.message : "Error sending transaction"
);
} finally {
setIsSendingTransaction(false);
}
};
return (
<>
Run your app, and if you copied our snippet from earlier, you should see this
basic page
Click Connect your wallet, enter your email and hit Continue. After pasting in your OTP you'll be fully logged in!
Next, we're going to send a transaction. To do that, we will need some of the network's native token. Grab your wallet address by clicking on the Dynamic Widget, then click on the three dots next to your address and hit "Copy wallet address". If you're using Base Sepolia as in this guide, you can paste your address into the [Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia) which will deposit some free ETH into your account. After doing so, if you refresh your app, you should see your balance update
Optionally, set up fiat onramp by following our guide here:
[https://docs.dynamic.xyz/fiat-onboarding/banxa](https://docs.dynamic.xyz/fiat-onboarding/banxa)
Now, send yourself some tokens by clicking on the Send button in the Dynamic Widget. Enter 0.01 as the amount, and an address of your choosing as the recipient, then hit Send now. You will see a screen like the following. Notice that there is no gas estimate field, because this transaction will be sponsored!
Hit confirm, sign for the transaction with your passkey. Congratulations, you just sent a gas-sponsored transaction! If you take your smart wallet address and paste it into the block explorer for your network (for Base Sepolia, that's the [Base Sepolia Scan](https://sepolia.basescan.org/)), you will see your smart wallet and the transaction you just sent.
## Advanced Configuration
Now that you've completed the initial setup and sent your first transaction, you can utilize the full functionality of ZeroDev inside Dynamic - everything from session keys to gas policies. Learn more in the [ZeroDev Docs](https://docs.zerodev.app/).
#### Specifying a bundler/paymaster RPC
Use `ZeroDevSmartWalletConnectorsWithConfig` and pass in values for `bundlerRpc` and `paymasterRpc`:
```tsx
import { ZeroDevSmartWalletConnectorsWithConfig } from "@dynamic-labs/ethereum-aa";
{/* ... your app */}
;
```
For more info, see: [Pimlico Paymaster documentation](https://docs.zerodev.app/sdk/infra/pimlico#using-pimlico-paymaster)
#### Specifying a bundler
To specify a bundler, use `ZeroDevSmartWalletConnectorsWithConfig` and pass in a value for `bundlerProvider`:
```tsx
import { ZeroDevSmartWalletConnectorsWithConfig } from "@dynamic-labs/ethereum-aa";
{/* ... your app */}
;
```
For more info, see: [https://docs.zerodev.app/meta-infra/rpcs#bundler--paymaster-rpcs](https://docs.zerodev.app/meta-infra/rpcs#bundler--paymaster-rpcs)
#### Retrieving the Kernel Client using `getAccountAbstractionProvider()`
```tsx
import { isZeroDevConnector } from '@dynamic-labs/ethereum-aa';
const App = () => {
const { primaryWallet } = useDynamicContext();
useEffect(() => {
const { connector } = primaryWallet;
const getKernelClient = async () => {
if (!isZeroDevConnector(connector)) {
return;
}
// ensure that the kernel client has been loaded successfully
await connector.getNetwork();
const params = {
// if you have gas sponsorship enabled, set `withSponsorship` to `true`, else omit
withSponsorship: true
};
const kernelClient = connector.getAccountAbstractionProvider(params);
}
...
}
```
#### Using with Viem & Ethers
You can use viem or ethers with account abstraction to sign messages or send sponsored transaction with no extra configuration, it also works with our [wagmi integration](/react-sdk/providers/dynamicwagmiconnector).
## Going Further
Once you've tested things out and want to deploy to a live network, you will need to do the following:
1. Add your credit card to ZeroDev under Account Settings > Billing
2. Create a new ZeroDev project and select a live network
3. Copy your new ZeroDev project id and paste it into your Dynamic Dashboard
a. We recommend using your Dynamic Sandbox environment for testing your testnet setup, and using your Dynamic Live environment for production.
### Restricting Access to your ZeroDev Project
In order to restrict access to your ZeroDev project id to allow only dynamic to use it you can add dynamic's static IP address's to your projects IP allowlist.
Dynamic's IP addresses:
* `52.204.85.87`
* `54.145.74.8`
* `107.20.170.238`
* `52.206.26.56`
* `3.232.2.67`
* `44.213.187.169`
## Examples
### Get smart wallet address vs signer address
The wallet connector will return your smart wallet address, that address will be used in the Dynamic UI and is the main address you will interact with. But you can fetch the signer address by using the wallet connector's eoaConnector property and then fetching the address there.
```tsx
import { useEffect, useState } from "react";
import {
useDynamicContext,
DynamicContextProvider,
DynamicWidget,
} from "@dynamic-labs/sdk-react-core";
import {
isZeroDevConnector,
ZeroDevSmartWalletConnectors,
} from "@dynamic-labs/ethereum-aa";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
const SignerAddress = () => {
const { primaryWallet } = useDynamicContext();
const [signerAddress, setSignerAddress] = useState("");
useEffect(() => {
if (!primaryWallet) {
return;
}
const {
connector,
address, // This is your smart wallet address
} = primaryWallet;
if (!isZeroDevConnector(connector)) {
return;
}
const signerConnector = connector.eoaConnector;
if (!signerConnector) {
return;
}
const getAddress = async () => {
const address = await signerConnector.getAddress();
if (!address) {
return;
}
setSignerAddress(address);
};
getAddress();
}, [primaryWallet]);
return My Signer address: {signerAddress};
};
const App = () => (
);
export default App;
```
For more information about ZeroDev's AA features, go to [ZeroDev's documentation](https://docs.zerodev.app/)
## FAQ
Yes, but not today with Dynamic. We are working on developing new flows to make managing existing EOA wallets with SCWs a smooth transition.
It depends which provider you choose. For example, with ZeroDev you have the following options:
* Arbitrum One
* Avalanche
* Base
* Binance Smart Chain
* Ethereum
* Optimism
* Polygon
Each provider will handle things differently, so it's always better to check
directly with them. For example, with ZeroDev you can't change the network
after deployment. With Alchemy, it might be possible in a roundabout way.
With Dynamic, you will need to use either ZeroDev or Alchemy. If you have
alternative AA providers, please reach out via our
[slack](https://www.dynamic.xyz/slack).
This is [an advanced feature](https://www.dynamic.xyz/pricing), but there is
no additional cost from Dynamic beyond the advanced tier itself. The providers
do take a transaction fee, which you can see on their respective pricing
pages.
We are adding customers one at a time for a few weeks, after which we’ll open
it up to the general public as GA.
Private keys are managed by the EOA, not the SCW. Every SCW has a Signer, or
Owner, which is the EOA.
The only way the SCW can be recovered is if the EOA is recovered. The SCW is a
smart contract, and the EOA is the owner of the SCW. If the EOA is lost, the
SCW is lost.
It's a common misconception that AA wallets are inherently non-custodial. In fact, whether a wallet is AA or not has nothing to do with whether it's custodial. It's the signers that determine whether a wallet is custodial.
That is, if you use a non-custodial signer such as local private keys to manage your AA wallet, then it's non-custodial. At the same time, if you use a custodial key provider such as Fireblocks to manage your AA wallet, then it's custodial.
In any case, whoever has custody over the signers has custody over the wallet.
We have wrapped our providers so you get all the benefit, and more. For
example, we handle the transaction hashing so it’s user friendly and are able
to show the SCW in our widgets and connectors.
# ZKsync SSO
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/zksyncsso
This feature is currently in closed beta. Reach out to us to get access.
ZKsync SSO is a new way to create wallets for users on ZKsync. Together with Dynamic, it allows you to create embedded walelts with an email or social login, combined with a direct on chain passkey. Think about it as an Account Abstraction layer on ZKsync.
If you're building a chain on ZKsync, you can leverage this feature together with our [global wallet](https://www.dynamic.xyz/features/global-wallet) solution to provide a seamless experience for your users.
[Reach out](https://www.dynamic.xyz/get-started) to learn more and get access to the beta.
# Apple
Source: https://docs.dynamic.xyz/social-providers/apple
## Important information
For every Dynamic `environmentId`, please ensure to use a unique set of Apple oauth app credentials.
Apple will only return a user's `email` on the first login across any site that uses the OAuth application's credentials.
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Apple:
1. Open Dynamic dashboard, in either social account linking on the [Login Methods](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-apple) depending on whether you want to do linking or signup:
1. Open the Apple section, copy the Redirect URL and paste it in the "Valid OAuth Redirect URIs" field in Apple.
2. Go to the [Apple Developers](https://developer.apple.com/account) dashboard and sign in to your account.
3. Navitate to [Membership details](https://developer.apple.com/account/#/membership)
4. Find your Team ID.
5. In Apple's dashboard, navigate to Identifiers under [Certificates, IDs, & Profiles](https://developer.apple.com/account/resources/identifiers/list/serviceId)
6. Add a new Service ID.
7. Click your newly created Services ID to enable it for Sign in with Apple. Then, click Configure.
8. In Return URLs, you'll paste the Redirect URI listed on Dynamic Dashboard for your Apple provider. Once you've entered the correct information, you can save your Services ID by clicking Continue, then Save.
9. Return to Dynamic Dashboard, you should have Team ID and Services ID populated by this step. Now you can paste your Key ID as well. Finally, you'll need to paste the contents of the Private Key file you downloaded from Apple's dashboard.
That's it! You now have OAuth credentials for your Apple application that you can use in Dynamic.
# Discord
Source: https://docs.dynamic.xyz/social-providers/discord
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Discord:
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and sign in to your account.
2. Once you're signed in, click on the "New Application" button in the top right corner of the screen.
3. Enter a name for your application and click the "Create" button.
4. In the left-hand menu, click on the "OAuth2" tab.
5. Back in the Dynamic dashboard, in either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-discord) depending on whether you want to do linking or signup.
1. Copy the "Client ID" and "Client secret" from the application you created in Discord and paste it into the modal in the Dynamic Dashboard.
2. We recommend you already copy the Redirect URL to your clipboard so you can use it in the next step.
3. Click Confirm.
6. Return to your Discord OAuth2 page:
1. Under the "OAuth2 Redirects" section, click the "Add Redirect" button.
2. Copy & paste the Redirect URL provided in your Dynamic Dashboard in the prior step.
3. Copy the Redirect URL and paste it in the section on Discord page.
4. Click "Save changes" button.
That's it! You now have OAuth credentials for your Discord application that you can use in Dynamic.
If you need more help with configuring the Discord OAuth App check their docs [here](https://discord.com/developers/docs/topics/oauth2).
# Epic Games
Source: https://docs.dynamic.xyz/social-providers/epicgames
## Creating a new App
Here's the step-by-step guide on how to set up a new account, organization, product, and application to set up OAuth2 with Epic Games:
Create an Epic Games Developer Account:
1. [Go to Epic Games Developer Portal](https://dev.epicgames.com/) to create an account
* Once your account is created, log in to the Developer Portal.
2. [Create an Organization](https://dev.epicgames.com/portal/en-US/profile/signup)
* Click Create Organization and fill in the required details.
* Click Submit to create the organization.
3. Register a Product:
* In the Developer Portal, go to the Products section.
* Click on Create Product and fill in the product details.
4. Create an Application:
* Go to the Applications section in the Developer Portal.
* Click Create Application.
* You'll need to validate your domain. It will ask you to add a TXT DNS record to your domain.
* Fill in the application details such as name, description, and redirect URI (the URL where users will be redirected after successful authentication).
5. Create an Client:
* Go to Product Settings > Client. Click Add new Client.
* Fill in the application details such as name, description, and redirect URI (the URL where users will be redirected after successful authentication).
6. Get Client ID and Client Secret:
* Go to Product Settings
* Copy the **Client ID** and **Client Secret** that are generated for your application.
7. Turn on Epic Games in [Dynamic Dashboard](https://app.dynamic.xyz/dashboard/log-in-user-profile)
* Go to Log in & User Profile, switch on Epic Games and add **Client ID** and **Client Secret**
That’s it! You now have OAuth credentials for your Epic Games application that you can use in Dynamic.
# Facebook
Source: https://docs.dynamic.xyz/social-providers/facebook
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Facebook:
1. Go to the [Facebook Developers](https://developers.facebook.com/apps/) website and sign in to your account.
2. Once you're signed in, click on the "My Apps" dropdown menu in the top navigation bar and select "Create App."
3. Choose the type of app you want to create.
4. Enter a name for your app and click "Create App ID."
5. Once your app is created under "Add a product" section click "Set up" under Facebook Login card.
6. Select "Settings" under "Facebook Login" section in the left side bar.
7. Back in the Dynamic dashboard, in either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-facebook) depending on whether you want to do linking or signup:
1. Open the Facebook section, copy the Redirect URL and paste it in the "Valid OAuth Redirect URIs" field in Facebook.
2. Click "Save changes" on the bottom of the screen.
8. Select "Basic" under "Settings" section in the left side bar.
9. Copy the "App ID" and "App secret" and paste it into "Set up Facebook Auth" Modal in the Dynamic Dashboard.
That's it! You now have OAuth credentials for your Facebook application that you can use in Dynamic.
If you need more help with configuring the Facebook OAuth App check their docs [here](https://developers.facebook.com/docs/development/create-an-app).
# Farcaster
Source: https://docs.dynamic.xyz/social-providers/farcaster
## Configuration
## User Values
We map the Farcaster values returned to the standard oauth user values (found in [verified Credentials](/react-sdk/objects/verified-credential)):
```typescript
{
id: string; // Unique ID (Dynamic)
publicIdentifier: string; // Farcaster username
oauthAccountId: string; // Farcaster ID
oauthProvider: ProviderEnum; // "farcaster"
oauthAccountPhotos?: []string; // Farcaster PFP URLs
oauthDisplayName?: string; // name if provided
oauthUsername?: string; // Farcaster username
};
```
To get this information, you can use the `user` object returned from the [`useDynamicContext` hook](/react-sdk/hooks/usedynamiccontext) i.e.
```typescript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const { user } = useDynamicContext();
if (user) {
console.log(user.verifiedCredentials);
}
```
You can then use this information to create enhanced experiences within your app!
# Github
Source: https://docs.dynamic.xyz/social-providers/github
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for GitHub:
1. Go to the [GitHub Developer Settings](https://github.com/settings/developers) page and sign in to your account.
1. If you're on your profile page, click "Developer Settings" at the bottom of the left-hand menu.
2. Click on the Oauth Apps menu and then "Register a new application".
3. Enter a name for your application, the homepage URL, and the callback URL.
1. Enter whatever name and homepage URL you want. For the callback URL follow the steps below.
2. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-github) depending on whether you want to do linking or signup.
3. Open the Github section of the configuration.
4. Copy the Redirect URL and paste it in the Callback URL section in Github.
4. Click "Register application" button.
5. Github will create an OAuth app for you and will redirect you to the details page.
6. Click "Generate a new client secret" button
7. Copy the "Client ID" and "Client secret" you've just created and paste it into "Set up Github Auth" Modal in the Dynamic Dashboard.
8. Click "Confirm" button.
That's it! You now have OAuth credentials for your GitHub application that you can use in Dynamic.
If you need more help with configuring the Github OAuth App check their docs [here](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app).
# Google
Source: https://docs.dynamic.xyz/social-providers/google
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Google:
1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and sign in to your account.
2. Once you're signed in, click on the project dropdown menu in the top navigation bar and select or create the project you want to use for your OAuth credentials.
3. In the left-hand menu, click on the "APIs & Services" tab, then click on the "Credentials" submenu.
4. Complete the "Configure Consent Screen" instructions if you haven't completed this before.
5. Click on the "+ Create Credentials" in the horizontal navigation below the search bar, then select "OAuth client ID" from the dropdown menu.
6. Select the "Web application" application type.
7. Enter a name for your OAuth client ID, such as "My App OAuth Credentials."
8. In the "Authorized JavaScript origins" field, enter the origin of your web application, for example, "[https://example.com"]().
9. In the "Authorized redirect URIs" field, enter the URI that Google should redirect users to after they authorize your application. This will be provided by Dynamic.
1. You can find the "Authorized redirect URI" in either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-google) depending on whether you want to do linking or signup.
2. Open the the Google section of the configuration page you brought up in the previous step.
3. Copy the Redirect URL, paste it in the section on Google page and click "Save changes" button.
10. Click the "Create" button to create your OAuth client ID.
11. After creating your OAuth client ID, you should see a "Client ID" and "Client Secret" on the "Credentials" page. These are the credentials you'll need to copy and paste them into "Set up Google Auth" Modal in the Dynamic Dashboard.
That's it! You now have OAuth credentials for your Google application that you can use in Dynamic.
If you need more help with configuring the Google OAuth App check their docs [here](https://support.google.com/cloud/answer/6158849?hl=en).
## Submitting your app for review
By default, when you click "log in with Google", Google will display dynamicauth.com in the name of the pop up. To show your organization name and logo in the Google auth consent screen instead, you can apply to a Google "brand review". You can do this by following the instructions [here](https://support.google.com/cloud/answer/13461325?sjid=10558921481157129495-EU).
# LINE
Source: https://docs.dynamic.xyz/social-providers/line
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for LINE
1. Go to the [LINE Developer Portal](https://developers.line.biz/console) and sign in or create an account
2. Click "Create" under the "Providers" section
3. Specify a "Provider name"
4. Click on "Create a LINE Login channel"
5. Set the "Company or owner's country or region" for your channel, "Channel name", "Channel description"
6. Under "App types", select "Web app"
7. Review and agree to the terms and conditions and click "Create"
8. Click on the newly created channel and select "LINE Login" tab
9. Under "Callback URL"
1. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-line) depending on whether you want to do linking or signup.
2. Open the LINE configuration section.
3. Copy the Redirect URL and paste it in the "Callback URL" field in LINE Developer Portal.
10. Select the "Basic settings" tab now
11. Copy the "Channel ID" and "Channel Secret" and paste it into the "Set up LINE Auth" Modal in the Dynamic Dashboard as "Client ID" and "Client Secret"
12. Make sure to publish your channel before testing out login
That's it! You now have OAuth credentials for your LINE application that you can use in Dynamic.
# Social Providers Overview
Source: https://docs.dynamic.xyz/social-providers/overview
This section relates to setting up oauth providers inside Dynamic. You would do this for two purposes:
1. To allow [linking of social accounts](/users/social-linking) as part of their profile.
2. To allow users to [sign up or log in with social accounts](/authentication-methods/email-social-sms).
In both cases you will need to configure whatever social providers you want to use. Dynamic supports the following providers:
* [Apple](/social-providers/apple)
* [Discord](/social-providers/discord)
* [Epic Games](/social-providers/epicgames)
* [Farcaster](/social-providers/farcaster)
* [Facebook](/social-providers/facebook)
* [GitHub](/social-providers/github)
* [Google](/social-providers/google)
* [LINE](/social-providers/line)
* [Shopify](/social-providers/shopify)
* [Spotify](/social-providers/spotify)
* [Telegram](/social-providers/telegram)
* [TikTok](/social-providers/tiktok)
* [Twitch](/social-providers/twitch)
* [Twitter](/social-providers/twitter)
If you need to get the auth token of a valid OAuth provider, use [this API
request](https://docs.dynamic.xyz/api-reference/users/getUserOauthAccessToken).
# Shopify
Source: https://docs.dynamic.xyz/social-providers/shopify
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Shopify:
1. Install the [Headless](https://apps.shopify.com/headless) app on your existing Shopify store
2. On the next page, click on `Create storefront`
3. Click on `Manage` next to `Customer Account API`
4. Select `Confidential` under `Client Type` and click `Save`
5. Under `Application setup` paste your "Redirect URL" (Redirect URL can be found in the [Dynamic dashboard](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-shopify))
6. Copy and past the `Client ID` and `Client Secret` from `Customer Account API credentials` and paste it into "Set up Shopify Auth" Modal in the Dynamic Dashboard.
7. Find your shopify store ID under `Application Endpoints` in the `Authorization endpoint` URL and paste it into `Shopify Store ID` in the Dynamic Dashboard.
# Spotify
Source: https://docs.dynamic.xyz/social-providers/spotify
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Spotify
1. Go to the [Spotify Developer Portal](https://developer.spotify.com/dashboard) and sign in
2. Click on "Create App" on the right of the screen
3. Specify an "App Name", "App Description"
4. Under "Redirect URIs"
1. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-shopify) depending on whether you want to do linking or signup.
2. Open the Spotify configuration section.
3. Copy the Redirect URL and paste it in the "Redirect URI" field in Spotify Developer Portal.
5. Under "Which API/SDKs are you planning to use?", check "Web API"
6. Check the terms and conditions
7. Click "Save" at the bottom of the form
8. Once saved, click on the app and click "Settings"
9. Copy the "Client ID" and "Client Secret" and paste it into the "Set up Spotify Auth" Modal in the Dynamic Dashboard
That's it! You now have OAuth credentials for your Spotify application that you can use in Dynamic.
# Telegram
Source: https://docs.dynamic.xyz/social-providers/telegram
**Attention Required: Telegram Bot Secret Security**
To use automatic wallet creation for Telegram, developers must create a Telegram bot configured with a bot secret, which serves as both the control mechanism for the bot and as a symmetric key for authentication. This key technically grants the developer an ability to sign authentication data and actions with a wallet. Any compromise of the bot secret internally or externally can expose users and their accounts to significant risk.
Securing this symmetric key is critical to ensuring the integrity of all Telegram login sessions in your application.
## Summary
This feature allows developers to obtain authentication credentials with Telegram so users can log in and link their Telegram username to their account. The Telegram handle will be added as a verified credential in the user's profile.
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Telegram:
1. Open Telegram and search for the "BotFather" bot, or click [here](https://t.me/botfather) to start a conversation with it.
2. Start a conversation with BotFather by typing `/start`.
3. Type `/newbot` to create a new bot.
4. Follow the prompts to name your bot and create a unique username for it. The username must end with "bot" (e.g., `mycoolbot` or `my_cool_bot`).
5. After creating your bot, you will receive a message with the bot's token. Copy this token as it will be needed for configuration.
6. Navigate to the Dynamic Dashboard social section. ([https://app.dynamic.xyz/dashboard/log-in-user-profile](https://app.dynamic.xyz/dashboard/log-in-user-profile)).
7. Open the Telegram configuration module.
8. Paste the token you received from BotFather into the "Bot Token" field.
9. Paste the bot's username in the "Bot Name" field.
10. You also need to set up a domain URL for your bot. In the Dynamic Dashboard, find the "Bot Domain" field in the Telegram configuration section.
11. Copy the URL provided by Dynamic.
12. Return to your conversation with BotFather and type `/setdomain`.
13. When prompted, paste the URL you copied in the previous step.
That's it! You now have OAuth credentials for your Telegram application that you can use in Dynamic.
If you need more help with configuring the Telegram OAuth App check their docs [here](https://core.telegram.org/bots#botfather).
## Frequently Asked Questions
### What is BotFather?
BotFather is an official bot on Telegram. It allows developers to create and manage their own Telegram bots and is required for obtaining the necessary credentials to interact with the Telegram API.
### What username should I use?
We suggest using your brand or application name to avoid confusing users when they authenticate. Example: `Dynamic_bot`.
# TikTok
Source: https://docs.dynamic.xyz/social-providers/tiktok
Due to TikTok's requirement to verify URL ownership for all redirect URLs, TikTok cannot be used with Dynamic shared credentials in sandbox or production environments.
You will need create an app with custom credentials. To go to production, you will need use to contact us for custom domains.
## Creating a new sandbox application
• When you are creating your app, make sure to specify "Configure for Web" for your app type (it will be treated as a web app in the context of OAuth)
• Your OAuth client\_id is referred to as client\_key
• As of September 2024, TikTok requires Terms of Service URL, Privacy Policy URL, your Desktop or web URL, Redirect URI and Webhooks Callback URL
• TikTok docs and pre-requisites can be found [here](https://developers.tiktok.com/doc/login-kit-web?enter_method=left_navigation)
Here are the step-by-step instructions for obtaining OAuth credentials for TikTok:
1. Go to the [TikTok Developer Portal](https://developers.tiktok.com/apps) and sign in to your account.
2. Once you're signed in, click on "Connect an app"
3. Fill out the "App name" and specify if this is for an Individual or an Organization, then click "Confirm"
4. Make sure that "Sandbox" is selected. Sandbox applications do not require domain verification
5. Fill out the "Category", "Description", "Terms of Service URL", "Privacy Policy URL"
6. Select "Web" under "Platforms"
7. Under "Products", select "Add Products" and click on "Login Kit"
8. Under "App info" paste your "Redirect URL" (Redirect URL can be found in the Dynamic dashboard [https://app.dynamic.xyz/dashboard/log-in-user-profile#social-tiktok](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-tiktok))
9. Enter your "Website URL".
10. In order to allow test users to login, click "Add account" under "Target Users" and link an existing TikTok account
11. Click save under the form.
12. Copy and paste the "Client Key" and "Client Secret" and paste it into "Set up TikTok Auth" Modal in the Dynamic Dashboard.
That's it! You now have OAuth credentials for your TikTok application that you can use in Dynamic.
## Creating a production app (Enterprise Only)
Follow the same instructions above for setting up an app.
In order for you to add the callback URI, you will need to follow these steps
1. Click on `URL Properties` in the top right of the TikTok developer Portal
2. In the next modal, click on `Verify properties`
3. Click on `Domain` and enter `app.dynamicauth.com` and click `Verify` to the right of the text box
4. In the next screen, click on `Copy` to the right of the TXT record and send it to us. After this click `Verify`. **Note that the domain verification will not work until we have added the record on our domain**
5. Once we have confirmed the record is added, click on `Continue to verify` and verify the domain
6. Add the callback URI specified in our dashboard under TikTok settings
7. Continue with your TikTok app submission
# Twitch
Source: https://docs.dynamic.xyz/social-providers/twitch
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Twitch:
1. Go to the [Twitch Developer Portal](https://dev.twitch.tv/console) and sign in to your account.
2. Once you're signed in, click on the [Applications](https://dev.twitch.tv/console/apps) on the left nav bar
3. Click on "Register Your Application", and enter the following information:
1. Name of your application
2. OAuth Redirect URLs
1. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-twitch) depending on whether you want to do linking or signup.
2. Open the Twitch configuration section.
3. Copy & paste the Redirect URL provided in your Dynamic Dashboard to the text field in Twitch
3. Category (You can select any that is most appropriate)
4. Click "Create"
5. You should see a new row added to the "Developer Applications" table
6. On the right side of the table in the app you just created, click on "Manage"
7. Click on "New Secret", this will generate a secret key you will see only once
8. Copy the "Client ID" and "Client secret" from the application you created in Twitch and paste it into the modal in the Dynamic Dashboard.
That's it! You now have OAuth credentials for your Twitch application that you can use in Dynamic.
# Twitter/X
Source: https://docs.dynamic.xyz/social-providers/twitter
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Twitter:
1. Go to the [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard) and sign in to your account.
2. Once you're signed in, go to "Projects & Apps", choose the project you want to configure,and in the "Apps" section at the bottom of the page, click the gears icon on the right.
3. At the bottom of the following page, under "User authentication settings" select "Set up"
4. Select "App permissions" and "Type of App" you want.
5. Under "App info" paste the "Redirect URL":
1. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-twitter) depending on whether you want to do linking or signup.
2. Open the Twitter configuration sectione.
3. Copy the Redirect URL and paste it in the "Redirect URL" field in Twitter Developer Portal.
6. Enter your "Website URL".
7. Click save under the form.
8. Copy the "Client ID" and "Client Secret" and paste it into "Set up Twitter Auth" Modal in the Dynamic Dashboard.
That's it! You now have OAuth credentials for your Twitter application that you can use in Dynamic.
If you need more help with configuring the Twitter OAuth App check their docs [here](https://developer.twitter.com/en/docs/authentication/guides).
# Store Approval Issues
Source: https://docs.dynamic.xyz/troubleshooting/browser-extension/browser-extension-approval-issues
# Google Play Store Approval Guide
When submitting browser extensions to the Google Play Store, you may encounter specific restrictions that can lead to rejection. This guide covers common issues and their solutions.
## Remote Code Loading in Manifest V3
### The Issue
Google Play Store prohibits Manifest V3 extensions from loading remotely hosted code. A common violation occurs when your extension bundle includes code that loads external scripts, such as the AppleID script from `https://appleid.cdn-apple.com/`.
### Solution: Replacing Remote Loaders
To resolve this issue, you can configure your bundler to replace remote script loaders with local dummy files. We provide solutions for both Vite and Webpack bundlers.
#### Step 1: Create a dummy loader file
First, create a dummy loader file that will replace the remote script loader:
```javascript
// src/loadAppleId.js
"use client";
const loadAppleId = () => {};
export { loadAppleId };
```
#### Step 2: Configure your bundler
##### Option 1: Using Vite
Configure Vite to alias the remote loader to your dummy file:
```typescript
// vite.config.ts
import { defineConfig } from "vite";
import path from "path";
const replaceLoadAppleIdScriptWithCustomScriptPlugin = {
name: "replace-loadAppleId",
enforce: "pre",
resolveId(source) {
if (source.includes("loadAppleId")) {
return path.resolve(__dirname, "src/loadAppleId.js");
}
},
} as const;
export default defineConfig({
plugins: [react(), replaceLoadAppleIdScriptWithCustomScriptPlugin],
// ... other config options
});
```
For a complete Vite implementation example, check out our [Vite reference implementation](https://github.com/dynamic-labs/browser-extension-bundled-with-vite-example/commit/cb24d17435e04f7c21c82527d572aff8bfe42e1a).
##### Option 2: Using Webpack
Configure Webpack to alias the remote loader to your dummy file:
```javascript
// webpack.config.js
const path = require('path');
const webpack = require('webpack');
module.exports = {
// ... other config options
resolve: {
alias: {
// Alias any imports containing loadAppleId to our local dummy file
loadAppleId: path.resolve(__dirname, 'src/loadAppleId.js'),
},
},
plugins: [
// ... other plugins
// Add a plugin to replace any direct references to the Apple ID script URL
new webpack.NormalModuleReplacementPlugin(
/loadAppleId/,
path.resolve(__dirname, 'src/loadAppleId.js')
),
],
};
```
For a complete Webpack implementation example, check out our [Webpack reference implementation](https://github.com/dynamic-labs/browser-extension-bundled-with-webpack-example).
# Dynamic Doctor
Source: https://docs.dynamic.xyz/troubleshooting/dynamic-doctor
Web3 moves fast, and this means that version management when it comes to packages is difficult. Often one library might require a specific version of Viem while another requires a different version. This is where Dynamic Doctor can help.
Use it if you've installed and initialized Dynamic but you're getting some errors. Often these can be related to the versions currently installed even though the errors themselves might not indicate it.
## Usage
In the root of your project, run the following command:
```bash
npx dynamic-doctor@latest run
```
## Output
You will see a list of issues found and a file `dynamic-doctor-report-.html` will be generated in your root directory.
Make sure that all of the dynamic packages have the same version, and if that doesn't fix things, you can review the generated file and as long as it doesn't contain any sensitive data, share this file with the Dynamic team to help diagnose the issue.
# Initial Steps
Source: https://docs.dynamic.xyz/troubleshooting/general
If you're experiencing any issues with your app, please follow these initial troubleshooting steps:
See if you can replicate on [demo.dynamic.xyz](https://demo.dynamic.xyz).
See if you can replicate using an app creating with `npx create-dynamic-app@latest`.
Run [the Dynamic Doctor](/troubleshooting/dynamic-doctor) in your own codebase.
Check the other troubleshooting guides in this section, and [the "How Do I" page](/how-do-i).
If you can replicate on demo or in create-dynamic-app, please let us know immediately [via Slack](https://dynamic.xyz/slack) using the "#bug-report" channel.
If you cannot replicate on demo or on create-dynamic-app, the doctor does not identify any issues and we don't have a troubleshooting or how-do-i guide, it means it might be isolated to your codebase.
In this case, we recommend paring back your codebase to the minimal amount of code that reproduces the issue, and then sharing the code with us [via Slack](https://dynamic.xyz/slack) using the "#bug-report" channel.
It's also helpful to search in the Slack workspace linked above to see if someone else has had the same issue and found a resolution.
# Wallet is redirecting to the App Store
Source: https://docs.dynamic.xyz/troubleshooting/mobile/wallet-is-redirecting-to-the-app-store
If a user is loading the site on on iOS, and is being redirected to the mobile app store instead of the wallet, then a user may need to uninstall and reinstall the wallet.
This is happening because the deeplinks "breaks" (ie, a user is getting redirected to the app store). The scenario specifically arises after a user does the following:
1. The user is in incognito mode
2. The user will get a pop up to Cancel/Open the wallet
3. The user clicks cancel.
This will cause the deeplinks in iOS for that wallet to break across any site. The only way to reset the deeplinks for the impacted wallet is to delete and re-install the wallet.
# Hydration failed because initial UI does not match what was rendered on the server
Source: https://docs.dynamic.xyz/troubleshooting/next/hydration-failed
This error happens when there is a mismatch between the React tree rendered during the first render in the browser (called hydration), and the React tree that was pre-rendered from the server.
Hydration is the process of React converting pre-rendered HTML into an interactive application by attaching event handlers.
In general these errors happen with components that should only be rendered in the browser (i.e. components that depend on state like the user being logged in or not, like the navigation).
To easily resolve this, you can wrap those components with our own `IsBrowser` component, exported from `sdk-react-core`.
```jsx
import { IsBrowser } from "@dynamic-labs/sdk-react-core";
const MyComponent = () => {
return (
)
};
```
# FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed
Source: https://docs.dynamic.xyz/troubleshooting/next/javascript-heap-out-of-memory
You might run into the following error when building your application when using the `@dynamic-labs/sdk-react-core` package in a NextJS version 14.x project.
```
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
```
## Solution
Update `next.config.js` to optimize `@dynamic-labs/sdk-react-core`:
```typescript
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
optimizePackageImports: ["@dynamic-labs/sdk-react-core"],
},
};
export default nextConfig;
```
# Module not found: Can't resolve 'encoding'
Source: https://docs.dynamic.xyz/troubleshooting/next/module-not-found
If you ever see console warning like the following related to encoding, lokijs and pino-pretty:
```
./node_modules/node-fetch/lib/index.js
Module not found: Can't resolve 'encoding' in '/Users/xxx/xxx/node_modules/node-fetch/lib'
```
You can fix it by adding the following to your `next.config.js`:
```js
webpack: (config) => {
config.externals.push("pino-pretty", "lokijs", "encoding");
return config;
};
```
It would appear that it's coming from the following issue: [https://github.com/WalletConnect/walletconnect-monorepo/issues/1908#issuecomment-1487801131](https://github.com/WalletConnect/walletconnect-monorepo/issues/1908#issuecomment-1487801131)
# Cannot convert a BigInt value to a number
Source: https://docs.dynamic.xyz/troubleshooting/react/cannot-convert-a-bigInt-value-to-a-number
If using `create-react-app`, without a specific browserlist, the compiler tries to compile for older browser versions.
[BigInts are not supported by all browser versions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#browser_compatibility), but are still used in many libraries
This means that you may see the following error when trying to run your react app: `Cannot convert a BigInt value to a number`
Here is one example in the wild: [https://github.com/0xs34n/starknet.js/issues/37#issuecomment-955797303](https://github.com/0xs34n/starknet.js/issues/37#issuecomment-955797303)
If you see the error, you can fix it by instructing your compiler to target only recent browser versions. You do this by adding the following to your package.json:
```
{
“browserslist”: {
“production”: [
“chrome >= 67”,
“edge >= 79",
“firefox >= 68”,
“opera >= 54",
“safari >= 14”
],
“development”: [
“last 1 chrome version”,
“last 1 firefox version”,
“last 1 safari version”
]
}
}
```
As a precaution, better to also `rm -rf node_modules/.cache` before building or running your application again.
# Cannot resolve rpc-websockets
Source: https://docs.dynamic.xyz/troubleshooting/react/cannot-resolve-rpc-websockets
If you are seeing an error like `Module not found: Can't resolve 'rpc-websockets/dist/lib/client.cjs'` when trying to use the SDK, you can fix this by adding the following to your `package.json` file:
Note that even if you are not using Solana, you still need to include the `@solana/web3` line below. This will be fixed in the next major SDK release (V3).
```json npm
"overrides": {
"rpc-websockets": "7.10.0",
"@solana/web3.js": "1.91.6"
},
```
```json yarn
"resolutions": {
"rpc-websockets": "7.10.0",
"@solana/web3.js": "1.91.6"
}
```
# Failed to parse source map warnings
Source: https://docs.dynamic.xyz/troubleshooting/react/failed-to-parse-source-map-warnings
If using create-react-app v5, you may see some warnings (although they appear like errors) when running/building your react application.
This has been reported as seen in this [Github discussion](https://github.com/facebook/create-react-app/discussions/11767).
Example Warning Message
```
WARNING in ./node_modules/json-rpc-engine/dist/mergeMiddleware.js
Module Warning (from ./node_modules/source-map-loader/dist/cjs.js):
Failed to parse source map from 'node_modules/json-rpc-engine/src/mergeMiddleware.ts'
file: Error: ENOENT: no such file or directory,
open 'node_modules/json-rpc-engine/src/mergeMiddleware.ts'
```
These warnings can be ignored, and do not affect your application. However, if you wish to suppress the warnings and disable source map loader altogether, you can set this environment variable:
```Shell
export GENERATE_SOURCEMAP=false
```
# Input Cannot Be Focused
Source: https://docs.dynamic.xyz/troubleshooting/react/input-cannot-be-focused
Sometimes inputs on Dynamic modal components cannot receive focus. This is a common issue with libraries that use `react-focus-lock` to manage focus.
This is often solved by disabling the focus trap on certain components so that the modal elements can be focused.
## Chakra UI Example
```tsx
{/* ... */}
```
# Jest Error: SyntaxError: Cannot use import statement outside a module
Source: https://docs.dynamic.xyz/troubleshooting/react/jest-error-syntaxerror-unexpected-token-export
When using Jest to test a component that renders DynamicContextProvider, you might run into an error like:
```
FAIL app/page.spec.tsx
● Test suite failed to run
Jest encountered an unexpected token
Jest failed to parse a file. This happens e.g. when your code or its dependencies use non-standard JavaScript syntax, or when Jest is not configured to support such syntax.
Out of the box Jest supports Babel, which will be used to transform your files into valid JS based on your Babel configuration.
By default "node_modules" folder is ignored by transformers.
Here's what you can do:
• If you are trying to use ECMAScript Modules, see https://jestjs.io/docs/ecmascript-modules for how to enable it.
• If you are trying to use TypeScript, see https://jestjs.io/docs/getting-started#using-typescript
• To have some of your "node_modules" files transformed, you can specify a custom "transformIgnorePatterns" in your config.
• If you need a custom transformation specify a "transform" option in your config.
• If you simply want to mock your non-JS modules (e.g. binary assets) you can stub them out with the "moduleNameMapper" config option.
You'll find more details and examples of these config options in the docs:
https://jestjs.io/docs/configuration
For information about custom transformations, see:
https://jestjs.io/docs/code-transformation
Details:
/Users/testuser/code/test-jest-thing/node_modules/uint8arrays/esm/src/concat.js:1
({"Object.":function(module,exports,require,__dirname,__filename,jest){import { allocUnsafe } from './alloc.js';
^^^^^^
SyntaxError: Cannot use import statement outside a module
10 | some text
11 |
> 12 | );
| ^
13 | }
14 |
at Runtime.createScriptFromCode (node_modules/jest-runtime/build/index.js:1496:14)
at Object. (app/page.tsx:12:19)
at Object. (app/page.spec.tsx:7:54)
```
This can be easily fixed by mocking DynamicContextProvider:
```JavaScript
jest.mock("@dynamic-labs/sdk-react-core", () => ({
DynamicContextProvider: ({ children }) => children,
}));
```
# Modal pop up isn't visible
Source: https://docs.dynamic.xyz/troubleshooting/react/pop-up-isnt-visible-on-some-devices
Make sure that you set the body min-height to 100vh
`body {
min-height: 100vh;
}
`
# Vite.js polyfills necessary for Dynamic SDK
Source: https://docs.dynamic.xyz/troubleshooting/react/vitejs-polyfills-necessary-for-dynamic-sdk
## Vite.js requires global and process polyfills
If you're using Vite.js with react and using the Dynamic SDK you may get this error in your console:
```
util.js:109 Uncaught ReferenceError: process is not defined
```
This is because one of the many libraries that our SDK depends on uses the `process` module which is natively not in the browser environment nor is it automatically polyfilled by Vite.
#### Polyfill `process` using `vite.config.js`
To fix this we must modify the `vite.config.js` file to modify `esbuild` to polyfill this for us. Here is a minimal example config:
```TypeScript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { NodeGlobalsPolyfillPlugin } from "@esbuild-plugins/node-globals-polyfill";
import { NodeModulesPolyfillPlugin } from "@esbuild-plugins/node-modules-polyfill";
export default defineConfig({
optimizeDeps: {
esbuildOptions: {
// Enable esbuild polyfill plugins
plugins: [
NodeGlobalsPolyfillPlugin({
process: true,
}),
NodeModulesPolyfillPlugin(),
],
},
},
plugins: [react()],
});
```
#### Warning: You may still see a console error `React Static Flag Error`
After applying the polyfill, you may still see an error for `React Static Flag Error`. This is currently expected. To learn more, checkout the troubleshooting page [React Static Flag Error](/troubleshooting/solved/react-static-flag-error). At this time, you can ignore this error in local development environment.
# Vite.js - Starknet module export error
Source: https://docs.dynamic.xyz/troubleshooting/react/vitejs-starknet-module-export-error
If you're using Vite.js with react and using the Dynamic SDK with Starknet, you may get a similar error to this one in your console:
```
Uncaught SyntaxError: The requested module '/[APP_PATH]/node_modules/.vite/deps/starknet.js?v=5327d40a' does not provide an export named 'default'
```
This is because older versions of Vite don't know how to resolve the `starknet` module exports.
#### Add `resolve` alias for `starknet` using `vite.config.js`
To fix this we must modify the `vite.config.js` file to add an alias for `starknet`. Here is a minimal example config:
```TypeScript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import * as path from 'path';
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
'starknet': path.resolve(__dirname, 'node_modules/starknet/dist/index.mjs')
}
}
})
```
# Can't resolve 'crypto'
Source: https://docs.dynamic.xyz/troubleshooting/solana/can't-resolve-'crypto'
If you're using Solana, you may encounter an error like this:
```
Module not found: Can't resolve 'crypto'
```
This is because you need to polyfill the `crypto` module.
If you're using webpack for example, your webpack config should look something like this:
```
const webpack = require('webpack');
module.exports = {
resolve: {
fallback: {
"crypto": require.resolve("crypto-browserify"),
"stream": require.resolve("stream-browserify"),
"buffer": require.resolve("buffer/")
}
},
plugins: [
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
}),
]
};
```
# TypeScript Compilation Errors
Source: https://docs.dynamic.xyz/troubleshooting/typescript/typescript-compilation-error
We support TypeScript v5.x. If you have a compilation error and are on TypeScript 4 or lower, either upgrade to latest, or add an override to your package.json:
```
"dependencies": {
...
},
"overrides": {
"typescript": "5.2.0"
},
```
# WalletConnect Unsupported Chain
Source: https://docs.dynamic.xyz/troubleshooting/walletconnect/walletconnect-unsupported-chain
A common error encountered when using WalletConnect is `Unsupported chain`. This error occurs when the chain ID of the network you are trying to connect to is different than the chain specified by the WalletConnect provider.
```
UnknownRPCError: An unknown RPC error occurred.
Details: Unsupported chain
```
To resolve the above error, the `DynamicContextProvider` can be configured to dynamically change the desired WalletConnect chain ID of the network you are trying to connect to using the `walletConnectPreferredChains` property. [See here](/react-sdk/providers/dynamiccontextprovider#settings)
```jsx
The args returned by handleAuthenticatedUser is a [UserProfile](/react-sdk/objects/userprofile).
```jsx
{
console.log("handleBeforeAuth was called", args);
await customUserObjectProcess(args.user);
},
},
}}
>
{/* ... rest of your app ... */}
```
## User Created Webhook
One of the valid webhook events you can listen to is called `user.created` (learn more about event types [here](http://localhost:3001/developer-dashboard/eventTypes)).
All you will need to get started is a server that can receive events, and then you can plug in that URL in the dashboard. [Learn more about setting up the webhook step by step here](/developer-dashboard/webhooks#setting-up-webhooks).
## onAuthSuccess Event
The Dynamic SDK has a concept called [Events](/react-sdk/events/events-introduction) which allows you to hook into lifycycle events of the SDK. One such event is called \[]`onAuthSuccess`]\(/react-sdk/events/onauthsuccess), which is called when the user has successfully authenticated.
This event returns a user object that you can access and do something with.
```jsx
{
console.log('user', args.user);
}
}
}}
>
{/* ... rest of your app ... */}
```
## useDynamicContext
Once placed anywhere inside the component tree that is wrapped by the `DynamicContextProvider`, [the `useDynamicContext` hook](/react-sdk/hooks/usedynamiccontext) will give you access to the `user` object.
```jsx
import { useDynamicContext } from '@dynamic/sdk-react-core';
function MyComponent() {
const { user } = useDynamicContext();
console.log('user', user);
return
Click here to learn more about Verified Credentials
# Email and Phone Verification
Source: https://docs.dynamic.xyz/users/email-verification
**Summary**
This page expands on the information capture described [here](/users/information-capture) but for email, with added support for Uniqueness and Verification options.
**OTP Verification** verifies the validity of an email or phone provided by a customer by sending a One Time Password (OTP to ensure it is a functional and active email/phone. This helps prevent errors in customer communication and ensures that customer data is accurate.
**Uniqueness** ensures that each customer has a unique email address in each project environment to prevent duplicates.
**Usage**
To enable Email and Phone OTP Verification and/or Uniqueness, follow these steps:
1. Navigate to the [Log in & User Profile](https://app.dynamic.xyz/dashboard/log-in-user-profile) page of the developer dashboard.
2. In the Email & Phone Number Selection, toggle both on and click the gear icon to the right of each one.
3. Check the boxes for either or both OTP Verification and/or Uniqueness to enable them.
4. Click the 'Save Changes' button to save your changes.
Note: If Email or Phone Verification is enabled, Email Uniqueness will also be mandatory.
### 🚧 Caution when toggling verification/uniqueness on Live mode
When enabling/disabling Email Verification and/or Uniqueness on live sites, be aware that such actions can result in data inconsistencies. If testing is necessary, it is recommended to conduct the tests on a Sandbox environment and to avoid frequently changing the fields on a live environment.
## Twilio Credentials for enabling additional countries
Specifically for your phone number, Dynamic by default uses its own Twilio credentials and has the United States and Canada on by default. If you wish to enable additional countries, then you will need to add your own Twilio credentials. To do so:
1. Click on the configure button and turn off the `Use Dynamic's credentials` Toggle
2. Enter your Twilio Credentials
3. Add the additional countries you would like to support.
a. It's important you also enable the same countries in your Twilio account. We do not have access to see what countries you have enabled so you must ensure they are both configured the same.
# Get the user's profile
Source: https://docs.dynamic.xyz/users/examples/get-the-users-profile
Here is an example where you can use the user profile to display in a HTML table.
```TypeScript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const UserProfileTable = () => {
const { user } = useDynamicContext();
return (
);
};
```
# Collecting Extra Information (Information Capture)
Source: https://docs.dynamic.xyz/users/information-capture
## Introduction
You may want to collect additional information about you user, whether it's a customer's email, first name, last name, address or other custom fields .
You can do this at any stage... pre-signup, at signup,or at any point in the user's lifecycle. Let's go through each one in turn.
We offer pre-made fields (see note below), or you can [create your own](/custom-fields/overview).
We have a few fields pre-made for you including Alias, First Name, last Name, Job Title, T-Shirt Size, and username.
As an example,
**Username** field is a string that is unique for each project, and has the following validations:
1. Letters A-Z, a-z, numbers 0-9, or symbols \$ ! # % ?
2. Must be length 5 to 20
3. Cannot contain consecutive symbols
4. **T-shirt size** - this field is a dropdown with the standard options available (XS, S, M, L, XL, XXL).
You can specify additional custom fields and how you want to validate these fields by creating a new field in. It is located in the log in and user profile section.
## Enabling field collection
For all instances, we'll want to enable the fields we want to collect:
Scroll to "Additional User Information" in [the Login/User Profile section of the dashboard](https://app.dynamic.xyz/dashboard/log-in-user-profile).
Here you specify which fields you want to collect. For each field, you can select whether it is optional or mandatory.
Save, and you're all set!
## Pre-signup
You will want to programmatically create a user in Dynamic and attach this information to them. You can do both steps at the same time, or you can do one after the other.
Make an API call to [the users endpoint](https://docs.dynamic.xyz/api-reference/users/creates-a-new-user) with some form of identifier for the user, and with or without the information you want to capture.
```
curl -X POST https://app.dynamicauth.com/api/v0/environments/{environmentId}/users \
-H "Authorization: Bearer $DYNAMIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "username": "testuser"}'
```
You can now update that user object with more information when you want to, utilizing the [update user endpoint](https://docs.dynamic.xyz/api-reference/users/updates-a-user):
```
curl -X PUT https://app.dynamicauth.com/api/v0/environments/{environmentId}/users/USER_ID_HERE \
-H "Authorization: Bearer $DYNAMIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"firstName": "My", "lastName": "Name"}'
```
Now, when the user actually signs up using that same email, we can give the user object a verified credential, and they will be able to see the information you captured on their profile.
## During Signup
Once you have enabled the fields you want to collect, the user will automatically be prompted to enter the information during signup!
## Post-signup
If fields are mandatory, they cannot be skipped during onboarding and the user will be prompted to enter the information. However, if you have only optional fields, you can skip them during onboarding and prompt for them at a time of your choosing.
Then, if you want to prompt the user to enter the information at a later time, you can do so by calling the `updateuserwithmodal` method from the [`useuserupdaterequest` hook](/react-sdk/hooks/useuserupdaterequest#function-updateuserwithmodal). This will trigger the UI for info capture.
## FAQ
Q. What happens with your current users if you change the settings?
A. No big deal. If you make certain fields required, then the next time a user connects to your application, we'll ask them to enter the field that you just made mandatory. That way, your users will stay up to date with the fields that you need.
# Social Linking
Source: https://docs.dynamic.xyz/users/social-linking
Dynamic supports linking social accounts from Apple, Discord, Facebook, Farcaster, Github, Google, Telegram, Twitch and Twitter!
You can do this by going to the Information Capture section of the dashboard and toggling on Social Account Linking.
It will then prompt you you to configure a social provider, and you can find the guides for each one in [the social providers section.](/social-providers/overview)
# Verified Credentials
Source: https://docs.dynamic.xyz/users/verified-credential
## Introduction
In the physical world, we as people have numerous ways of identifying ourselves (a passport, driving license or birth certificate for example). They are each used in different contexts, and can have different fields of information but they are share one defining characteristic, they are accepted as proof of identity and are called "physical credentials".
We have exactly the same need in the digital world and for this reason, the concept of ["verified credentials"](https://en.wikipedia.org/wiki/Verifiable_credentials) were created. A Verified Credential (VC) is a way to represent a digital identity in a way that can be shared and verified by others. They can be digital representations of physical credentials (like a passport) or they can be entirely digital (like an email address).
Specific to Dynamic, verified credentials can map to things like oauth (i.e. Facebook and Google), email, blockchain wallets, passkeys and more (these are called "formats"). Each format has its own set of fields and information that can be shared. They also always have a "provider" which is the service that issued the credential (i.e. Google, Apple, Dynamic).
## Accessing Verified Credentials
As you probably already read in the [accessing users](/users/accessing-users) section, you can access verified credentials as part of the user profile, so once you have that it is as simple as accessing the `verifiedCredentials` array.
```javascript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const { user } = useDynamicContext();
const verifiedCredentialsArray = user?.verifiedCredentials;
```
## Verified Credential Structure
### Fields Applicable to All VCs
| Field | Description |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | Internal ID for this VC |
| format: JwtVerifiedCredentialFormatEnum | \[Optional] - Type of VC, e.g., email. See [JwtVerifiedCredentialFormatEnum](/users/verified-credential#jwtverifiedcredentialformatenum) for more details. |
| publicIdentifier? | \[Optional] - Common way to reference the VC, e.g., email address for email VCs or the name of a user for Google VC. |
| email? | \[Optional] - Email associated with the VC. |
### Fields Specific to OAuth
| Field | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| oauthProvider? | \[Optional] - Social provider associated with the VC, e.g., Apple. See [ProviderEnum](/users/verified-credential#providerenum) for more details. |
| oauthAccountId? | \[Optional] - ID associated with the social provider for the VC. |
| oauthDisplayName? | \[Optional] - Display name associated with the social provider for the VC. |
| oauthUsername? | \[Optional] - Username associated with the social provider for the VC. |
| oauthEmails? | \[Optional] - Emails associated with the social provider for the VC. |
| oauthAccountPhotos? | \[Optional] - Photos associated with the social provider for the VC. |
| refId? | \[Optional] - If using OAuth, this is the embedded wallet ID associated with the social account. |
| previousUsers? | \[Optional] - User IDs who were previously associated with the VC. |
### Fields Specific to Wallets
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| walletName? | \[Optional] - Wallet name associated with the VC. |
| address? | \[Optional] - Wallet address associated with the VC. |
| chain? | \[Optional] - Chain associated with the VC. |
| walletProvider? | \[Optional] - Type of wallet. See [WalletProviderEnum](/users/verified-credential#walletproviderenum) for more details. |
| walletProperties? | \[Optional] - Generally only used for embedded wallets with Turnkey. See [WalletProperties](/users/verified-credential#walletproperties) for more details. |
| embeddedWalletId? | \[Optional] - ID of the embedded wallet associated with the VC. |
| nameService? | \[Optional] - ENS data name and avatar URL, if one is associated with the wallet in the VC. See [NameServiceData](/users/verified-credential#nameservicedata) for more details. |
| signerRefId? | \[Optional] - For smart contract wallets, this is the wallet ID of the signer for the SCW. |
### NameServiceData
| Field | Description |
| --------------- | -------------------------------------------- |
| avatar?: string | \[Optional] - avatar associated with the ens |
| name?: string | \[Optional] - name associated with the ens |
### WalletProviderEnum
'browserExtension' || 'custodialService' || 'walletConnect' || 'qrCode' || 'deepLink' || 'embeddedWallet' || 'smartContractWallet'
### WalletProperties
| Field | Description |
| --------------------------------- | ------------------------------------------------------------------ |
| turnkeySubOrganizationId?: string | \[Optional] - turnkey sub organization ID associated with wallet |
| turnkeyHDWalletId?: string | \[Optional] - turnkey HD wallet ID associated with the the wallet |
| isAuthenticatorAttached?: boolean | \[Optional] - is authenticator i.e. passkey attached to the wallet |
### JwtVerifiedCredentialFormatEnum
'blockchain' || 'email' || 'oauth' || 'passkey'
### ProviderEnum
'emailOnly' || 'magicLink' || 'apple' || 'bitbucket' || 'discord' || 'facebook' || 'github' || 'gitlab' || 'google' || 'instagram' || 'linkedin' || 'microsoft' || 'twitch' || 'twitter' || 'blocto' || 'banxa' || 'dynamic' || 'alchemy' || 'zerodev' || 'turnkey'
# Integrate your Chain
Source: https://docs.dynamic.xyz/wallets-and-chains/chains
We're excited about the possibility of supporting your chain on Dynamic! We're always looking to expand our ecosystem and provide developers with more options. If you'd like us to consider adding support for your chain, please submit your information using the form below. Our team will review your submission and reach out to learn more about your chain and explore potential integration.
# Integrate your Wallet
Source: https://docs.dynamic.xyz/wallets-and-chains/wallets
## Overview
If you're a wallet looking to integrate with Dynamic, you're in the right place. We support multiple wallet standards, and if you implement one of these standards, we can quickly add you to our list of supported wallets.
After implementing one of these standards below, reach out via the form below to get allowlisted.
## EVM
### WalletConnect Protocol
[WalletConnect Protocol](https://walletconnect.com/) is an open protocol that enables secure communication between wallets and dApps. It supports a wide range of wallets across multiple chains, including MetaMask, Rainbow, and other EVM-compatible wallets.
### ERC-6963
[ERC-6963](https://eips.ethereum.org/EIPS/eip-6963) is a standard for wallet discovery and connection for browser extension wallets. It aims to improve the user experience by allowing dApps to detect and interact with multiple installed wallets at the same time. MetaMask, Coinbase Wallet and Rainbow are some of the wallets that support this standard.
### Mobile Wallet Protocol
The Mobile Wallet Protocol is designed for seamless integration between mobile wallets and dApps and is led by Coinbase. You can find more information on the protocol [here](https://github.com/MobileWalletProtocol/wallet-mobile-sdk).
### Smart Wallets (ERC-1271 and ERC-6492)
Smart wallets are contract-based wallets that offer advanced features like account abstraction. If you're a smart wallet looking to integrate with Dynamic, note that we support both [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) (Standard Signature Validation Method for Contracts) and [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492) (Signature Validation for Predeploy Contracts).
## Solana
### Solana Wallet Standard
The [Solana Wallet Standard](https://github.com/solana-labs/wallet-standard) is a specification for Solana wallets to interact with dApps. It supports wallets such as Phantom, Solflare, and other Solana-compatible wallets.
### WalletConnect Protocol
WalletConnect Protocol also supports Solana wallets, enabling cross-chain compatibility.
## Bitcoin
### Bitcoin Wallet Standard
The [Bitcoin Wallet Standard](https://github.com/ExodusMovement/bitcoin-wallet-standard) is an emerging specification for Bitcoin wallets to interact with web applications. Wallets such as Exudus, Phantom and Magic Eden support this protocol.
### Sats Connect
[Sats Connect](https://docs.xverse.app/sats-connect) is a protocol for connecting Bitcoin wallets to web applications. Xverse, Hiro, and other Bitcoin wallets implement this standard
## Custom Wallet Connectors
Dynamic now offers developers the ability to add their own custom wallet connectors to the Dynamic SDK. This feature allows for greater flexibility and customization in integrating wallets that may not follow standard protocols or have unique requirements.
To create a custom wallet connector:
1. Visit the [Dynamic Public Wallet Connectors repository](https://github.com/dynamic-labs/public-wallet-connectors) on GitHub.
2. Follow the guidelines in the [CONTRIBUTING.md](https://github.com/dynamic-labs/public-wallet-connectors/blob/main/CONTRIBUTING.md) file to understand the process of creating and submitting a custom connector.
3. For an example of a custom connector implementation, you can refer to the [Safe connector](https://github.com/dynamic-labs/public-wallet-connectors/blob/main/packages/@dynamic-labs-connectors/safe-evm/README.md).
By creating a custom wallet connector, you can ensure that your wallet integrates seamlessly with the Dynamic SDK, providing a smooth experience for users of your wallet and applications using Dynamic.
## Submit your wallet
Ready to add your wallet to Dynamic or need us to make changes to a current wallet's name or logo? Fill out our form below and we'll get back to you shortly.
# External Wallets Overview
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/branded-wallets-overview
External wallets are a way to let users sign up and log in to your application using their own wallet, such as MetaMask. This is opposed to embedded wallets, where the wallet is created and managed by Dynamic on signup or after.
Branded wallets and embedded wallets are completely compatible, a user can start with an embedded wallet and also link their branded wallet, or vice versa.
We cover enabling signup/login with branded wallets in the [authentication methods section](/authentication-methods/branded-wallets), and assume if you're reading this section that you've already enabled the appropriate chains and configured RPC URLs.
This section details the more advanced areas of branded wallets, such as:
* [Connect vs Authenticate modes](/wallets/advanced-wallets/connected-vs-authenticated)
* [Allowing multiple wallet connections](/wallets/advanced-wallets/multi-wallet)
* [Recommending certain wallets at signup](/wallets/advanced-wallets/recommend-wallets)
* [Blocking risky wallet addresses with Chainalysis](/wallets/advanced-wallets/chainalysis)
# Block Addresses With Chainalysis
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/chainalysis
#### Summary
The Chainalysis integration allows for blocking certain wallet addresses based on their association with sanctioned lists or risky categories. Today, you can enable this integration with a simple toggle in your dashboard.
### 📘 Let us know if you want the Address Screening API
Today, we have an integration with the free sanctions API. If you want us to add the address screening API, let us know through [slack or email](/introduction/welcome#support-and-feedback).
#### Usage
1. Enable the Chainalysis integration in your developer dashboard by going to the [Configurations tab](https://app.dynamic.xyz/dashboard/configurations).
2. Use the free sanctions API to block wallet addresses associated with sanctioned lists or use the paid address screening API for additional risky category screening.
3. View the results of the screening for any given user, go to the Users table and click on their row. Here you will see a "Pass" or "Fail" status.
4. If a wallet address fails the screening, the user will see the "sad path" message reflected in the SDK, with a header "This address is not approved for access", secondary text "This wallet has been correlated to illicit activity and cannot be used to access this site."
# Coinbase Smart Wallet
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/coinbase-smart-wallet
### Introduction
Coinbase Smart Wallets lets your users easily onboard and create wallet accounts without the need for a browser extension or mobile app. You can see a walkthrough of the feature and use with Dynamic below:
You can see the Coinbase Smart wallet in action in our demo environment by clicking on Coinbase.
### Integration Steps
#### Initial Setup
To set up Coinbase Smart Wallet, simply upgrade to our latest SDK (v2.2+), ensure [you have wallet login set up](/authentication-methods/branded-wallets), and [a network compatible with Coinbase Smart Wallet enabled](/chains/enabling-chains#enabling-a-chain-network), then we'll do the rest!
* Base
* Arbitrum
* Optimism
* Zora
* Polygon
* BNB
* Avalanche
* ETH mainnet (not preferred for use, due to gas cost)
#### Recommend Coinbase Smart Wallet
Dynamic gives you the ability to [recommend wallets](/wallets/advanced-wallets/recommend-wallets) by making them stick to the top of the wallet list, whether or not they are installed.
You can easily recommend Coinbase Smart Wallet by adding the following to your DynamicContext settings:
```Typescript
```
#### Coinbase SW + New To Web3
The Dynamic provided UI components include a [New to Web3 help section](/wallets/advanced-wallets/recommend-wallets#new-to-web3-section) as part of the DynamicWidget, where we show a common wallet for users to get started for each chain.
You can easily recommend Coinbase Smart Wallet by adding the following to your DynamicContext settings:
```Typescript
```
### How it works
### Overview
Each wallet is created as a smart contract wallet (ERC-4337), and is secured by a user added Passkey, which is tied to the domain "keys.coinbase.com".
Because the passkey is scoped to Coinbase's domain, the wallets will work securely across any site that integrates with Coinbase Smart Wallet.
This is a huge unlock for the ecosystem, as it allows users to have a seamless experience across multiple sites, without any extra lift.
Since the wallet is actually an ERC-4337 compliant smart contract, you can also make use of batch transactions and app-defined paymasters which are supported by the Coinbase Smart Wallet.
Lastly, the wallet is integrated with [Magic Spend](https://www.smartwallet.dev/why#magic-spend) by default, allowing for seamless onramping of funds into the newly created wallet.
### Signing
The user signs with their passkey, and a function named `isValidSignature` is subsequently called on their Smart Wallet in order to verify that signature ([based on EIP-1271](https://eips.ethereum.org/EIPS/eip-1271)).
Since the user's passkey is an owner on the Smart Wallet's contract, it would return that the signature is valid and the transaction can be processed from there. However, what happens if the smart acccount has not yet been deployed?
A Smart Wallet is not deployed on a chain until the first transaction on that chain, so there must be a method of handling the signing of an initial transaction offchain. This is done by adopting the solutions outlined in [EIP-6492](https://eips.ethereum.org/EIPS/eip-6492).
### What's Next
We're excited to support the move of Coinbase Smart Wallet to mainnet in the coming weeks. With incredible features such as [Magic Spend](https://www.smartwallet.dev/guides/magic-spend) and [Batch Transactions](https://www.smartwallet.dev/guides/batch-transactions), we see a future of even simpler new user onboarding. Learn more in our deeper blog post on [Coinbase Smart Wallet](https://www.dynamic.xyz/blog/test-drive-coinbases-smart-wallet-today).
### Get up to \$20k in paymaster credits
Utilizing Coinbase Smart Wallets or AA accounts on @base with Dynamic?
We teamed up with @coinbasewallet to kick it up a notch 💙
You may be eligible for up to \$20K in gas credits: \$15K from the Smart Wallet Gas Program + \$5K just for being a Dynamic customer.
Fill out this form to indicate that you are building with Dynamic and get credits: [apply now](https://docs.google.com/forms/d/1yPnBFW0bVUNLUN_w3ctCqYM9sjdIQO3Typ53KXlsS5g/viewform?edit_requested=true)
# Configure Connect Only Mode
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/connect
### Setup
By default, the SDK will authenticate all users which means users will need to
sign when logging in. This page describes how you can remove the authentication
step and allow users to just connect their wallets to log into your site.
### Usage
#### initialAuthenticationMode (optional)
If you want to skip signing a message and just connect, then set the
`initialAuthenticationMode` to `connect-only`.
```js TypeScript
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
{...}
```
#### enableVisitTrackingOnConnectOnly (optional)
If you are using the `connect-only` mode, then you also have the option to
disable visitor tracking by setting `enableVisitTrackingOnConnectOnly` to false.
If you set this to `false` then we will not track visitors. Note that you will
not be able to see visitor information in our visitors table or analytics page.
```js TypeScript
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
{...}
```
### useIsLoggedIn
The [useIsLoggedIn](/react-sdk/hooks/useisloggedin#useisloggedin) hook determines whether a user is logged in or not by returning a boolean value you can use to determine if the user has connected their wallets. The hook needs to be initialized within a child of [DynamicContextProvider](/react-sdk/providers/dynamiccontextprovider).
#### User Management & Analytics
Any user who connect, but does not authenticate, will appear in your dashboard
as a `Visitor`. You'll be able to see them in your
[user management table](https://app.dynamic.xyz/dashboard/users/visitors) or in
[analytics](https://app.dynamic.xyz/dashboard/analytics) under as `Visitors`.
# Configure Authenticate Mode
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/connect-and-sign
### Setup
By default, we will authenticate users which means users will need to sign on
every connection. This means, that you don't need to set any prop to
automatically authenticate users.
That being said, you can explicitly control the settings using the
`initialAuthenticationMode` prop and setting the value to `connect-and-sign`.
#### initialAuthenticationMode (optional)
```js TypeScript
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
{...}
```
### Usage
#### useAuthenticateConnectedUser
If you elect to avoid authentication initially by using `connect-only`, but at
some point you want to authenticate your connected users (ie, prove ownership of
the wallet), then you can call `authenticateUser` to trigger a sign request.
You can check the boolean `isAuthenticating` to check on the status of a user
that is authenticating which will be either `true` or `false`.
```ts TypeScript
import { useAuthenticateConnectedUser, useDynamicContext } from "@dynamic-labs/sdk-react-core";
const Element = () => {
const { user } = useDynamicContext();
const { authenticateUser, isAuthenticating } = useAuthenticateConnectedUser();
if (!user) {
return (
;
)
}
return 
# Connected vs Authenticated
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/connected-vs-authenticated
## Definitions
When using Dynamic, one of the first things you'll need to decide is whether you want to have users sign to prove ownership of their wallets or if you just want them to connect their wallets.
As we talk about these two options, you'll regularly see that we either discuss a `visitor` or an `authenticated user` in our documents and dashboard. In short, here are there definitions:
* `Visitor` is a user that connects their wallet to your dApp but has not yet signed to prove ownership of that wallet.
* You can identify a visitor as having a `primaryWallet` but user is not defined.
* `Authenticated User` is a user that connects their wallet and has signed to prove ownership.
* You can identify an authenticated user since the `user` object will be defined.
* A JWT is returned for an authenticated user
For example, here we log in a user whether they are connected or authenticated. We check for either a primary wallet or a user being defined.
```typescript
import { useDynamicContext } from "@dynamic-labs/sdk-react-core"; //later you will read about dynamicContext
const HomePage = () => {
const { primaryWallet, user } = useDynamicContext();
if (primaryWallet !== null || user) {
return (
Note: We base the default message on the standard SIWE format.
If you would like to update this message and customize it for your users, you
simply need to update this message by passing in the prop `siweStatement` and
your custom message:
```tsx
```
# Multiple Wallet Connections (Multi-Wallet)
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/multi-wallet
### Summary
Lots of users have multiple wallets but managing multiple wallets and multiple
accounts for each wallet is challenging. You have to manage event listeners,
various connection states, wallets shared across accounts, and much much more.
If you want to learn more about our multi-wallet solution, check out our
[blog post](https://www.dynamic.xyz/blog/multi-wallet-announcement).
Our multiwallet widget allows your users to easily:
1. Add multiple wallets
2. Add multiple accounts from the same wallet
3. Transfer wallets between accounts
4. It is mobile friendly
5. Keep track of the active account in a wallet
6. Swap primary wallets
7. and so much more.
To simplify management of these scenarios and the resulting edge cases, we've
released a widget that does it for you. You can see it in action on our
[demo site](https://demo.dynamic.xyz).
### Setup
To enable multiwallet, simply visit [the Log in & User Profile section of the dashboard](https://app.dynamic.xyz/dashboard/log-in-user-profile) and toggle it on in the "Branded Wallets" section.
### How it works
#### Connect-only
When a user initially connects an additional wallet, they go through the normal wallet connection flow.
Once connected, the wallet is added to the Wallets list and the user can switch between wallets as needed.
If the user manually disconnects a wallet from the extension/app, the wallet gets removed from the Wallets list (unless the no disconnect event is emitted by the wallet extension/app).
If the user manually disconnects their primary wallet, they get logged out.
If a wallet gets disconnected while the user is not in the app using Dynamic (or we don't detect any disconnect events), the wallet will remain in the Wallets list, and once the user tries to take any action with it (e.g. send a transaction), we'll check the state and prompt them to re-connect.
When a user connects a wallet, they cannot connect another wallet from the same provider through the widget. However, if they switch account in the wallet extension/app while in the app that is using Dynamic, we'll detect this account change and automatically switch the previously connected wallet to the new one (unless no accountChange event is emitted by the wallet extension/app).
Example:
If the user initially connects with MetaMask account 1, they cannot connect another MetaMask account. However, it they switch to MetaMask account 2, that will be the account connected to Dynamic and the address that they'll see in the widget, not account 1 anymore.
#### Connect-and-sign
When a user initially links an additional wallet, they go through the normal wallet connection flow i.e. connect and sign a message.
Once connected, the wallet is added to the user's profile and they can switch between wallets as needed.
When unused, we do not keep track of the wallets states once they are linked, meaning the user can lock their wallets, change accounts and so on. This avoids extra friction for the user, as the wallets are not in use at that time, and that that matters is that they have a valid JWT.
However, once the user is ready to take action using a linked wallet, we check the state and can prompt them to unlock, change back to the connected account etc.
### Headless Multi-Wallet
Multi-wallet functionality comes bundled as part of the user profile, and we have a guide to achieve every aspect of this in a headless manner [here](/headless/headless-user-profile).
# Recommend Wallets at Signup
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/recommend-wallets
There are two different kinds of wallet recommentdations that you can configure. The first is for a user who might already have a wallet, but you want to recommend a specific wallet to them, to learn about this, continue to [the General Wallet List section](/wallets/advanced-wallets/recommend-wallets#general-wallet-list). The second is for a user who is new to Web3 and doesn't have a wallet at all, to learn about this you can skip to [the New to Web3 section](/wallets/advanced-wallets/recommend-wallets#new-to-web3-section).
## General Wallet List
You can now specify recommended wallets that stick to the top of the wallet list, whether or not they are installed.
To do so, we added a new prop `recommendedWallet` to the DynamicContext settings which is an array of:
```JSON
{
"walletKey": "phantomevm",
// label: freeform string input for the tag label. If not specified, defaults to "Recommended"
"label": "Popular"
}
```
You can find the valid wallet keys in the chain configuration section of the
dashoard. For example,
[here](https://app.dynamic.xyz/dashboard/chains-and-networks#evm) is the EVM
section that lists all the wallets and their keys.
```Typescript
```
If you would like to customize the background and text color for the recommended tag, please refer to the [CSS variable guide](/design-customizations/css/css-variables):
```
--dynamic-badge-primary-background: #4779FF;
--dynamic-badge-primary-color: #fff;
```
***
## New To Web3 Section
In our New to Web3 help section in our SDK, we show a common wallet for users to get started for each chain. For now, if you have enabled more than 1 chain, then we will show only 1 chain and 1 wallet.
To change the default wallet shown in this this section, you can pass a prop `newToWeb3WallChainMap` to specify the primary chain (this is to support multi-chain) and then specify the wallet with the corresponding chain.
```Typescript
```
For customers supporting multiple chains, you can also specify which chain you prefer to be primary which will then recommend the wallet aligned with that chain. You **don't** need to specify a wallet unless you want to override the current default wallet for that chain.
```TypeScript
```
# Sort and Filter Wallets
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/sort-and-filter-wallets
### Summary
There are a few helper methods you can leverage to sort, filter, remove, or filter and sort wallets. You can call the methods from within the `walletsFilter` prop.
The helper methods are:
1. FilterWallets
2. RemoveWallets
3. SortWallets
4. FilterAndSortWallets
5. BYOF (Bring your own function)
### Wallet Type
You can see the fields of the wallet that you'll be able to access when building your filter function in the [WalletOption](/react-sdk/objects/wallet-option) object.
Note that if you need to check if the wallet is installed on the browser, you can use the `isInstalledOnBrowser` field, while if you want to check if it's the most recently used wallet, you should check if a value for the key `dynamic_last_used_wallet` is present in local storage, and then match against the key field of the wallets.
### Setup
#### walletsFilter (optional)
To filter and sort wallets, you'll want to use the `walletsFilter` prop under settings. You will then use either the one of the helper methods or BYOF to organize your wallet list.
```TypeScript
import { DynamicContextProvider, DynamicWidget, FilterWallets } from '@dynamic-labs/sdk-react-core';
....
```
### Usage
For all examples we mention here, make sure you have the chains enabled in [the dashboard](https://app.dynamic.xyz/dashboard/chains-and-networks) and that you have used [the appropriate walletConnectors](https://docs.dynamic.xyz/react-sdk/wallet-connectors) in the DynamicContextProvider.
#### FilterWallets
If you would like to filter out all wallets except for a predefined list, then call the FilterWallets method and include the wallets that you want your users to use:
```TypeScript
import { DynamicContextProvider, DynamicWidget, FilterWallets } from '@dynamic-labs/sdk-react-core';
```
#### SortWallets
The Dynamic SDK has a predefined sorted list of wallets. If you want to change the wallet list to a different ordered list, add a sorted array of the wallets that you want to appear first.
The rest of the wallets will keep their current order.
```jsx
import { DynamicContextProvider, DynamicWidget, SortWallets } from '@dynamic-labs/sdk-react-core';
```
#### FilterAndSortWallets
If you would like to combine the previous two options, then you can use the FilterAndSortWallets method to define the wallets that you want to appear in a specific order.
```jsx
import { DynamicContextProvider, DynamicWidget, FilterAndSortWallets } from '@dynamic-labs/sdk-react-core';
....
```
#### RemoveWallets
If you want to remove specific wallets from the available list of wallets, you can call the RemoveWallets and specify which wallets you don't want your users to use:
```jsx
import { DynamicContextProvider, DynamicWidget, RemoveWallets } from '@dynamic-labs/sdk-react-core';
....
```
#### FilterChain
If you want to filter out wallets based on whether they support a chain, then you can call FilterChain and specify the chain you want the wallets to support.
```TypeScript
import { DynamicContextProvider, FilterChain } from '@dynamic-labs/sdk-react-core';
```
#### BYOF (Bring Your Own Function)
If the above helper methods are not sufficient, you can design your own function and pass it to walletFilter.
```jsx
{
return wallets.filter((wallet) => {
return ['wallet1', 'wallet2'].includes(wallet.key)
});
},
}}
>
```
#### Combine multiple filters
You can use the `pipe` function to combine multiple operations to create your wallets filter.
For example, filters by chain, remove wallets and sort.
```TypeScript
import { DynamicContextProvider, FilterChain } from '@dynamic-labs/sdk-react-core';
import { pipe } from '@dynamic-labs/utils';
```
#### Fetch standardized wallet options keys
To find the key of all the wallets options you can output all the keys using the following syntax:
```jsx
import { useWalletOptions } from ‘@dynamic-labs/sdk-react-core’;
const { walletOptions } = useWalletOptions();
console.log(walletOptions.map((wallet) => wallet.key));
```
#### Wallet list tabs
To configure multiple wallet filters, you can use the [wallet list tabs feature](/react-sdk/objects/views#wallet-list) to define different tabs for users to select.
# TOS & Privacy Policy
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/tos-privacy-policy
## Overview
Displaying your Terms of Service and Privacy Policy are an important step of customer onboarding. We give you the flexibility to display those two documents in our SDK or you can hide the links and display them somewhere else in your site.
## Display as a sentence
#### privacyPolicyUrl (optional) & termsOfServiceUrl (optional)
We currently display the Terms of Service and Privacy Policy during the connecting step of the SDK.
If you want to update the links, then you can do so by updating the props in settings.
```TypeScript
```
#### Hiding the Terms of Service and Privacy Policy Copy
If you don't want to display this text, then you can instead hide the sentence with:
```TypeScript
```
## Display as a checkbox
As an alternative to displaying the Terms of Service and Privacy Policy as a sentence, you can display a checkbox that the user must check in order to proceed. To do so, turn on TOS and PP in the login methods section under information capture. After that, you can display the checkbox component like so:
Note: this will display the TOS and PP in a page post login as part of the user's onboarding flow.
```TypeScript
)
}}
>
{children}
```
# Architecture & Security
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/architecture-security
## Authentication and JWT
End users must be logged in and issued a JWT by Dynamic's backend API to create and use embedded wallets. This JWT acts as an authentication token allowing the browser to identify a logged in user to the backend. The JWT is signed by a private key that is stored encrypted using our KMS. A developer could validate Dynamic's JWT using a standard JWKS endpoint to retrieve the public key. Unauthenticated requests or requests with an invalid JWT for creating or accessing an embedded wallet will be rejected by the Dynamic API.
## Wallet private key storage
All private keys are encrypted, and never stored in raw form. End user private keys are not accessible to Dynamic, the developer, or the key management service. All decryption functions to use private keys must be user-initiated and done so in secure enclaves (i.e Trusted Execution Environments).
Dynamic does not sign transactions on a end-user’s behalf, and end-users have to take explicit actions to sign transactions. Dynamic also does not offer APIs to sign transactions for end-users.
## Iframes
For data that must never be exposed except to the end-user i.e. private keys, it is sent encrypted through an API call to an iframe in the end-users browser, and only decrypted on the client device. This ensures that at all times, no-one but the end-user will ever be able to access that data, and only on their own device.
## Recovery of Wallets
Recovering a wallet is tied to the authentication method enabled by the application developer. For example, if an application developer allows login with email, the user can always recover their wallet by having access to their email. They can use standard email recovery procedures from their email client to support regaining access.
Adding additional recovery options through other authentication methods.
Dynamic allows users to link other verified credentials to their account such as phone number, Google or other Social Media login methods. If users have multiple credentials assigned, they can be used to recover their wallet if a single method is lost.
Retrieving Wallet Key if Dynamic or Application Developer are down. (Coming soon)
Dynamic will be adding additional fall back support in case an application developer or Dynamic services are down. A custom URL will be available so end-users can log in and export their private key.
## Trusted Execution Environments (AWS Nitro Enclaves)
A core component of Dynamic-powered embedded wallets is the isolation of any sensitive key material or credentials. All sensitive operations that involve an embedded wallet’s private key occur within secure AWS nitro enclaves.
Additionally, token private keys never exist outside of the AWS secure enclave unencrypted. There is no avenue of unilateral access to the secure enclave from any employee of Dynamic, nor our KMS.
## Sessions, Signatures, Transactions
By default, Dynamic allows the end user to use session keys to authenticate and interact with their wallets.
Session keys are implemented by creating api keys in the developer website and registering those as valid authentication methods within a secure enclave. Those session keys are retained by the end user on the developer website and are never sent to Dynamic.
Session key registration requires a valid Dynamic JWT, which is obtained via a successful user authentication. Once the session keys expire, they can no longer be used to authenticate into a Dynamic-powered embedded wallet. If you are using our SDK, session keys are automatically refreshed when expired as long as the JWT is valid
Transactions requests are signed by the end user’s wallet authenticator and validated by our KMS. Upon successful validation, the end user’s private keys are used to sign the actual transaction within the KMS’s secure enclave.
Note that for added account level security, you can [enforce TOTP using an authenticator app](/authentication-methods/mfa).
# Creating Embedded Wallets
Source: https://docs.dynamic.xyz/wallets/embedded-wallets/create-embedded-wallets
No matter how your user signs up, whether it's using social login i.e. Telegram, email/phone login or even with a branded wallet i.e. Metamask, you can create an embedded wallet for them using Dynamic. Simply decide when you want this wallet created and follow the guides below.
{isProviderLinked ? (
{connectedAccountInfo?.publicIdentifier ?? provider}
{enabled && (
)}
)
}
```
### Networks
#### Display current and available networks
How: Use evmNetworks and getNetwork to fetch, use supportsNetworkSwitching and switchNetwork to switch
Hook/Component: [useDynamicContext](/react-sdk/hooks/usedynamiccontext) & [getNetwork](/react-sdk/utilities/getnetwork)
Notes: This example is for Evm networks only
```jsx
import { useDynamicContext, getNetwork } from '@dynamic-labs/sdk-react-core'
const CustomNetworkPicker = () => {
const [currentNetwork, setCurrentNetwork] = useState(null)
const { primaryWallet } = useDynamicContext()
const handleNetworkChange = async (event) => {
const chainId = parseInt(event.target.value)
if (primaryWallet?.connector?.supportsNetworkSwitching()) {
try {
return await primaryWallet?.connector?.switchNetwork({
networkChainId: chainId,
})
} catch (error) {
console.error('Error switching network', error)
}
}
}
useEffect(() => {
if (!currentNetwork)
getNetwork(primaryWallet?.connector).then((network) => {
setCurrentNetwork(network)
})
}, [primaryWallet])
return (
<>
{currentNetwork && (
)}
)
}
```
### Primary Wallet
Primary wallet is the wallet that is defined as the active one of all your connected wallets. All interactions, such as signing or creating transactions, will be made with this wallet. In addition, when leveraging our multiasset functionality, this is the wallet that will be display all available tokens.
#### Display primary wallet address
How: Fetch the primary wallet info from context
Hook/Component: [useDynamicContext](/react-sdk/hooks/usedynamiccontext)
Notes: There can be a moment after logging in when it’s not populated yet
```jsx
import { useDynamicContext } from '@dynamic-labs/sdk-react-core'
const { primaryWallet } = useDynamicContext()
const copyWalletAddress = () => {
navigator.clipboard.writeText(primaryWallet?.address)
}
return (
)
```
#### Display primary wallet icon
How: Utilize the Walletbook library
Hook/Component: WalletIcon (not publicly documented yet)
Notes: Requires the primaryWallet.connector object.
```jsx
import { primaryWallet } from '@dynamic-labs/sdk-react-core'
import { WalletIcon } from '@dynamic-labs/wallet-book'
const WalletIconWrapped = ({ connector }) => {
return (
{balance}
``` #### Show all tokens and balances How: Mapping return from usetokenbalances hook Hook/Component: [https://docs.dynamic.xyz/react-sdk/hooks/usetokenbalances](https://docs.dynamic.xyz/react-sdk/hooks/usetokenbalances) Notes: Multi-asset is only supported on the following networks - Ethereum, Optimism, Polygon, Arbitrum, and Base. ```jsx import { useTokenBalances } from '@dynamic-labs/sdk-react-core' const TokenBalances = () => { const tokenBalances = useTokenBalances() return (
{tokenBalances.map((token) => (
))}
)
}
```
#### Detect Wallet Locking
The wallet object has a field called `connected` which indicates whether the wallet is locked or not, and you can use this to trigger your own workflow to warn the user.
### Multi-Wallet
#### Show all linked wallets and allow unlinking
How: Mapping return from useUserWallets hook and handleUnlinkWallet from useDynamicContext
Hook/Component: [https://docs.dynamic.xyz/react-sdk/hooks/useuserwallets](https://docs.dynamic.xyz/react-sdk/hooks/useuserwallets) & [https://docs.dynamic.xyz/react-sdk/hooks/usedynamiccontext](https://docs.dynamic.xyz/react-sdk/hooks/usedynamiccontext)
Notes: Doesn’t yet show if a wallet is the primary wallet. Unlinking is also handled here.
```jsx
import { useDynamicContext, useUserWallets } from '@dynamic-labs/sdk-react-core'
import { Tooltip } from 'react-tooltip'
const LinkedWallets = () => {
const { handleUnlinkWallet } = useDynamicContext()
const userWallets = useUserWallets()
return (
<>
{userWallets.length > 0 && (
)}
)
}
```
#### Detect which wallet is primary
How: You can grab it directly from useDynamicContext
Hook/Component: [useDynamicContext](/react-sdk/hooks/usedynamiccontext)
```jsx
import { useDynamicContext, useUserWallets } from '@dynamic-labs/sdk-react-core'
const { primaryWallet } = useDynamicContext()
console.log(primaryWallet)
```
#### Allow user to link a new wallet
How: Pop up our linking modal using a hook (setShowLinkNewWalletModal)
Hook/Component: [useDynamicModals](/react-sdk/hooks/usedynamicmodals)
Notes:
* You will need to also use the DynamicMultiWalletPromptsWidget component
```jsx
import {
useDynamicModals,
DynamicMultiWalletPromptsWidget,
} from '@dynamic-labs/sdk-react-core'
const LinkWallet = ({ text }) => {
const { setShowLinkNewWalletModal } = useDynamicModals()
return (
<>
{token.symbol}
{token.balance}
{userWallets.map((wallet) => (
))}
)
}
```
## Wallet Interactions
To learn how to send balance, sign messages etc., please check out [the Wallet Interaction guides](/wallets/using-wallets/interacting-with-wallets) where we split into Read actions and Write actions, and we provide per chain examples for common functionality.
# How do I...
Source: https://docs.dynamic.xyz/how-do-i
This section covers common FAQ's and how to solve them.
### How do I ensure all the wallets I expect are shown in the widget?
1. Ensure you have enabled the chains in the dashboard.
It can sometimes happen that you missed enabling a chain in the dashboard, or did it for a different environment than the one you are testing in. Check [the chains and networks tab](https://app.dynamic.xyz/dashboard/chains-and-networks) to be sure.
2. Ensure you have enabled the wallet connectors for the chains you want to show.
Double check that you have added [the right wallet connectors](https://docs.dynamic.xyz/react-sdk/providers/dynamiccontextprovider#walletconnectors) in your Dynamic Context Provider.
3. Ensure you are not encountering a CSP issue.
Check for any errors like "Refused to connect because it violates the document's Content Security Policy." in your console/networks tab, it means you need to add `dynamic-static-assets.com` to your server CSP.
### How do I add a new network?
[Add a custom EVM network](/chains/evmNetwork#custom-evm-networks).
[Add a custom Solana network](/chains/solNetwork#custom-svm-networks).
[Add a custom Cosmos network](/chains/customCosmosNetwork#custom-cosmos-network).
### How do I set a custom RPC URL?
Set a custom RPC URL [in code](/chains/customRpcUrls), or in the Dynamic Dashboard (when you enable a network, there is a dropdown to set your own RPC URL).
### How do I control whether the user is redirected or opened in an in-app browser on mobile?
You can control how users connect on mobile devices using [the `mobileExperience` prop](/react-sdk/providers/dynamiccontextprovider#mobileexperience). You can set it globally or per wallet:
```jsx
// Global setting
## Migration Path A: You only have a front-end "connect wallet" flow
### Common scenarios
You built your own front end wallet connector or use Rainbowkit/ConnectKit. There is no SIWE, no issuing JWTs, and mostly just a front end.
### Recommended approach
You pretty much just swap out the modals. If you use wagmi, add our [wagmi connector](/react-sdk/using-wagmi#-install-wagmi) and follow our [rainbowkit guide](/migrations/tutorials/rainbowkit), but in general, no migration needed. After the initial update to the Dynamic modal, you can stay on our [connect-only mode](/wallets/advanced-wallets/connect) and not store any user info with Dynamic, or alternatively start adding more sophisticated features.
## Migration Path B: You store wallet info somewhere and a wallet is a user
### Common scenarios
You built your own front end wallet connector or use Rainbowkit/ConnectKit, and in addition implemented a SIWE on your own, authenticating users and creating sessions for them.
### Recommended approach
For front end changes, you can follow path A above. In addition, you can use our [create wallet](https://docs.dynamic.xyz/api-reference/wallets/createWallet) endpoint to generate users and add wallet records to them. When they first log in, they will verify wallet ownership via SIWE (we provide that and return a JWT - you don't need to do this), and you're done.
## Migration Path C: You have users, but no embedded wallets
### Common scenarios
You use Auth0, Firebase or another web2 user management system, or alternatively created something on your own. You store your users' emails and basic info.
### Recommended approach
You'll need to import your users into Dynamic
1. [Bulk upsert your users into Dynamic](https://docs.dynamic.xyz/api-reference/users/bulkCreateUser), including their info capture/kyc information and their data
2. For any profile information that Dynamic does not yet explicitly support, you can add these in the user.metadata, which is a key-value object
3. When they log in, we verify their emails
And that's it. You're done. When your users log in next time around, we will verify their email addresses/social login information independently as part of the auth flow, and issue a JWT once you have successfully logged in.
## Migration Path D: You have users, and they have embedded EOA wallets
### Common scenarios
You use an embedded wallets provider, or have built a simple KMS-based key management system on your own
### Recommended approach
**There are really two options here:**
1. Keep current users in their existing embedded wallets and generate Dynamic wallets for new users
2. Migrate existing wallet users to Dynamic
**Keep current users:**
1. Switch to Dynamic auth
2. When user logs in with email, check if they have an existing account:
* If so, redirect them to old login flow
* If they don't, create a Dynamic-powered embedded wallet for them
```typescript
import { useEmbeddedWallet } from "@dynamic-labs/sdk-react-core";
// component declaration and all other logic you might need
const { createEmbeddedWallet } = useEmbeddedWallet();
const onCreateWalletHandler = async () => {
try {
await createEmbeddedWallet();
} catch (e) {
console.error(e);
}
};
```
**Migrate users:**
1. You'll need to import your users into Dynamic (the previous section)
2. When a user logs in, check if they have a wallet in the previous system
3. Check if wallet was ever used/is empty
4. If it isn't, prompt user to transfer funds to new Dynamic wallet (this can feel like an account upgrade flow for the users)
5. Next time that the user logs in, they go to their Dynamic wallet
## Migration Path E: You have users, and they have AA wallets
### Considerations
1. Your users have an EOA embedded wallet, but it only serves as a signer for an AA layer (safe, zerodev etc).
2. Hence, you'll want to add the Dynamic-powered embedded wallet as a second signer to the AA layer, or alternatively swap signers from the old embedded wallet one to the Dynamic one
**Main activities**
You'll want to have the end user add their new Dynamic wallet as a second signer to the smart contract wallet, or alternatively have them replace the current signer with a second signer
**Steps**
Example: "Coinbase" | | `iconUrl` | string | Yes | - | The icon URL of the onramp provider to be displayed in UI.
Example: "[https://www.coinbase.com/assets/coinbase-logo-2020-09-09-1024x1024.png](https://www.coinbase.com/assets/coinbase-logo-2020-09-09-1024x1024.png)" | | `id` | string | Yes | - | The id of the onramp provider, ideally based off its name.
Example: "coinbase" | | `url` | string | No | - | The URL of the onramp provider. For iframe mode, this is displayed directly in the UI. For popup mode, this is opened in a new window when the provider is selected.
Example: "[https://widget.coinbase.com/iframe/onramp?apiKey=YOUR\_API\_KEY\&walletAddress=YOUR\_WALLET\_ADDRESS](https://widget.coinbase.com/iframe/onramp?apiKey=YOUR_API_KEY\&walletAddress=YOUR_WALLET_ADDRESS)" | | `openMode` | 'iframe' \| 'popup' | No | 'iframe' | The display mode for the onramp provider.
'iframe' - The provider will be displayed in an iframe within the UI
'popup' - The provider will be opened in a new window when selected | | `onClick` | function | Yes | - | The onClick handler for when the onramp provider is selected.
Signature: `({ wallet }: { wallet: Wallet }) => void` | | `description` | string | No | - | The description of the onramp provider to be displayed in UI.
Example: "Buy crypto with a credit card" | | `isPaymentMethod` | boolean | No | false | Whether the option is for a specific payment method within the onramp provider. If true, the SDK will display the option as a payment method in the UI. |
### Example 3: Bring Your Own Onramp
Instead of changing the existing onramp options, you can also add your own option, which can be as simple as this:
```tsx
const onrampOptions = (defaultOnrampOptions) => {
return [
...defaultOnrampOptions,
{
id: 'myNewOnramp',
url: 'https://dynamic.xyz',
displayName: 'My New Onramp',
iconUrl: 'https://my-company.com/icon.png',
openMode: 'popup',
},
];
};
```
The result should look like this:
# Default Onramp Experiences
Source: https://docs.dynamic.xyz/money-and-funding/default-onramps
## Summary
At Dynamic, we make it incredibly simple to add a Fiat onramp solution to your SDK integration. We are currently working with [Coinbase](https://www.coinbase.com/en-gb/developer-platform/products/onramp) and [Banxa](https://banxa.com/). Other great onramp solutions will be made available soon.
To learn how to customize the experience, check out the [Customizing the Onramp Experience](/money-and-funding/customizing-the-onramp-experience) doc.
# Fund from External Wallet
Source: https://docs.dynamic.xyz/money-and-funding/fund-from-external-wallet
## Introduction
As one of the funding options for users, you may want to allow them to fund their wallet from an external wallet.
To do so, all you need to do is turn it on in the [Funding tab in your Dynamic developer dashboard](https://app.dynamic.xyz/dashboard/funding).
If you open the configuration section for this option, you'll also be able to configure the following:
* The default currency/token to fund
* The suggested minimum amount to fund
* Whether the amount is a suggestion or a requirement
In the initial step, users will be able to select the external wallet they want to fund their wallet from, and following this, they can choose the amount and token:
# Quickstart
Source: https://docs.dynamic.xyz/quickstart
Let's get you up and running with a full signup/login UI! Just [sign up](https://app.dynamic.xyz) and follow the guide below!
| |
# Wallet
Source: https://docs.dynamic.xyz/react-sdk/objects/wallet
An object containing the attributes about the user wallets.
### Props
| Field | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| additionalAddresses: WalletAdditionalAddress\[] | Additional addresses associated to the wallet (e.g. ordinals and payment addresses for bitcoin wallets) |
| address: string | Public address of the connected wallet |
| chain: string | Current BlockChain name (e.g: 'ETH', 'SOL', 'BTC', etc) |
| connector: WalletConnector | The wallet connector object |
| id: string | The wallet's unique id (matches thw wallet verified credential on connect-anf-sign) |
| isAuthenticated: boolean | True if the user is authenticated, otherwise it's false |
| key: string | The wallet key (e.g. metamask, phantom, etc) |
### Methods
| Method | Description |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| getBalance(): Promise\By clicking "Connect", you agree to our{' '} Terms of Service {' '} and{' '} Privacy Policy .
{walletConnectorOptions.map((wallet) => (
); };
export default App
;````
{wallet.name}
))}
{wallets.map((wallet) => (
); };
export default App;
`````
{wallet.name}
))}
##### *Multiwallet prop has been removed.* If you have multiwallet enabled please enable it in your dashboard:
### Multi-wallet prompts without userProfile widget
* New [multiWalletPromptsWidget](https://docs.dynamic.xyz/react-sdk/components/dynamicmultiwalletpromptswidget)
This allows you to use the multi wallet prompts without needing the full user profile which in which these prompts are normally bundled.
# Upgrade from V2 to V3
Source: https://docs.dynamic.xyz/react-sdk/upgrade/v3
## Changes in 3.0.0-alpha.53 -> latest
See [here](/react-sdk/upgrade/v3#2-x-x-to-3-0-0-alpha-52) for changes from 2.x.x to 3.0.0-alpha.52
### Wallet and WalletConnectors
#### No undesired prompting
No more undesired prompting to reconnect or switch wallets when not required!
Now a wallet can be made primary at any time without extra prompting, even if the wallet is not connected or unlocked.
Users will only be prompted to connect/unlock when sending/signing a transaction if the wallet is not connected or unlocked already.
#### Wallet object has changed
* wallet.authenticated changed to wallet.isAuthenticated
* wallet.connected is now an async method wallet.isConnected()
* wallet.network is now an async method wallet.getNetwork()
* wallet.chain valid values have changed
We used to use values like 'eip155' for wallet.chain. This is no longer the case. The new valid values for wallet.chain are the following:
```
'ALGO' | 'BTC' | 'COSMOS' | 'EVM' | 'FLOW' | 'SOL' | 'STARK'
```
The Wallet object has changed and now contains some methods that were previously on the WalletConnector object. Each chain specific wallet has its own methods. The methods specific to the main chains on the wallet object are:
* EthereumWallet
* getPublicClient
* getWalletClient
* SolanaWallet
* getConnection
* getSigner
* BitcoinWallet
* sendBitcoin
* sendRawTransaction
* signMessageWithAddress
* signPsbt
* signPsbts
* CosmosWallet
* getOfflineSigner
* getProvider
* StarknetWallet
* getProvider
* getWalletAccount
* AlgorandWallet
* getSigner
### Wallet type checking
You should always use our utilities to check that you're dealing with the correct wallet type before calling the wallet specific methods.
```tsx
import { isEthereumWallet } from '@dynamic-labs/ethereum';
import { isSolanaWallet } from '@dynamic-labs/solana';
import { isBitcoinWallet } from '@dynamic-labs/bitcoin';
const { primaryWallet } = useDynamicContext();
if (isEthereumWallet(primaryWallet)) {
console.log('call any ethereum wallet method')
}
if (isSolanaWallet(primaryWallet)) {
console.log('call any solana wallet method')
}
if (isBitcoinWallet(primaryWallet)) {
console.log('call any bitcoin wallet method')
}
```
Learn more in the [Wallet Interactions section](/wallets/using-wallets/interacting-with-wallets).
#### Wallet connector object has changed
Since we have moved some methods from the connector to the wallet object, the wallet connector object is now slimmed down, you can find the methods and props available on both the connector and the wallet object in the [Wallet Interactions section](/wallets/using-wallets/interacting-with-wallets).
As with the wallet object, each chain specific wallet connector has its own methods so we recommend checking out the appropriate section for the chain you are working with.
wagmi connected: {isConnected ? 'true' : 'false'}
wagmi address: {address}
wagmi network: {chain?.id}
{primaryWallet && !account ? (
)
```
5. Run the app by executing:
Loading...
) : ( <>Address: {account?.address}
Send User Operation
)}
6. Add a valid address to send to, and an amount that is within your wallet's balance plus a reasonable gas fee. Click on the "Send" button, and you should see the transaction hash in the UI!
## Troubleshooting
**Problem:** `Execution reverted for an unknown reason`
**Solution:** This is most likely due to the account not having enough ETH to pay for the transfer, make sure your smart wallet is funded!
# Crossmint
Source: https://docs.dynamic.xyz/smart-wallets/smart-wallet-providers/crossmint
## Step-by-Step Guide
This guide shows you how to use Dynamic for authentication and as a signer for Crossmint Smart Wallets.
3. Expand the "Developers" section in the left-hand navigation and select "SDK and API Keys" to find your Dynamic Environment ID.
4. Copy the Dynamic Environment ID and return to the Crossmint developer console
5. Within the JWT authentication section, select "3P Auth providers" option, and then select Dynamic
6. Add your Environment ID and save changes
3. Enable the desired chain for smart wallet support (in this example, we'll use `polygon-amoy`)
Crossmint Smart Wallet:{' '}
{crossmintWallet?.address || 'Not connected'}
Dynamic Signer Wallet:{' '}
{dynamicWallet?.address || 'Not connected'}
Status:{' '}
{isLoading ? 'Loading...' : crossmintSmartWalletStatus}
{crossmintSmartWalletError && (
Error: {crossmintSmartWalletError?.message}
)}
Crossmint + Dynamic Integration
This example demonstrates how to use Dynamic's wallet as a signer for Crossmint Smart Wallets. When you connect with Dynamic, your wallet serves as the signer for your Crossmint Smart Wallet.
Loading...
;
} else if(user && !safeDeployed) {
return (
Welcome
Safe Account Deployed
Safe Address: {safeAddress}
If you would like to remove a multichain ZeroDev provider, hover your mouse over the network icon and you should be able to click the "Trash icon" to remove.
Click "Yes" to save and add another provider if desired.
Select "Amount" as the Type, "0.1" as the value and "Day" as the interval. This is saying that we will sponsor up to 0.1 ETH total per day
Click Create Project Policy, and that's it! Now start your app, log in and try sending some ETH out. The Dynamic SDK will check if a transaction meets your gas policies and will automatically hide the gas in the transaction confirmation step if the gas is sponsored, if not the gas will be displayed.
{primaryWallet && (
);
};
export default App
```
When using EIP-7702, make sure to:
* Enable a 7702 compatible network (like Odyssey Testnet) on [Dynamic's Chains](https://app.dynamic.xyz/dashboard/chains-and-networks#evm)
* Select 7702 for wallet options during ZeroDev configuration in the dashboard
{txHash && (
)}
{error &&
Transaction Hash:
{`${txHash.slice(0, 6)}...${txHash.slice(-4)}`}
(View on Explorer)
)}
Error: {error}
}
Click Connect your wallet, enter your email and hit Continue. After pasting in your OTP you'll be fully logged in!
Next, we're going to send a transaction. To do that, we will need some of the network's native token. Grab your wallet address by clicking on the Dynamic Widget, then click on the three dots next to your address and hit "Copy wallet address". If you're using Base Sepolia as in this guide, you can paste your address into the [Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia) which will deposit some free ETH into your account. After doing so, if you refresh your app, you should see your balance update
Now, send yourself some tokens by clicking on the Send button in the Dynamic Widget. Enter 0.01 as the amount, and an address of your choosing as the recipient, then hit Send now. You will see a screen like the following. Notice that there is no gas estimate field, because this transaction will be sponsored!
Hit confirm, sign for the transaction with your passkey. Congratulations, you just sent a gas-sponsored transaction! If you take your smart wallet address and paste it into the block explorer for your network (for Base Sepolia, that's the [Base Sepolia Scan](https://sepolia.basescan.org/)), you will see your smart wallet and the transaction you just sent.
## Examples
### Get smart wallet address vs signer address
The wallet connector will return your smart wallet address, that address will be used in the Dynamic UI and is the main address you will interact with. But you can fetch the signer address by using the wallet connector's eoaConnector property and then fetching the address there.
```tsx
import { useEffect, useState } from "react";
import {
useDynamicContext,
DynamicContextProvider,
DynamicWidget,
} from "@dynamic-labs/sdk-react-core";
import {
isZeroDevConnector,
ZeroDevSmartWalletConnectors,
} from "@dynamic-labs/ethereum-aa";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
const SignerAddress = () => {
const { primaryWallet } = useDynamicContext();
const [signerAddress, setSignerAddress] = useState("");
useEffect(() => {
if (!primaryWallet) {
return;
}
const {
connector,
address, // This is your smart wallet address
} = primaryWallet;
if (!isZeroDevConnector(connector)) {
return;
}
const signerConnector = connector.eoaConnector;
if (!signerConnector) {
return;
}
const getAddress = async () => {
const address = await signerConnector.getAddress();
if (!address) {
return;
}
setSignerAddress(address);
};
getAddress();
}, [primaryWallet]);
return My Signer address: {signerAddress};
};
const App = () => (
4. Select `Confidential` under `Client Type` and click `Save`
5. Under `Application setup` paste your "Redirect URL" (Redirect URL can be found in the [Dynamic dashboard](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-shopify))
6. Copy and past the `Client ID` and `Client Secret` from `Customer Account API credentials` and paste it into "Set up Shopify Auth" Modal in the Dynamic Dashboard.
7. Find your shopify store ID under `Application Endpoints` in the `Authorization endpoint` URL and paste it into `Shopify Store ID` in the Dynamic Dashboard.
# Spotify
Source: https://docs.dynamic.xyz/social-providers/spotify
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Spotify
1. Go to the [Spotify Developer Portal](https://developer.spotify.com/dashboard) and sign in
2. Click on "Create App" on the right of the screen
3. Specify an "App Name", "App Description"
4. Under "Redirect URIs"
1. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-shopify) depending on whether you want to do linking or signup.
2. Open the Spotify configuration section.
3. Copy the Redirect URL and paste it in the "Redirect URI" field in Spotify Developer Portal.
5. Under "Which API/SDKs are you planning to use?", check "Web API"
6. Check the terms and conditions
7. Click "Save" at the bottom of the form
8. Once saved, click on the app and click "Settings"
9. Copy the "Client ID" and "Client Secret" and paste it into the "Set up Spotify Auth" Modal in the Dynamic Dashboard
That's it! You now have OAuth credentials for your Spotify application that you can use in Dynamic.
# Telegram
Source: https://docs.dynamic.xyz/social-providers/telegram
2. In the next modal, click on `Verify properties`
3. Click on `Domain` and enter `app.dynamicauth.com` and click `Verify` to the right of the text box
4. In the next screen, click on `Copy` to the right of the TXT record and send it to us. After this click `Verify`. **Note that the domain verification will not work until we have added the record on our domain**
5. Once we have confirmed the record is added, click on `Continue to verify` and verify the domain
6. Add the callback URI specified in our dashboard under TikTok settings
7. Continue with your TikTok app submission
# Twitch
Source: https://docs.dynamic.xyz/social-providers/twitch
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Twitch:
1. Go to the [Twitch Developer Portal](https://dev.twitch.tv/console) and sign in to your account.
2. Once you're signed in, click on the [Applications](https://dev.twitch.tv/console/apps) on the left nav bar
3. Click on "Register Your Application", and enter the following information:
1. Name of your application
2. OAuth Redirect URLs
1. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-twitch) depending on whether you want to do linking or signup.
2. Open the Twitch configuration section.
3. Copy & paste the Redirect URL provided in your Dynamic Dashboard to the text field in Twitch
3. Category (You can select any that is most appropriate)
4. Click "Create"
5. You should see a new row added to the "Developer Applications" table
6. On the right side of the table in the app you just created, click on "Manage"
7. Click on "New Secret", this will generate a secret key you will see only once
8. Copy the "Client ID" and "Client secret" from the application you created in Twitch and paste it into the modal in the Dynamic Dashboard.
That's it! You now have OAuth credentials for your Twitch application that you can use in Dynamic.
# Twitter/X
Source: https://docs.dynamic.xyz/social-providers/twitter
## Creating a new App
Here are the step-by-step instructions for obtaining OAuth credentials for Twitter:
1. Go to the [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard) and sign in to your account.
2. Once you're signed in, go to "Projects & Apps", choose the project you want to configure,and in the "Apps" section at the bottom of the page, click the gears icon on the right.
3. At the bottom of the following page, under "User authentication settings" select "Set up"
4. Select "App permissions" and "Type of App" you want.
5. Under "App info" paste the "Redirect URL":
1. In the Dynamic dashboard, visit either social account linking on the [Info Capture page](https://app.dynamic.xyz/dashboard/configurations#informationcapture) or in [the Social Signup page](https://app.dynamic.xyz/dashboard/log-in-user-profile#social-twitter) depending on whether you want to do linking or signup.
2. Open the Twitter configuration sectione.
3. Copy the Redirect URL and paste it in the "Redirect URL" field in Twitter Developer Portal.
6. Enter your "Website URL".
7. Click save under the form.
8. Copy the "Client ID" and "Client Secret" and paste it into "Set up Twitter Auth" Modal in the Dynamic Dashboard.
That's it! You now have OAuth credentials for your Twitter application that you can use in Dynamic.
If you need more help with configuring the Twitter OAuth App check their docs [here](https://developer.twitter.com/en/docs/authentication/guides).
# Store Approval Issues
Source: https://docs.dynamic.xyz/troubleshooting/browser-extension/browser-extension-approval-issues
# Google Play Store Approval Guide
When submitting browser extensions to the Google Play Store, you may encounter specific restrictions that can lead to rejection. This guide covers common issues and their solutions.
## Remote Code Loading in Manifest V3
### The Issue
Google Play Store prohibits Manifest V3 extensions from loading remotely hosted code. A common violation occurs when your extension bundle includes code that loads external scripts, such as the AppleID script from `https://appleid.cdn-apple.com/`.
### Solution: Replacing Remote Loaders
To resolve this issue, you can configure your bundler to replace remote script loaders with local dummy files. We provide solutions for both Vite and Webpack bundlers.
#### Step 1: Create a dummy loader file
First, create a dummy loader file that will replace the remote script loader:
```javascript
// src/loadAppleId.js
"use client";
const loadAppleId = () => {};
export { loadAppleId };
```
#### Step 2: Configure your bundler
##### Option 1: Using Vite
Configure Vite to alias the remote loader to your dummy file:
```typescript
// vite.config.ts
import { defineConfig } from "vite";
import path from "path";
const replaceLoadAppleIdScriptWithCustomScriptPlugin = {
name: "replace-loadAppleId",
enforce: "pre",
resolveId(source) {
if (source.includes("loadAppleId")) {
return path.resolve(__dirname, "src/loadAppleId.js");
}
},
} as const;
export default defineConfig({
plugins: [react(), replaceLoadAppleIdScriptWithCustomScriptPlugin],
// ... other config options
});
```
For a complete Vite implementation example, check out our [Vite reference implementation](https://github.com/dynamic-labs/browser-extension-bundled-with-vite-example/commit/cb24d17435e04f7c21c82527d572aff8bfe42e1a).
##### Option 2: Using Webpack
Configure Webpack to alias the remote loader to your dummy file:
```javascript
// webpack.config.js
const path = require('path');
const webpack = require('webpack');
module.exports = {
// ... other config options
resolve: {
alias: {
// Alias any imports containing loadAppleId to our local dummy file
loadAppleId: path.resolve(__dirname, 'src/loadAppleId.js'),
},
},
plugins: [
// ... other plugins
// Add a plugin to replace any direct references to the Apple ID script URL
new webpack.NormalModuleReplacementPlugin(
/loadAppleId/,
path.resolve(__dirname, 'src/loadAppleId.js')
),
],
};
```
For a complete Webpack implementation example, check out our [Webpack reference implementation](https://github.com/dynamic-labs/browser-extension-bundled-with-webpack-example).
# Dynamic Doctor
Source: https://docs.dynamic.xyz/troubleshooting/dynamic-doctor
Web3 moves fast, and this means that version management when it comes to packages is difficult. Often one library might require a specific version of Viem while another requires a different version. This is where Dynamic Doctor can help.
Use it if you've installed and initialized Dynamic but you're getting some errors. Often these can be related to the versions currently installed even though the errors themselves might not indicate it.
## Usage
In the root of your project, run the following command:
```bash
npx dynamic-doctor@latest run
```
## Output
You will see a list of issues found and a file `dynamic-doctor-report-
A common error encountered when using WalletConnect is `Unsupported chain`. This error occurs when the chain ID of the network you are trying to connect to is different than the chain specified by the WalletConnect provider.
```
UnknownRPCError: An unknown RPC error occurred.
Details: Unsupported chain
```
To resolve the above error, the `DynamicContextProvider` can be configured to dynamically change the desired WalletConnect chain ID of the network you are trying to connect to using the `walletConnectPreferredChains` property. [See here](/react-sdk/providers/dynamiccontextprovider#settings)
```jsx
My Component
;
}
```
## User Format
This user record follows a specific format, which you can read all about in the [User](/react-sdk/objects/userprofile) reference.
One important array inside that user object will be called `verified_credentials`. This is where you'll find information about any and every associated "credential" for the user i.e. email, social, blockchain, passkey.
| Property | Value |
|---|---|
| {user?.email} | |
| First name | {user?.firstName} |
| Last name | {user?.lastName} |
| Alias | {user?.alias} |
| Job title | {user?.jobTitle} |
| Country | {user?.country} |
Here you specify which fields you want to collect. For each field, you can select whether it is optional or mandatory.
Save, and you're all set!
## Pre-signup
## Post-signup
If fields are mandatory, they cannot be skipped during onboarding and the user will be prompted to enter the information. However, if you have only optional fields, you can skip them during onboarding and prompt for them at a time of your choosing.
Then, if you want to prompt the user to enter the information at a later time, you can do so by calling the `updateuserwithmodal` method from the [`useuserupdaterequest` hook](/react-sdk/hooks/useuserupdaterequest#function-updateuserwithmodal). This will trigger the UI for info capture.
## FAQ
Q. What happens with your current users if you change the settings?
A. No big deal. If you make certain fields required, then the next time a user connects to your application, we'll ask them to enter the field that you just made mandatory. That way, your users will stay up to date with the fields that you need.
# Social Linking
Source: https://docs.dynamic.xyz/users/social-linking
Dynamic supports linking social accounts from Apple, Discord, Facebook, Farcaster, Github, Google, Telegram, Twitch and Twitter!
You can do this by going to the Information Capture section of the dashboard and toggling on Social Account Linking.
It will then prompt you you to configure a social provider, and you can find the guides for each one in [the social providers section.](/social-providers/overview)
# Verified Credentials
Source: https://docs.dynamic.xyz/users/verified-credential
## Introduction
In the physical world, we as people have numerous ways of identifying ourselves (a passport, driving license or birth certificate for example). They are each used in different contexts, and can have different fields of information but they are share one defining characteristic, they are accepted as proof of identity and are called "physical credentials".
We have exactly the same need in the digital world and for this reason, the concept of ["verified credentials"](https://en.wikipedia.org/wiki/Verifiable_credentials) were created. A Verified Credential (VC) is a way to represent a digital identity in a way that can be shared and verified by others. They can be digital representations of physical credentials (like a passport) or they can be entirely digital (like an email address).
Specific to Dynamic, verified credentials can map to things like oauth (i.e. Facebook and Google), email, blockchain wallets, passkeys and more (these are called "formats"). Each format has its own set of fields and information that can be shared. They also always have a "provider" which is the service that issued the credential (i.e. Google, Apple, Dynamic).
## Accessing Verified Credentials
As you probably already read in the [accessing users](/users/accessing-users) section, you can access verified credentials as part of the user profile, so once you have that it is as simple as accessing the `verifiedCredentials` array.
```javascript
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
const { user } = useDynamicContext();
const verifiedCredentialsArray = user?.verifiedCredentials;
```
## Verified Credential Structure
### Fields Applicable to All VCs
| Field | Description |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | Internal ID for this VC |
| format: JwtVerifiedCredentialFormatEnum | \[Optional] - Type of VC, e.g., email. See [JwtVerifiedCredentialFormatEnum](/users/verified-credential#jwtverifiedcredentialformatenum) for more details. |
| publicIdentifier? | \[Optional] - Common way to reference the VC, e.g., email address for email VCs or the name of a user for Google VC. |
| email? | \[Optional] - Email associated with the VC. |
### Fields Specific to OAuth
| Field | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| oauthProvider? | \[Optional] - Social provider associated with the VC, e.g., Apple. See [ProviderEnum](/users/verified-credential#providerenum) for more details. |
| oauthAccountId? | \[Optional] - ID associated with the social provider for the VC. |
| oauthDisplayName? | \[Optional] - Display name associated with the social provider for the VC. |
| oauthUsername? | \[Optional] - Username associated with the social provider for the VC. |
| oauthEmails? | \[Optional] - Emails associated with the social provider for the VC. |
| oauthAccountPhotos? | \[Optional] - Photos associated with the social provider for the VC. |
| refId? | \[Optional] - If using OAuth, this is the embedded wallet ID associated with the social account. |
| previousUsers? | \[Optional] - User IDs who were previously associated with the VC. |
### Fields Specific to Wallets
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| walletName? | \[Optional] - Wallet name associated with the VC. |
| address? | \[Optional] - Wallet address associated with the VC. |
| chain? | \[Optional] - Chain associated with the VC. |
| walletProvider? | \[Optional] - Type of wallet. See [WalletProviderEnum](/users/verified-credential#walletproviderenum) for more details. |
| walletProperties? | \[Optional] - Generally only used for embedded wallets with Turnkey. See [WalletProperties](/users/verified-credential#walletproperties) for more details. |
| embeddedWalletId? | \[Optional] - ID of the embedded wallet associated with the VC. |
| nameService? | \[Optional] - ENS data name and avatar URL, if one is associated with the wallet in the VC. See [NameServiceData](/users/verified-credential#nameservicedata) for more details. |
| signerRefId? | \[Optional] - For smart contract wallets, this is the wallet ID of the signer for the SCW. |
### NameServiceData
| Field | Description |
| --------------- | -------------------------------------------- |
| avatar?: string | \[Optional] - avatar associated with the ens |
| name?: string | \[Optional] - name associated with the ens |
### WalletProviderEnum
'browserExtension' || 'custodialService' || 'walletConnect' || 'qrCode' || 'deepLink' || 'embeddedWallet' || 'smartContractWallet'
### WalletProperties
| Field | Description |
| --------------------------------- | ------------------------------------------------------------------ |
| turnkeySubOrganizationId?: string | \[Optional] - turnkey sub organization ID associated with wallet |
| turnkeyHDWalletId?: string | \[Optional] - turnkey HD wallet ID associated with the the wallet |
| isAuthenticatorAttached?: boolean | \[Optional] - is authenticator i.e. passkey attached to the wallet |
### JwtVerifiedCredentialFormatEnum
'blockchain' || 'email' || 'oauth' || 'passkey'
### ProviderEnum
'emailOnly' || 'magicLink' || 'apple' || 'bitbucket' || 'discord' || 'facebook' || 'github' || 'gitlab' || 'google' || 'instagram' || 'linkedin' || 'microsoft' || 'twitch' || 'twitter' || 'blocto' || 'banxa' || 'dynamic' || 'alchemy' || 'zerodev' || 'turnkey'
# Integrate your Chain
Source: https://docs.dynamic.xyz/wallets-and-chains/chains
We're excited about the possibility of supporting your chain on Dynamic! We're always looking to expand our ecosystem and provide developers with more options. If you'd like us to consider adding support for your chain, please submit your information using the form below. Our team will review your submission and reach out to learn more about your chain and explore potential integration.
# Integrate your Wallet
Source: https://docs.dynamic.xyz/wallets-and-chains/wallets
## Overview
If you're a wallet looking to integrate with Dynamic, you're in the right place. We support multiple wallet standards, and if you implement one of these standards, we can quickly add you to our list of supported wallets.
After implementing one of these standards below, reach out via the form below to get allowlisted.
## EVM
### WalletConnect Protocol
[WalletConnect Protocol](https://walletconnect.com/) is an open protocol that enables secure communication between wallets and dApps. It supports a wide range of wallets across multiple chains, including MetaMask, Rainbow, and other EVM-compatible wallets.
### ERC-6963
[ERC-6963](https://eips.ethereum.org/EIPS/eip-6963) is a standard for wallet discovery and connection for browser extension wallets. It aims to improve the user experience by allowing dApps to detect and interact with multiple installed wallets at the same time. MetaMask, Coinbase Wallet and Rainbow are some of the wallets that support this standard.
### Mobile Wallet Protocol
The Mobile Wallet Protocol is designed for seamless integration between mobile wallets and dApps and is led by Coinbase. You can find more information on the protocol [here](https://github.com/MobileWalletProtocol/wallet-mobile-sdk).
### Smart Wallets (ERC-1271 and ERC-6492)
Smart wallets are contract-based wallets that offer advanced features like account abstraction. If you're a smart wallet looking to integrate with Dynamic, note that we support both [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) (Standard Signature Validation Method for Contracts) and [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492) (Signature Validation for Predeploy Contracts).
## Solana
### Solana Wallet Standard
The [Solana Wallet Standard](https://github.com/solana-labs/wallet-standard) is a specification for Solana wallets to interact with dApps. It supports wallets such as Phantom, Solflare, and other Solana-compatible wallets.
### WalletConnect Protocol
WalletConnect Protocol also supports Solana wallets, enabling cross-chain compatibility.
## Bitcoin
### Bitcoin Wallet Standard
The [Bitcoin Wallet Standard](https://github.com/ExodusMovement/bitcoin-wallet-standard) is an emerging specification for Bitcoin wallets to interact with web applications. Wallets such as Exudus, Phantom and Magic Eden support this protocol.
### Sats Connect
[Sats Connect](https://docs.xverse.app/sats-connect) is a protocol for connecting Bitcoin wallets to web applications. Xverse, Hiro, and other Bitcoin wallets implement this standard
## Custom Wallet Connectors
Dynamic now offers developers the ability to add their own custom wallet connectors to the Dynamic SDK. This feature allows for greater flexibility and customization in integrating wallets that may not follow standard protocols or have unique requirements.
To create a custom wallet connector:
1. Visit the [Dynamic Public Wallet Connectors repository](https://github.com/dynamic-labs/public-wallet-connectors) on GitHub.
2. Follow the guidelines in the [CONTRIBUTING.md](https://github.com/dynamic-labs/public-wallet-connectors/blob/main/CONTRIBUTING.md) file to understand the process of creating and submitting a custom connector.
3. For an example of a custom connector implementation, you can refer to the [Safe connector](https://github.com/dynamic-labs/public-wallet-connectors/blob/main/packages/@dynamic-labs-connectors/safe-evm/README.md).
By creating a custom wallet connector, you can ensure that your wallet integrates seamlessly with the Dynamic SDK, providing a smooth experience for users of your wallet and applications using Dynamic.
## Submit your wallet
Ready to add your wallet to Dynamic or need us to make changes to a current wallet's name or logo? Fill out our form below and we'll get back to you shortly.
# External Wallets Overview
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/branded-wallets-overview
External wallets are a way to let users sign up and log in to your application using their own wallet, such as MetaMask. This is opposed to embedded wallets, where the wallet is created and managed by Dynamic on signup or after.
### How it works
### Overview
Each wallet is created as a smart contract wallet (ERC-4337), and is secured by a user added Passkey, which is tied to the domain "keys.coinbase.com".
Because the passkey is scoped to Coinbase's domain, the wallets will work securely across any site that integrates with Coinbase Smart Wallet.
This is a huge unlock for the ecosystem, as it allows users to have a seamless experience across multiple sites, without any extra lift.
Since the wallet is actually an ERC-4337 compliant smart contract, you can also make use of batch transactions and app-defined paymasters which are supported by the Coinbase Smart Wallet.
Lastly, the wallet is integrated with [Magic Spend](https://www.smartwallet.dev/why#magic-spend) by default, allowing for seamless onramping of funds into the newly created wallet.
### Signing
The user signs with their passkey, and a function named `isValidSignature` is subsequently called on their Smart Wallet in order to verify that signature ([based on EIP-1271](https://eips.ethereum.org/EIPS/eip-1271)).
Since the user's passkey is an owner on the Smart Wallet's contract, it would return that the signature is valid and the transaction can be processed from there. However, what happens if the smart acccount has not yet been deployed?
A Smart Wallet is not deployed on a chain until the first transaction on that chain, so there must be a method of handling the signing of an initial transaction offchain. This is done by adopting the solutions outlined in [EIP-6492](https://eips.ethereum.org/EIPS/eip-6492).
### What's Next
We're excited to support the move of Coinbase Smart Wallet to mainnet in the coming weeks. With incredible features such as [Magic Spend](https://www.smartwallet.dev/guides/magic-spend) and [Batch Transactions](https://www.smartwallet.dev/guides/batch-transactions), we see a future of even simpler new user onboarding. Learn more in our deeper blog post on [Coinbase Smart Wallet](https://www.dynamic.xyz/blog/test-drive-coinbases-smart-wallet-today).
### Get up to \$20k in paymaster credits
Utilizing Coinbase Smart Wallets or AA accounts on @base with Dynamic?
We teamed up with @coinbasewallet to kick it up a notch 💙
You may be eligible for up to \$20K in gas credits: \$15K from the Smart Wallet Gas Program + \$5K just for being a Dynamic customer.
Fill out this form to indicate that you are building with Dynamic and get credits: [apply now](https://docs.google.com/forms/d/1yPnBFW0bVUNLUN_w3ctCqYM9sjdIQO3Typ53KXlsS5g/viewform?edit_requested=true)
# Configure Connect Only Mode
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/connect
### Setup
By default, the SDK will authenticate all users which means users will need to
sign when logging in. This page describes how you can remove the authentication
step and allow users to just connect their wallets to log into your site.
### Usage
#### initialAuthenticationMode (optional)
If you want to skip signing a message and just connect, then set the
`initialAuthenticationMode` to `connect-only`.
```js TypeScript
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
User is authenticated!
;
};
```
### Example
This video shows our [demo site](https://demo.dynamic.xyz). Here we start with a connected user who
has not yet authenticated. We call the authenticateUser method and signature
request appears. Once the user signs, then Dynamic verifies the signature and
returns a JWT.
# Connected vs Authenticated
Source: https://docs.dynamic.xyz/wallets/advanced-wallets/connected-vs-authenticated
## Definitions
When using Dynamic, one of the first things you'll need to decide is whether you want to have users sign to prove ownership of their wallets or if you just want them to connect their wallets.
As we talk about these two options, you'll regularly see that we either discuss a `visitor` or an `authenticated user` in our documents and dashboard. In short, here are there definitions:
* `Visitor` is a user that connects their wallet to your dApp but has not yet signed to prove ownership of that wallet.
* You can identify a visitor as having a `primaryWallet` but user is not defined.
* `Authenticated User` is a user that connects their wallet and has signed to prove ownership.
* You can identify an authenticated user since the `user` object will be defined.
* A JWT is returned for an authenticated user
For example, here we log in a user whether they are connected or authenticated. We check for either a primary wallet or a user being defined.
```typescript
import { useDynamicContext } from "@dynamic-labs/sdk-react-core"; //later you will read about dynamicContext
const HomePage = () => {
const { primaryWallet, user } = useDynamicContext();
if (primaryWallet !== null || user) {
return (
In our New to Web3 help section in our SDK, we show a common wallet for users to get started for each chain. For now, if you have enabled more than 1 chain, then we will show only 1 chain and 1 wallet.
To change the default wallet shown in this this section, you can pass a prop `newToWeb3WallChainMap` to specify the primary chain (this is to support multi-chain) and then specify the wallet with the corresponding chain.
```Typescript
## Display as a sentence
#### privacyPolicyUrl (optional) & termsOfServiceUrl (optional)
We currently display the Terms of Service and Privacy Policy during the connecting step of the SDK.
If you want to update the links, then you can do so by updating the props in settings.
```TypeScript
By checking this box, you agree to our{' '} Terms of Service {' '} and{' '} Privacy Policy .
### Creating wallets for external wallet login
Embedded wallets can be automatically created for users signing in with external wallets, such as Metamask. To enable this feature, click the “Create on Sign up” card to expand the “Advanced Options” panel, and ensure the "Embedded Wallet for Third-Party Wallets" toggle is enabled.
## Disable Confirmation Screen
You can enable/disable this transaction confirmation screen with a single toggle in the [Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic). If you want to keep the confirmation UI but customize it, read on!
## Customize Confirmation Screen
### Modal title
By default this reads "Confirm transaction" as you can see in the image above, but you can customize it to say whatever you want. To do this, use [Translations](/design-customizations/customizing-copy-translations) and set the following:
```tsx
const locale = {
en: {
dyn_send_transaction: {
confirmation: {
title: "My New Title",
},
},
}
};
When turned on, as well as having the Confirmation UI on, transactions will be simulated to show all asset transfers of a transaction. So, if you are swapping 0.1 SOL to USDC, you will see the assets coming in and out on the transaction UI.
## Future Enhancements
Our upcoming security features will include comprehensive transaction and signature analysis to protect users from potential vulnerabilities. This includes detection of token and NFT approval requests, as well as any other asset exposures in order to provide enhanced transparency during transaction flows.
# Advanced Features
Source: https://docs.dynamic.xyz/wallets/mpc/advanced
## Custom Key Derivation Options
Our solution supports flexible key derivation paths and customizable derivation schemes. This enables advanced use cases like hierarchical deterministic wallets, custom address generation patterns, and integration with existing key management systems.
## Advanced Key Sharing Configurations
Beyond the standard 2-of-3 setup, we support more complex key sharing arrangements like 3-of-5 configurations and other custom threshold schemes. This allows for more sophisticated security models, including:
* Multiple backup options
* Tiered access controls
* Enhanced security through additional key shares
* Custom recovery flows with [Independent Recovery](/wallets/mpc/glossary#independent-recovery)
# Architecture & Cryptography
Source: https://docs.dynamic.xyz/wallets/mpc/architecture
### Key Share Management
**During wallet creation:**
1. The [User Share](/wallets/mpc/glossary#user-share) is generated and stored locally on their device (on web, this is done in an iframe)
2. The [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share) is generated and stored by Dynamic in encrypted form
3. An encrypted copy of the User Share is stored by Dynamic using [User Share Backup Options](/wallets/mpc/glossary#user-share-backup-options)
4. The backup is encrypted using the [Encryption Proxy Service](/wallets/mpc/glossary#encryption-proxy-service)
5. Dynamic cannot decrypt the backup without the user
6. Users can optionally add [Passcode Encryption](/wallets/mpc/glossary#passcode-encryption) for additional backup security
**When signing transactions:**
1. The [User Share](/wallets/mpc/glossary#user-share) participates from their local device
2. The encrypted [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share) is decrypted and used for signing within a [TEE (Trusted Execution Environment)](/wallets/mpc/glossary#tee-trusted-execution-environment)
3. The complete private key is never reconstructed, even within the TEE
**This architecture ensures that:**
* No single party has complete control of the private key
* Users maintain self-custody of their wallet
* Recovery is possible if a user loses access to their device
* The system is resistant to compromise of any single party
* All sensitive signing operations are protected within the TEE
### 4. Set up your SDK
### Creating wallets for external wallet login
Embedded wallets can be automatically created for users signing in with external wallets, such as Metamask. To enable this feature, click the "Create on Sign up" card to expand the "Advanced Options" panel, and ensure the "Embedded Wallet for Third-Party Wallets" toggle is enabled.
When this is enabled:
* The system automatically upgrades to a 2-of-3 threshold scheme through [Key Resharing](/wallets/mpc/glossary#key-resharing)
* The user maintains their local [User Share](/wallets/mpc/glossary#user-share)
* A copy of the User Share is stored using their chosen backup option
* Dynamic continues to secure the [Dynamic Server Share](/wallets/mpc/glossary#dynamic-server-share)
This creates three recovery paths:
1. Using the stored User Share from backup + Dynamic Server Share
2. Using the local User Share + Dynamic Server Share
3. Using the local User Share + stored User Share from backup ([Independent Recovery](/wallets/mpc/glossary#independent-recovery))
When a user has access to both their local User Share and the stored backup copy, they can perform Independent Recovery without requiring Dynamic's share. As long as they are logged in and have access to the client-side SDK, they can use these two shares to reconstruct and export their private key completely independently of Dynamic's systems. This provides an important self-custody guarantee - users can always recover their wallet even if Dynamic's services are unavailable.
You can customize various elements of the transaction UI:
### Disable Confirmation Screen
You can enable/disable the transaction confirmation screen with a single toggle in the [Embedded Wallet configuration page](https://app.dynamic.xyz/dashboard/embedded-wallets/dynamic).
### Modal Title
Change the default "Confirm transaction" text using [Translations](/design-customizations/customizing-copy-translations):
## Transaction Simulation
When turned on, as well as having the Confirmation UI on, transactions will be simulated to show all asset transfers of a transaction. So, if you are swapping 0.1 SOL to USDC, you will see the assets coming in and out on the transaction UI.
# Multi Asset UI
Source: https://docs.dynamic.xyz/wallets/multi-asset
## Overview
With Dynamic's multi-asset UI, you can present your end users with the individual balances of each asset they hold in their wallet.
Balance and pricing information is refreshed every 20 min. If you need minute by minute refresh and different asset support, contact sales.
The list of tokens reflect the top 1000 tokens by DEX volume. We leverage Coingecko for pricing.
You can also choose to show the Fiat balance of those assets in whatever their primary currency is.
// ONLY USE ONE OR THE OTHER
)
}
```
### End user experience
Once logged in, on the Wallets screen of the widget, you will notice a "Send" button. Clicking on this button will take you to the Send Token UI.
You can then choose from any available token in your wallet, add an amount and recipient address, then preview the transaction before confirming.
## Standalone UI (useSendBalance)
You can use our useSendBalance hook to trigger the Send Balance UI and optionally, prepopulate the form for the user.
### How it works
The useSendBalance hook depends on the DynamicContextProvider, so it has to be used as a child of the Dynamic context. When you use the hook, you will get a function named `open`. That method accepts the follow options:
| Parameter | Type | Description |
| :--------------- | :--------------- | :----------------------------- |
| recipientAddress | String | The initial recipient address |
| value | ethers.BigNumber | The initial transaction amount |
The `open` function will return a promise; If successful, the promise will be resolved with the transaction; if not successful, the promise will be rejected accompanied by the error collected from the provider.
Here is an example of a custom Send button
```typescript
import { useSendBalance } from "@dynamic-labs/sdk-react-core";
const MySendButton = () => {
const { open } = useSendBalance();
return ;
};
```
From this example, when the user clicks the button, they will be prompted to fill the amount and recipient fields, review the transaction, and they will see a confirmation at the end of the flow.
For the second example, we will pre-populate the recipient and amount fields for the user.
```typescript
import { useSendBalance } from "@dynamic-labs/sdk-react-core";
import { ethers } from "ethers";
const MySendButton = () => {
const { open } = useSendBalance();
const onCickSend = async () => {
try {
const tx = await open({
recipientAddress: "",
value: ethers.utils.parseEther("1"),
});
} catch (err) {
// Handle the promise rejection
}
};
return ;
};
```
Here, when the user clicks the button, they will be prompted with the same UI, but now it will be pre-populated with the recipient address and amount.
# Accessing Wallets
Source: https://docs.dynamic.xyz/wallets/using-wallets/accessing-wallets
Learn about primaryWallet, useUserWallets, onEmbeddedWalletCreated, and handleConnectedWallet
## Introduction
It's not neccessary for a wallet to be associated with a user when they sign up, but the likelyhood is that if a user is interacting with Web3, one will be connected at some point, whether embedded or external (branded).
### Primary Wallet
Normally, if one or more wallets are connected, a `primaryWallet` object will be available on the Dynanmic Context which you can access with [the `useDynamicContext` hook](/react-sdk/hooks/usedynamiccontext). This is a quick and easy way to access the main wallet associated with that user.
```jsx
const { primaryWallet } = useDynamicContext();
```
### useUserWallets
Going beyond the primary wallet, you might want to get every wallet associated with the given user. The best option for this is to use [the `useUserWallets` hook](/react-sdk/hooks/useuserwallets).
```jsx
import { FC } from 'react'
import { useUserWallets } from '@dynamic-labs/sdk-react-core'
export const ListConnectedWallets: FC = () => {
const userWallets = useUserWallets()
return (
Wallets
{userWallets.map((wallet) => ({wallet.address}
))}Mint NFT
{isSuccess && (
Successfully minted your NFT!
)}
No wallet connected
;
if (isLoading) return Loading...
;
if (isError) return Error: {error.message}
;
return (
{tokenBalances.map((token) => (
))}
);
};
```
# Switch user's primary wallet
Source: https://docs.dynamic.xyz/wallets/using-wallets/general/switch-primary-wallet
The [useSwitchWallet hook](/react-sdk/hooks/useswitchwallet) gives you the ability to switch the user's primary wallet.
All it needs is a wallet ID as a parameter, and it resolve upon success. You can find the ID on any wallet object in Dynamic i.e. on the primaryWallet or those returned by [useUserWallets](/react-sdk/hooks/useuserwallets):
```jsx
import React from 'react';
import { useSwitchWallet, useUserWallets } from '@dynamic-labs/sdk-react-core';
const WalletSwitcher = () => {
const switchWallet = useSwitchWallet();
const userWallets = useUserWallets();
return (
{token.name}
{token.symbol}
{token.balance}
{userWallets.map(wallet => (
))}
);
};
```
# Interacting with wallets
Source: https://docs.dynamic.xyz/wallets/using-wallets/interacting-with-wallets
There are two aspects of the wallet object that are useful to know about:
1. The wallet object itself
2. The connector object
### Wallet Interface
The wallet is akin to a single account on your Wallet provider. For example, in Metamask, you can have multiple accounts, each with their own public address.
You can also have multiple chains associated with a single account in your wallet provider, for example in Magic Eden, you can have "Account 1", which has a public address for Solana, another for Bitcoin, etc. Each of these chain addresses are mapped to a different wallet object in Dynamic.
You'll find props and methods for a wallet object are specific to interacting with a single account/sub-account (i.e. for a single chain) on your wallet provider.
For example, getBalance, or signMessage interact with a single account/subaccount.
Below we outline the generic props and methods for a wallet object no matter what chain the account belongs to.
In each chain specific section, we also outline the props and methods for a wallet object for that chain.
Send USDC (Gasless)
setRecipientAddress(e.target.value)}
/>
setAmount(e.target.value)}
/>
{result}
{txSignature && (Signature: {txSignature}
View on Solana Explorer