Skip to content

Commit 4a54959

Browse files
alexander-seiclaude
andcommitted
docs: explain SIP-03 migration for mnemonic-only and hardware wallets
Adds a "Migrating a hardware or mnemonic-only wallet" section to the SIP-03 migration guide for users whose wallet can't hand them a usable raw private key. Covers: - Why raw private-key export always works (the key carries no coin type) but exporting a mnemonic does not (re-derived at coin type 60 in EVM wallets), and Ledger exports nothing — you can only switch between the Cosmos (118) and Ethereum (60) apps. - The workaround: create a new EVM account, fund it (~0.1 SEI for the association tx), associate it on the Sei Dashboard to reveal its paired sei1 address, then send old Cosmos funds there (1 SEI test first), so the assets land on a key the user controls via EVM. - A matching FAQ entry pointing to the new section. Also fixes a dead anchor: the USDC.n FAQ linked to #3-usdc-on-sei, but the heading is "### 2) USDC on Sei" (#2-usdc-on-sei). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent a775b4f commit 4a54959

1 file changed

Lines changed: 43 additions & 2 deletions

File tree

learn/sip-03-migration.mdx

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: 'SIP-03 Migration Guide'
33
sidebarTitle: 'SIP-03 Migration'
44
description: 'Practical steps and resources for users and exchanges migrating during SIP-03, including asset transfer, USDC, and exchange migration guidance.'
5-
keywords: ['SIP-03', 'migration', 'asset transfer', 'USDC on Sei', 'Keplr', 'Leap', 'Compass', 'EVM wallet', 'exchange migration', 'FundsForwarder', 'address association']
5+
keywords: ['SIP-03', 'migration', 'asset transfer', 'USDC on Sei', 'Keplr', 'Leap', 'Compass', 'EVM wallet', 'exchange migration', 'FundsForwarder', 'address association', 'Ledger', 'hardware wallet', 'mnemonic', 'private key export', 'coin type 118', 'coin type 60']
66
---
77
<Danger>
88

@@ -90,6 +90,43 @@ Native USDC and Circle's CCTP V2 are now supported on Sei. USDC from Noble (USDC
9090

9191
- Wind down and withdraw your positions **before** migrating to native USDC. Failure to do so before the SIP-03 upgrade may result in inability to access your supplied assets.
9292

