Account Migration Guide
Does this article need to be translated?
This guide details the process of transferring the contents of all the accounts in your wallet to new accounts derived from a different Secret Recovery Phrase. You may be looking for instructions on how to perform "key migration", or you may have been told your SRP has been compromised. Maybe you have seen some unauthorized transactions in your accounts, or suspect someone has access to your wallet.
Whatever the reason, this guide is for those who want to move all their crypto assets to new, safe, accounts.
If you're in a hurry, and need to get started now, follow the steps below.
There is a lot of background information that can help you understand what's going on. If you get confused during the process, or would rather understand before proceeding, read the in-depth information further down in this article. Hopefully our explanations clear things up.
How to migrate your cryptoassets to new accounts
Step One: Ensure a safe environment
In order to keep your new SRP safe, you need to be in a safe situation.
This means:
- You are not being physically observed
- Your system is free from malware or spyware
- You have a secure medium on which to record your new SRP
- You are not being directed to do this by a person you don't trust
- You are not doing this under duress
- Traffic on your Internet connection is not being monitored
- Hint: a VPN connection under such circumstances can be very helpful!
Step Two: Generate a new SRP
This is easily done, in a matter of minutes, using MetaMask: you don't even need to change browsers.
- Follow the instructions here to create a new browser profile
- Navigate to https://metamask.io/download/ (type in the address: don't click on a web search result)
- Alternatively, find MetaMask in the Android (https://play.google.com/store/apps/details?id=io.metamask) or iOS (https://apps.apple.com/us/app/metamask-blockchain-wallet/id1438144202) stores
- Install the extension or application, and step through the process to create a new Secret Recovery Phrase
- Make note of that new Secret Recovery Phrase, and keep it somewhere safe
Step Three: Get a safe address to send your tokens to
- Follow the instructions here to copy the public address of the default account generated by your new SRP.
- Have that address at hand on the device that has the "source" SRP; it might help to open it in Etherscan, or you could hold it in a synced note, because it's a public address--you should never, ever, ever put an SRP in a cloud-synced note app.
Note: You can generate as many accounts as you want in your new SRP, and divide up your tokens however you wish among them. Also, if you have a hardware wallet on hand, now would be a convenient time to transfer assets to an address generated by an SRP that is only present on your hardware wallet.
Step Four: Transfer your stuff
This part of the process will vary depending on your specific situation. You may need to do some reading below.
The process is currently manual: you will be sending all of your assets to the new address(es), one transaction at a time. If you're unfamiliar with sending assets, see here.
Note: We are currently in the process of getting up-to-date tooling to help automate this process. The tools listed in the section further down may or may not work for you, and are not endorsed or affiliated with MetaMask. When we have a better process in place, we will update this article.
Your network gas tokens (ETH, POL (previously MATIC), etc.) should be the LAST THING YOU TRANSFER. Otherwise, you'll have no way to pay for the transfer fees of your other assets.
- Start with NFTs
- NFTS are likely to be the most expensive to transfer, so start with these. Currently, you can use MetaMask Mobile to transfer them; also, you can use OpenSea's transfer function.
- Keep in mind: if your account has been compromised, then adding more of the network's gas token to your account in order to transfer assets out of it may result in the new gas token balance being "swept out" before you can take any actions. If this is the case, see here.
- NFTS are likely to be the most expensive to transfer, so start with these. Currently, you can use MetaMask Mobile to transfer them; also, you can use OpenSea's transfer function.
- Move on to other ERC-20 tokens
- Gas Tokens: First in, Last out. Depending on the contents of your accounts and the network you're on, you may use a significant amount of the network gas token--so don't send it away while you still need it!
- Remember, ETH isn't technically an ERC-20 token, so automated ERC-20 sweeping tools may not automatically include balances of ETH.
Note: If you transferred an ENS name to your new address, and you use that ENS name to receive cryptoassets, make sure you update the routing information in the ENS app so that assets routed to that ETH name go to the new address, and not the old one!
Step Five: Switch networks and repeat
Yup, you guessed it: we live in a multi-chain era, which means that if you've got assets on multiple chains, they have to be transferred on those chains.
- Use the network switcher to change networks
- Follow steps 1-3
Help! I don't even know what stuff I have, and where it's at!
We totally understand. It's easy to end up with stakes in lots of protocols, all over the decentralized web.
Take a look at the section below, titled "What assets do I have?"; it will give you a good start.
Step Six: Did you remember your private keys?
Many MetaMask users have imported certain accounts from other SRPs into MetaMask. These accounts ARE NOT "backed up" by the SRP. They WILL NOT be restored by importing your SRP into another instance of MetaMask. You MUST ENSURE you have access to the SRP or other mechanism that produced them.
That said--if it was your SRP that was compromised, and not your system environment itself, then imported private keys may be safe.
If your SRP or wallet has been compromised, it is possible that you have had a sweeper bot placed on your account. If this is the case, then as soon as you transfer tokens in, they may be transferred to the attacker's address. This can be a complex situation to remedy; for much more detailed information, see here. See also the section below on Flashbots Whitehats.
If you do have a sweeper bot on your account, or think you may, keep an eye on the suspicious address using Blocknative's mempool explorer.
Background information on SRPs and account migration
Try to keep this mental model in mind:
Wallet = the MetaMask software
Secret Recovery Phrase = 12 or 24 words that, when imported into a wallet, produce the same accounts every time, as well as the private keys that control access to those accounts
Account = Derived from an SRP; holds cryptoassets on a blockchain network
Address = The public address (a long string of characters, generally beginning with 0x) of an account to which assets can be sent
To transfer assets from one account to another, you will need to pay some gas fees, as these transactions are occurring on-chain. Depending on the amount you own in assets and the contracts storing or managing those assets, this can become costly.
You can use previous gas data to try to determine when is generally the best time to do these transactions so you are not overpaying, and you can broadcast the signed transactions with a lower gas price to see if they get included in a block sometime soon.
An important step you should take before you begin is to write down your assets in priority order so you are aware of what you are moving and can account for all variables (ie: token lockups, contract-backed taxes on transferring assets).
Some of the assets you may need to transfer ownership of are:
- ERC-20 tokens
- NFTs (ERC-721, ERC-1155)
- Liquidity provider positions
- Ownerships on smart contracts (i.e.: gnosis-safe)
As most assets on-chain make use of a standard interface for each type of asset (for the most part), it doesn’t need to be too complicated to move assets.
What assets do I have?
Over time you can come into ownership of various assets under your address and you might lose track of which assets you have. Below are some tools you can use to get a list of assets you own.
MetaMask
You can make use of the MetaMask interface to see which assets you have, especially if you’ve imported custom tokens.
You can see an expanded view of your account by clicking the three dots ("⋮") in the top right and choosing the “Expand view” option.
From the new tab that will appear, you can select the “Assets” tab and see your assets in a larger view. From here, you can make a list of your priority assets to move.
MetaMask Portfolio Dapp
If you want a more complete overview, the MetaMask-affiliated Portfolio Dapp will automatically detect and display most common assets. Check out its NFT tab, which shows a very complete listing of NFT-type tokens held by your accounts.
Marketplaces
Various marketplaces such as OpenSea and LooksRare index your NFT assets on your profile page. You can see your assets on these marketplaces and evaluate which NFTs are a priority. Also, if for some reason you can't transfer an NFT from within MetaMask, you can use the tools on these platforms.
Indexers
You can make use of a blockchain indexer/block explorer to see your address and related transactions.
Keep in mind that in today's multi-chain world, you'll want to look at your address on multiple chains. Blockscan has a handy tool for this; paste the public address in question into the search bar here, and you'll be provided with links to block explorers on all chains on which the account has been active.
Aggregators
There are many different aggregators that index the blockchain to build a database of what assets an address holds - including assets in lockup and liquidity positions. The MetaMask Portfolio Dapp, mentioned above, fulfils exactly this function (and more!). Some alternatives include:
You'll notice, if you've gotten involved broadly in DeFi, that no one aggregator has everything. In order to be sure that you've "exited all your positions", it may help to visit several tools and see if there's anything you've missed.
Contract Tools
Some tools are available to help you semi-automate the finding of what contracts you have created which could have the Ownable pattern (or another similar pattern) for you to transfer ownership, as well as tools to help to search known contract function signatures.
- @msilb7/Get-Contracts-by-Creator-Address-Ethereum-Optimism
- Harry Denley’s MyContracts (Find contracts directly created by an address)
- 4byte.directory (Contract function signature database; click 'Go to website')
What tools can I use to move assets?
Please note: These tools may not currently be functional. We are in the process of sourcing a tool that is up-to-date and functional. Additionally, we are providing you links to these tools as a point of reference, and this is in no way endorsement from MetaMask or Consensys. Before using any of these tools, please familiarize yourself with their README files.
409H/eoa-migrator (https://github.com/409H/eoa-migrator)
This tool offers an interface to help you step through the process of migrating funds and discovering different asset types on your address. It is strict in that for you to access the tool, you will need to confirm ownership of the keys you are transferring the assets to.
svanas/migratooor (https://github.com/svanas/migratooor)
Written in Pascal, this tool offers a user interface to migrate funds from one address to another. It does provide compile instructions and offers you an executable to download in the releases.
Eth-sweep (https://github.com/James-Sangalli/eth-sweep)
Written in JavaScript, eth-sweep allows you to sweep your tokens by transfer to a safe address, swap them for ETH, or migrate tokens to L2.
Flashbots Whitehat (http://whitehat.flashbots.net)
If you believe your address is compromised and bad actors are watching the txpool to frontrun any transactions you may make with these tools, you can open a case with the Flashbots Whitehat team to help you create transaction bundles to skip the txpool.
Technical notes
We know that sweeping all of the assets from an account can be expensive, but Ethereum currently requires that all contract calls from an Externally Owned Account are individual transactions. To reduce these costs long term, we look forward to protocol changes like EIP-3074, which could allow batched transactions or even changing a controlling key with a single transaction. This could greatly reduce the cost of migrating to a new secret recovery phrase. You can get a sense of how much ether could be saved just by batching approvals on https://www.approvals.wtf/.
Need help with any of this?
If you're looking to migrate your assets to a new account and need advice or assistance, we’re here to help. If you need help using one of the specific tools we’ve listed above, it is recommended that you reach out to the maintainers of that tool first, but you are still welcome to contact MetaMask Support.
As always, please keep your Secret Recovery Phrase safe. It is for your eyes and your eyes alone, and when you ask for help in various places there may be bad actors waiting to reach out to you and attempt to steal your funds.