How to manually add token icons in MetaMask?

MetaMask users can manually add token icons by updating custom token lists or using developer tools to improve recognition of unsupported ERC-20 tokens.

Jun 12, 2025 at 03:49 am

What is MetaMask and Why Would You Need to Add Token Icons?

MetaMask is a popular cryptocurrency wallet that allows users to interact with the Ethereum blockchain. It supports not only Ether (ETH) but also various ERC-20 tokens. While many commonly used tokens automatically display their icons within the MetaMask interface, some lesser-known or newly launched tokens may not show an icon, making them harder to identify at a glance.

Manually adding token icons helps improve usability by ensuring each token has a recognizable visual representation. This is particularly useful for users who manage multiple tokens regularly. If you're encountering a token without an icon, it's likely because MetaMask hasn't indexed the token’s metadata yet, or the token developers haven’t submitted it for inclusion in public repositories.

How Does MetaMask Display Token Icons?

MetaMask pulls token information from several sources, including CoinGecko and community-maintained token lists such as those found on GitHub repositories like tokenlists.org. When a token is added to a user's wallet, MetaMask attempts to fetch its symbol, name, and icon from these sources. If the data isn't available, the token appears with a generic placeholder icon.

The icon itself is typically stored as a URL pointing to an image file hosted online. For MetaMask to display the correct icon, the token contract address must be associated with this image URL in one of the recognized token lists. Manually adding a token icon involves updating one of these lists or configuring your local wallet to recognize the custom icon path.

Steps to Manually Add a Token Icon via Custom Token List

To manually add a token icon in MetaMask, one method involves creating or modifying a custom token list JSON file that includes the icon URL for the desired token. Here's how:

• Ensure you have the token contract address and the icon URL ready.

• Create a new JSON file or modify an existing one following the format:

  {
    "name": "Custom Token List",
    "logoURI": "https://example.com/icon.png",
    "timestamp": "2024-03-15T12:00:00Z",
    "tokens": [
  {
    "chainId": 1,
    "address": "0x...",
    "symbol": "TKN",
    "name": "Token Name",
    "decimals": 18,
    "logoURI": "https://example.com/tkn-icon.png"
  }
  ]
  }

• Save the file and upload it to a publicly accessible server or hosting service (e.g., GitHub Pages).

• In MetaMask, go to Settings > Advanced > Manage Token Lists.

• Click Add Token List, and paste the URL of your hosted JSON file.

• Confirm and reload MetaMask if necessary.

After completing these steps, your custom token icon should now appear alongside the token name in your wallet.

Adding a Token Icon Without Modifying Token Lists

If you prefer not to deal with external token lists, you can manually override the token icon within your MetaMask instance using developer tools. This method applies only to your local installation and won't affect other users.

• Open MetaMask and ensure the token you want to customize is already added.
• Right-click on the MetaMask extension in your browser and select Inspect to open Developer Tools.
• Navigate to the Application tab, then under Local Storage, find the entry for metamask-controller-state.
• Locate the tokens section and find the token object corresponding to the contract address.
• Within the token object, add a new key-value pair: "iconUrl": "https://example.com/tkn-icon.png".
• Reload MetaMask to see the updated icon.

This approach requires some familiarity with browser developer tools and is not persistent across devices or sessions unless backed up.

Where Can You Find Token Icons for Manual Addition?

Finding the correct icon for a specific token is essential when manually adding it to MetaMask. The most reliable sources include:

• Official token websites: Most projects host high-quality icons on their official sites.
• GitHub repositories: Many token developers maintain assets, including icons, in public repositories.
• Community-driven token lists: Platforms like tokenlists.org often contain verified icon URLs for various tokens.
• Third-party asset directories: Some services aggregate token metadata and offer downloadable icons.

Before using an icon URL, ensure it points directly to a .png file and is publicly accessible without authentication. Using broken or unauthorized links may result in icons failing to load or being blocked by MetaMask.

---

Frequently Asked Questions (FAQ)

Q: Can I use any image format for a token icon in MetaMask?

MetaMask primarily supports .png files for token icons due to their transparency support and wide compatibility. Using other formats like .jpg or .svg may result in display issues or unsupported rendering.

Q: Will manually added token icons stay after updating MetaMask?

Icons added through local modifications (like editing Local Storage) may reset after updates or cache clearing. However, icons added via custom token lists are preserved as long as the list remains active and unchanged.

Q: Is there a size requirement for token icons in MetaMask?

While there’s no strict size requirement, it's recommended to use square images of at least 64x64 pixels for clarity. Larger sizes (e.g., 256x256) are preferred for high-resolution displays.

Q: Can I submit my token's icon to be included in MetaMask's default list?

Yes, you can submit your token to platforms like CoinGecko or Uniswap’s token list for broader recognition. Submitting to these services increases the likelihood of automatic icon detection in MetaMask without manual intervention.