How do I migrate from one federation to another?

"Migrating" to a new federation is a bit of a misnomer as it simply refers to the process of joining a new federation and moving your entire wallet balance, including any Stable Balance & Multispend funds, from the original federation before leaving it. 

Funds are never moved on their own, so migration is a manual process that you must complete if a federation you belong to is closing or nearing its end date, has regular reliability issues, or if you've simply found another one that better suits your needs.

Before you start, update the Fedi app to the latest version, which you can find in What is in the latest version of the Fedi app? Following the update, write down or take a screenshot of your balances in the original federation so you can check that all funds arrive in the new one.

Step 1: Join the New Federation

The first step is to join the new federation you will be "migrating" your funds and activity to. To do so:

1. Tap the Scan/Paste button at the bottom center of the screen. 
2. Scan or paste the invite code of the federation you'd like to join; then tap Continue.
3. If you don't have a specific federation in mind, you can choose one featured in the Discover tab.
4. To do this, tap the + at the top right of the Wallet tab and tap Join next to your federation of choice.
5. Review the federation's welcome message & terms of service (if any); then tap Join Federation.

Note – You should only use invite codes from sources you trust, such as your original federation's official announcement channels, a close friend, or the Discover tab. That said, no federation listed in the Discover tab is specifically endorsed by or related to Fedi.

Step 2 (As Applicable): Withdraw from Multispend Groups

For Multispend groups where the underlying shared wallet is provided by the original federation, funds will have to be withdrawn if the original federation is closing. Funds in these wallets are not part of your personal balance, so you will have to request the share you'd like to withdraw (more on this here). 

Your request will have to be approved by a threshold of the group's voters. Once this happens, the funds will be returned to your Stable Balance in your wallet provided by the original federation.

Note – Withdrawals need the approval of the group's voters, so start this step early. If your group wants to keep using Multispend, create a new group in the new federation once everyone has moved.

Step 3 (As Applicable): Move Funds from Stable Balance

The next step is to transfer any funds you may have in the Stable Balance of the original federation's wallet back to your Bitcoin balance. To do so:

1. In the Wallet tab, navigate to the wallet provided by your original federation.
2. Toggle from Bitcoin to USD (or other display fiat currency) to bring up your Stable Balance.
3. Tap ↑ Send and ensure that To my BTC wallet is selected at the top of the screen.
4. Enter the amount of your entire Stable Balance (denominated in fiat) and tap Send.
5. Review the details if desired; then tap Withdraw and subsequently Okay.

Note – Moving funds from Stable Balance to your Bitcoin balance can take up to 10 minutes. You can check the status of the transfer in your transaction history.

Step 4: Transfer your Entire Bitcoin Balance On-Chain

Fedi recommends moving your balance on-chain for reliability, as on-chain transfers settle directly on the Bitcoin network and don't depend on Lightning routing.

1. On the Wallet tab, navigate to the new federation and tap ↓ Receive on your Bitcoin Balance.
2. Toggle to On-chain at the top of the Receive Bitcoin screen; tap Copy to copy the Bitcoin address.
3. Back on the Wallet tab, switch to the original federation and tap ↑ Send on your Bitcoin Balance.
4. Tap Paste at the bottom of the screen & enter the amount of your entire Bitcoin balance.
5. Ensure the original federation is the sending wallet & tap Continue; tap Send on the next screen.

Note – There is no "Max Send" button. If you enter more than you can send once fees are taken into account, the app shows "The max you can send is X sats" in red. Tap the amount in that message to autofill the amount that will allow you to move your entire balance. Proceed with the transaction.

Keep in mind the following when moving funds on-chain:

• On-chain sends carry a 0.5% Fedi fee, a variable network fee, and any fees charged by the guardians of the original federation. Receiving on-chain also carries a 1,000 sat peg-in fee, which is deducted from the amount that arrives in the new federation.
• Send the funds within 24 hours of creating the address, and use each address for one deposit only.
• Deposits need 11 confirmations before they're credited to your new balance, which may take up to several hours. You can follow the status in your transaction history.

Because these fees don't scale down with the amount, they take a larger share of a small balance, and on-chain sends also have a minimum amount that the app shows if you go below it. For small amounts, or if On-chain is unavailable in the new federation, you can move your funds over Lightning instead (see How do I move funds between federations?).

Step 5 (If Desired): Deposit into New Stable Balance

1. On the Wallet tab, switch to the new federation and toggle from Bitcoin to USD (or other display currency).
2. Tap ↓ Receive and, if you see a bar at the top, choose From my BTC wallet.
3. Enter the amount you want to deposit (denominated in fiat) and tap Next.
4. Review the details and fees on the next screen and then tap Deposit.

Note – Deposits to Stable Balance may take up to 10 minutes to complete. You can check the status of the deposit in your transaction history.

Step 6: Download your Transaction History

Leaving a federation removes its transaction history from your device, and the history doesn't carry over to the new federation. Before you leave, and before the original federation's end date, download a copy of each history as a CSV file:

• Wallet history: tap your profile icon at the top right of any tab to access the Settings screen, tap the original federation under Federations and select Export transactions to CSV.
• Multispend history (if applicable): open the group chat, tap Multispend, tap the Transactions List icon and then tap the Export icon at the top right. Repeat this for each Multispend group in the original federation.

For more detail, see How can I see and download my wallet transaction history? and How can I see and download my Multispend group transactions?

Step 7 (If Desired or Necessary): Leave the Original Federation

Once your funds have arrived and you've downloaded your history, compare your balances in the new federation with the numbers you noted at the start, and check that your Bitcoin, Stable Balance and Multispend balances in the original federation are empty.

1. Tap your profile icon at the top right of any tab to access the Settings screen.
2. Scroll to the original federation, tap its name to display options and tap Leave Federation.
3. Tap Yes on the pop-up asking if you are sure you'd like to leave the federation.

Note – The app doesn't stop you from leaving a federation that still holds funds, so make sure your balance has been moved before you tap Leave Federation.