Skip to main content
The pattern for migrating a wallet to Turnkey is straightforward: we want to export the wallet from the existing provider, and securely import it to Turnkey. No matter which approach, it is recommended to create a sub-organization for each user. Each suborg can have its own set of wallets, authenticators, and policies that govern access. These “delegated access” flows are key to enabling powerful and secure use, whose configuration is an important part of the migration to Turnkey. For further guidance continue in our docs, and don’t hesitate to reach out to hello@turnkey.com. Additionally, familiarize yourself with Turnkey’s resource and rate limits. Ensure that finite suborg resources (like authenticators & private keys) and RPS limits are compatible with your migration approach.

​
Asset Availability

In most circumstances user assets remain exactly as they were on-chain, belonging to the same key/address. However, if a provider does not meaningfully support export, you may have to instead create a new wallet in Turnkey and transfer assets to it. Security note: be mindful that there are no guarantees a previous provider destroys their copy of exported keys, or that it wasn’t logged somewhere. It can be worth considering creating a new wallet and transferring assets to it anyway.

​
Non-custodial wallets

Migrating a non-custodial (user-owned) wallet to Turnkey follows the pattern described earlier. Within your application, we want to invoke the outgoing provider’s user facing export method, and prompt the user to copy over the key or seed to Turnkey’s importer iframe. This can be done “just in time,” creating the Turnkey user information (like suborg) on the spot when importing. This can also be done in a batch ahead of time, which might be preferable for larger migrations.

​
Export from existing provider

This export typically takes the form of an export modal which displays the private key or seed phrase in plaintext to the user. The specifics depend on your provider, but popular choices typically have methods designed for the user to copy their key/seed to clipboard.

​
Import to Turnkey

Setting up the import modal is easy. We maintain an embedded iframe element on import.turnkey.com, which ensures the mnemonics and keys travel securely directly to and from Turnkey’s infrastructure (instead of through yours). This frame should appear after the user has copied (exported) their key/seed in the first step, and will guide them through importing it to Turnkey. We’ve created a package designed to help you insert this iframe and interact with it: @turnkey/iframe-stamper
This is covered completely in the Import - Embedded iframe docs section. Additional information on key transport is covered in our Enclave to end-user secure channels page.

​
Custodial wallets

If instead you manage your users’ wallets, the export/import pattern will be similar, but typically take the shape of a back-end service you control.

​
Export from existing provider

The specifics will depend on the provider, but popular choices typically offer multiple programmatic wallet export options. The mnemonic key, or the private key + its format is all that is required to create a wallet bundle and import the account.
  • Privy: Node and API
  • Dfns: API
  • Other - Database (e.g. Firebase): accessing private keys on a db instance may require special permission, but tend to be simple and efficient to fetch in large numbers
  • Other - Hosted platform: some services may require user auth on key export, check available documentation
It is preferable for this migration script to not directly write/save these exported keys to the local filesystem, and instead directly pass them to the below import methods as keys are retrieved.

​
Import to Turnkey

There are two options for importing wallets to Turnkey programmatically: Please visit these linked resources for implementation-specific guides and code samples.
⌘I