93+
## Migrating a hardware or mnemonic-only wallet
94+
95+
The recommended migration is to export the raw private key from your Cosmos wallet and import it into an EVM wallet. This works in every case, because a private key is independent of coin type and produces the same `0x...` and `sei1...` addresses in any wallet that holds it.
96+
97+
This section covers the cases where a raw private key is not available: wallets that export only a recovery phrase, and hardware wallets such as Ledger that export nothing and only allow switching between apps. In those cases, create a new account in an EVM wallet you control, associate it to reveal its paired Cosmos (`sei1...`) address, and send your existing funds to that address with a standard Cosmos transfer. The original key is never moved; the assets are transferred to a new account that is already EVM-native.
98+
99+
### When private-key export isn't an option
100+
101+
A raw private key always works, but two common setups do not provide one:
102+
103+
- **Mnemonic-only wallets.** Some wallets back up only a recovery phrase, not a raw private key. Sei's Cosmos (`sei1...`) accounts use coin type 118 (`m/44'/118'/0'/0/0`). Importing the same phrase into an EVM wallet such as MetaMask derives it on coin type 60 (`m/44'/60'/0'/0/0`), producing a different account with no access to the original funds. The underlying private key would import correctly if the wallet exposed it, but a mnemonic-only wallet does not.
104+
- **Hardware wallets (such as Ledger).** A Ledger does not export the private key or seed under any circumstances. It only allows switching between the Cosmos app (coin type 118) and the Ethereum app (coin type 60), which control separate accounts with different addresses. The Cosmos-app account cannot be used from an EVM wallet.
105+
106+
For background, see [HD Paths and Coin Types](/learn/accounts#hd-paths-and-coin-types).
107+
108+
### Migration steps
109+
110+
Every account has exactly one EVM (`0x...`) address and one Cosmos (`sei1...`) address, both derived from the same key. The procedure below creates a new EVM account, reveals its Cosmos address, and routes the existing assets to it.
111+
112+
1. **Create a new account in an EVM wallet you control.** MetaMask, Compass, Rabby, or a Ledger running its Ethereum app are all suitable. This produces a new `0x...` address.
113+
2. **Fund the new `0x...` address with a small amount of SEI.** Roughly 0.1 SEI is sufficient. Association is an on-chain transaction, so the account requires SEI for gas. Fund it from an exchange withdrawal or from any EVM wallet that already holds SEI.
114+
3. **Associate the new account on the [Sei Dashboard](https://dashboard.sei.io).** Connect the new EVM account and complete address association. This records the public key on-chain and links the `0x...` address to its `sei1...` counterpart. The dashboard then displays the linked `sei1...` address, which is the destination for the next step. See [Account Linking](/learn/accounts) for details on association.
115+
4. **Send a test transfer of 1 SEI.** From the original Cosmos wallet (Keplr, Leap, the Ledger Cosmos app, and so on), send 1 SEI to the `sei1...` address from step 3. This is a standard Cosmos-to-Cosmos transfer.
116+
5. **Confirm receipt.** Because the addresses are associated, the test amount should appear under the new account on the dashboard and as a spendable balance in the EVM wallet.
117+
6. **Transfer the remaining balance.** Once the test transfer is confirmed, send the rest of the funds the same way. The assets are then held by an account whose key you control from an EVM wallet.
118+
119+
<Warning>
120+
Send the 1 SEI test transfer and confirm receipt before moving the full balance. Verify that the destination matches the exact `sei1...` address shown after association in step 3.
121+
</Warning>
122+
123+
### Notes and limitations
124+
125+
- **Complete this before the SIP-03 upgrade.** After the Cosmos interface is deprecated, addresses can no longer be associated and `sei1...` transfers can no longer be broadcast. Steps 3 and 4 must be completed beforehand.
126+
- **This procedure moves liquid balances only.** Staked SEI must be unbonded first, and the unbonding period is 21 days. See the staking question in the [FAQ](#faq).
127+
- **Associate before sending.** Associating the new account before transferring ensures the funds arrive at the correct, immediately spendable address rather than a temporary holding address.
128+
- **Optional verification.** To confirm the paired `sei1...` address independently, call `getSeiAddr(0x...)` on the `addr` precompile. See [Query Linked Addresses](/learn/accounts#query-linked-addresses).
129+
93130
## FAQ
94131

95132
### I am a Keplr / Leap wallet user; do I need to do anything?
@@ -100,6 +137,10 @@ Yes. Use the Asset Transfer tool to ensure your assets are available via an EVM
100137

101138
No action needed. Compass ensures your assets are available via EVM. Continue connecting to Sei like any EVM chain.
102139

140+
### My wallet only shows a recovery phrase, or I use a Ledger — how do I migrate?
141+
142+
If you can export a raw private key, import it into an EVM wallet. This always works, because the key reproduces the same addresses in any wallet. If you cannot (a wallet that exports only a recovery phrase, or a Ledger that only switches between apps), create a new account in an EVM wallet you control, fund it with a small amount of SEI, associate it to reveal its paired `sei1...` address, and send your existing Cosmos funds to that address. Send a 1 SEI test transfer first. See [Migrating a hardware or mnemonic-only wallet](#migrating-a-hardware-or-mnemonic-only-wallet) for the full procedure.
143+
103144
### I stake SEI — do I need to do anything?
104145

105146
It depends on whether your Cosmos (`sei1...`) and EVM (`0x...`) addresses are **associated (linked)**. Staking on Sei is handled by the Cosmos staking module. After SIP-03, Cosmos-native transaction interfaces will no longer be available — but the underlying staking state is preserved and accessible via EVM for associated addresses.
@@ -120,4 +161,4 @@ To check whether your addresses are linked, see [Query Linked Addresses](/learn/
120161

121162
### I hold USDC.n (USDC via Noble) — what should I do?
122163

123-
You must swap or migrate your USDC.n to native USDC before the SIP-03 upgrade (expected end of March 2026). After the upgrade, USDC.n may become inaccessible or lose its value on Sei. See the [USDC on Sei](#3-usdc-on-sei) section above for swap and migration options, or read the full announcement: [Holders of USDC.n Need to Swap or Migrate](https://blog.sei.io/announcements/holders-of-usdcn-need-to-swap-or-migrate/).
164+
You must swap or migrate your USDC.n to native USDC before the SIP-03 upgrade (expected end of March 2026). After the upgrade, USDC.n may become inaccessible or lose its value on Sei. See the [USDC on Sei](#2-usdc-on-sei) section above for swap and migration options, or read the full announcement: [Holders of USDC.n Need to Swap or Migrate](https://blog.sei.io/announcements/holders-of-usdcn-need-to-swap-or-migrate/).

0 commit comments

Comments
 (0)