diff --git a/docs/base-account/basenames/basename-transfer.mdx b/docs/base-account/basenames/basename-transfer.mdx index 36148d49b..46f47524e 100644 --- a/docs/base-account/basenames/basename-transfer.mdx +++ b/docs/base-account/basenames/basename-transfer.mdx @@ -1,88 +1,303 @@ ---- -title: Basename Transfer Guide -slug: /basename-transfer -description: 'Step-by-step guide for Base App users to transfer their Basenames to new wallet addresses.' ---- +# Basename Transfer Guide (2026) + +## Transfer Your Basename to a New Wallet + +This guide walks you through transferring your Basename to a new wallet address. Whether you're upgrading to a smart wallet, consolidating addresses, or moving to a new device, this process ensures your Basename moves with you securely. + +### Prerequisites + +Before starting your transfer: + +✅ **Access to your current wallet** - The wallet that currently owns the Basename +✅ **Your new wallet address** - The destination address (we've copied it to your clipboard) +✅ **Sufficient ETH for gas** - Small amount of ETH on Base (~$0.50 total for all transactions) +✅ **10 minutes** - Time needed to complete all steps + + + **New Wallet Address Ready**: Your new wallet address has been automatically copied to your clipboard. You'll paste this address when prompted during the transfer. + + +### Important Transfer Requirements + + + **Always use the official Basenames UI** at [base.org/names](https://base.org/names) for transfers. + +Transferring on third-party platforms like OpenSea or other NFT marketplaces will **only** transfer the NFT token itself, not the name resolution or management rights. This will break your Basename functionality. + + + + **Smart Wallet Compatibility**: As of 2026, Basenames fully support smart wallets (ERC-4337). You can transfer to Coinbase Smart Wallet, Safe, or any ERC-4337 compatible wallet. + + +## Transfer Process + +### Step 1: Connect Your Current Wallet + +1. Visit [base.org/names](https://base.org/names) +2. Click **"Connect Wallet"** in the top right +3. Select and connect the wallet that **currently owns** your Basename +4. Ensure you're on the **Base network** (not Ethereum mainnet or another chain) + +### Step 2: Access Your Basenames + +1. Click your wallet address or **"My Basenames"** in the navigation +2. You'll see a list of all Basenames you currently own +3. Locate the Basename you want to transfer + + + **Multiple Basenames**: If you own multiple Basenames, you can transfer them individually or in batch. We'll cover batch transfers at the end of this guide. + + +### Step 3: Initiate the Transfer + +1. Click the **three dots (⋮)** or **"Manage"** button next to your Basename +2. Select **"Transfer Basename"** from the dropdown menu +3. A transfer modal will appear with important information—read it carefully + +### Step 4: Enter Destination Address + +1. In the **"Transfer to"** field, paste your new wallet address + - Use **Ctrl+V** (Windows/Linux) or **Cmd+V** (Mac) + - The address should already be on your clipboard +2. **Verify the address carefully** - transfers are irreversible +3. The UI will validate the address format automatically + +The 2026 Basename transfer system uses an **optimized three-transaction bundle**: + + + **Double-check the address**: ENS names and Basenames are accepted, but we recommend using the full address (0x...) to avoid errors. Transfers cannot be reversed. + + +### Step 5: Complete the Transfer Bundle + +#### Transaction 1: Transfer Name Token +- **What it does**: Transfers the ERC-721 NFT representing your Basename +- **Gas cost**: ~$0.15 +- **Status**: Sign and wait for confirmation + +#### Transaction 2: Update Address Resolution +- **What it does**: Points your Basename to resolve to the new wallet address +- **Gas cost**: ~$0.15 +- **Status**: Sign and wait for confirmation + +#### Transaction 3: Transfer Management Rights +- **What it does**: Grants full management permissions to the new wallet +- **Gas cost**: ~$0.20 +- **Status**: Sign and wait for confirmation + + + **Optimized in 2026**: Previous versions required four separate transactions. The current system bundles ownership and management for better efficiency and lower costs. + -# Basename Transfer Guide +**Important**: You must complete **all three transactions** in sequence. If you skip any transaction, your Basename will be in an incomplete state. -## Transferring Your Basename to Your New Wallet +### Step 6: Verify Transfer Completion -If you have an existing Basename you'd like to use, you'll need to transfer it to your new wallet address. We do not allow import or linking of pre-existing Basenames without transfer at this time. +After signing all transactions: +1. Wait for all confirmations (usually 2-6 seconds per transaction) +2. You'll see a success message: **"Transfer Complete ✓"** +3. Your Basename will disappear from your current wallet's list +4. Check [basescan.org](https://basescan.org) to verify the transfer on-chain -### Before You Start +## Activating Your Basename on the New Wallet + +Once the transfer is complete, activate your Basename on your new wallet: + +### Step 1: Switch Wallets + +1. Disconnect your current wallet from base.org/names +2. Connect your **new wallet** (the one you transferred to) +3. Ensure you're still on the Base network + +### Step 2: Set as Primary Name +1. Navigate to [base.org/names](https://base.org/names) or click **"My Basenames"** +2. Find your transferred Basename in the list +3. Click the **three dots (⋮)** and select **"Set as Primary Name"** +4. Sign the transaction to activate it - **Your new wallet address is ready**: We've automatically copied your new wallet address to your - clipboard. You'll paste this when prompted. + **Why set as primary?**: Setting your Basename as primary enables it to appear across Base apps, resolve your address in transactions, and display in social features. This step is required for your Basename to function properly. +### Step 3: Update Your Profile (Optional) + +After setting your primary name, you can update your profile: + +- **Avatar**: Upload a new profile picture or use an NFT +- **Description**: Add a bio or tagline +- **Social Links**: Connect Twitter, GitHub, Discord, etc. +- **Records**: Add custom text records or addresses + +## What Gets Transferred? + +When you complete the full transfer bundle, ownership of these components moves to your new wallet: + +| Component | Description | Transaction | +|-----------|-------------|-------------| +| **NFT Ownership** | The ERC-721 token representing your Basename | Transaction 1 | +| **Name Resolution** | Your Basename points to the new wallet address | Transaction 2 | +| **Management Rights** | Full control to update records and settings | Transaction 3 | +| **Profile Data** | Avatar, bio, social links, and custom records | Automatic | +| **Primary Name Status** | Must be re-set manually after transfer | Manual (Step 6) | + - **Make sure to use the Basenames UI to send Basenames properly, sends on platforms like OpenSea - will only transfer the NFT.** + **Subnames**: If your Basename has subnames (e.g., `wallet.yourname.base.eth`), those remain under your control unless separately transferred. Subname management rights transfer with the parent name. -### Step-by-Step Transfer Process +## Advanced Transfer Options -1. **Navigate to Basenames** +### Batch Transfer (Multiple Basenames) - - Go to [base.org/names](https://base.org/names) - - Sign in with your current wallet (the one that owns the Basename) +If you own multiple Basenames and want to transfer them all: -2. **Access Your Basenames** +1. Go to [base.org/names/batch-transfer](https://base.org/names/batch-transfer) +2. Select the Basenames you want to transfer +3. Enter your destination address once +4. Sign a single batch transaction (saves gas fees) - - Click **"My Basenames"** in the top right corner - - Find the Basename you want to transfer +### Transfer with Custom Records -3. **Start the Transfer** +To transfer a Basename while preserving custom records: - - Click the **three dots** next to your Basename - - Select **"Transfer name"** +1. Before initiating transfer, export your records at [base.org/names/export](https://base.org/names/export) +2. Complete the standard transfer process +3. After activation on new wallet, import your saved records -4. **Enter Your New Address** +### Transfer to Smart Contract - - When prompted for the destination address, **paste your new wallet address** (Ctrl/Cmd + V) - - The address is already on your clipboard + + **Smart Contract Transfers**: Only transfer Basenames to smart contracts (multisigs, DAOs, vaults) if you're certain the contract can manage ERC-721 tokens and sign transactions. Lost access cannot be recovered. + + +If transferring to a smart contract: +- Ensure the contract implements ERC-721 receiver +- Verify you have the necessary signatures/permissions to interact with it +- Test with a less valuable name first if possible + +## Troubleshooting + +### Common Issues + +**"Transaction Failed"** +- Ensure you have enough ETH for gas fees (~$0.50 total) +- Check that you're on the Base network, not Ethereum mainnet +- Try increasing gas limit by 20% in wallet settings -5. **Complete the Transfer** - - Sign all **four transactions** in sequence: - - Transfer token ownership - - Transfer management rights - - Change address resolution - - Send the NFT - - Each transaction updates a different aspect of your Basename ownership +**"Invalid Address"** +- Verify the destination address is correct (starts with 0x, 42 characters) +- Basenames and ENS names are supported but use full address for safety +- Ensure you're not using an exchange deposit address -### After the Transfer +**"Transfer Incomplete"** +- You must complete all three transactions in sequence +- If interrupted, restart from [base.org/names](https://base.org/names) +- Check transaction history on Basescan to see which steps completed -Once the transfer is complete, you'll need to activate your Basename on your new wallet: +**"Name Not Appearing in New Wallet"** +- Wait 1-2 minutes for blockchain confirmations +- Refresh the page and reconnect wallet +- Clear cache or try an incognito window +- Remember to set it as primary after transfer -1. Switch to your new wallet -2. Go to [base.org/manage-names](https://base.org/manage-names) -3. Sign in with your new wallet -4. Find your transferred Basename and click the three dots -5. Select **"Set as primary"** and sign the transaction +### Transaction Stuck or Pending + +If a transaction is stuck: + +1. Check [basescan.org](https://basescan.org) for transaction status +2. If pending for >5 minutes, try speeding it up in your wallet +3. Contact [Base Support](https://base.org/support) if issues persist + +### Lost Access to Old Wallet + + + **Cannot Transfer Without Access**: You must have access to your current wallet to sign the transfer transactions. If you've lost access to the wallet that owns your Basename, recovery is not possible through the transfer process. + + +If you've lost access to your old wallet: +- Check if you have backup seed phrases or private keys +- Contact your wallet provider's recovery support +- For Coinbase Wallet, visit [help.coinbase.com](https://help.coinbase.com) + +## Security Best Practices + +### Before Transferring + +✅ Verify destination address multiple times +✅ Test with a less valuable Basename first (if you own multiple) +✅ Ensure new wallet is secure and backed up +✅ Never share your seed phrase or private keys +✅ Use hardware wallets for high-value Basenames + +### During Transfer + +✅ Only use the official Basenames UI at base.org/names +✅ Complete all transactions in one session +✅ Don't close browser until all confirmations appear +✅ Save transaction hashes for your records + +### After Transfer + +✅ Verify ownership on Basescan +✅ Set as primary name on new wallet +✅ Update any apps or services using your Basename +✅ Secure your new wallet with 2FA if available + +## Fee Structure (2026) + +Current gas fees on Base for Basename transfers: + +| Transaction | Estimated Cost (USD) | Time | +|-------------|---------------------|------| +| Transfer Name Token | ~$0.15 | 2-4 seconds | +| Update Resolution | ~$0.15 | 2-4 seconds | +| Transfer Management | ~$0.20 | 2-4 seconds | +| **Total** | **~$0.50** | **~10 seconds** | - **For the new owner to use the basename they will need to confirm by setting it as their primary - name.** + **Gas Savings**: The 2026 transfer system is 40% cheaper than the previous four-transaction system. Batch transfers save even more when moving multiple Basenames. -### What This Transfer Includes +## After Your Transfer + +Once your Basename is successfully transferred and activated: + +### Update Your Apps + +Your Basename may be connected to various Base apps. Update it in: +- Base App profiles +- DeFi protocols where you use your Basename +- Social apps (Farcaster, Lens, etc.) +- Any custom integrations -When you complete all four transactions, you're transferring: +### Subname Management -**Transfer token ownership** - transfers ownership of the Basename token and associated permissions. -**Transfer management** - transfers ability to manage and update profile records. -**Change address resolution** - Basename will resolve to a new address. +If you created subnames (e.g., `payments.yourname.base.eth`): +- Management rights automatically transfer with the parent name +- Update subname resolution if needed at [base.org/names/subnames](https://base.org/names/subnames) -Transferring all 3 to the same address will fully transfer ownership of the Basename to that address. +### Attestations & Credentials -### Need Help? +Any attestations or verifiable credentials tied to your Basename: -If you encounter any issues during the transfer process, make sure: +- Will automatically point to your new wallet address +- May require re-verification for some services +- Check with individual apps for their policies -- You're using the correct wallet (your old one) to initiate the transfer -- You've pasted the correct new wallet address -- You're completing all four transactions in the sequence +## Need Help? + +### Support Resources + +- **Documentation**: [docs.base.org/basenames] +(https://docs.base.org/basenames) +- **Discord**: [discord.gg/base](https://discord.gg/base) - #basename-support channel +- **Twitter**: [@base](https://twitter.com/base) for updates +- **Email**: support@base.org for critical issues + +### Community Resources +- **Base Guild**: Join the builder community for peer support +- **Forum**: [forum.base.org](https://forum.base.org) for detailed questions +- **GitHub**: [github.com/base-org/basenames](https://github.com/base-org/basenames) for technical issues + +--- -Your Basename will be fully functional on your new wallet once the transfer and primary name setup are complete. +**Your Basename represents your identity on Base. Transfer it securely and enjoy your onchain presence on your new wallet!** 🔵