Keplr Wallet Extension: Custom Token Import Guide for New Cosmos Projects and Testnets

A developer launching a new token on a Cosmos-based chain, or an early adopter testing assets on a testnet, faces a practical problem: the token may not appear in the default Keplr wallet extension interface. Major tokens are pre-configured, but custom or newly issued assets require manual addition. The configuration process itself is straightforward—chain ID, token denomination, and decimal places—yet the details matter. A single error in chain identification or denomination format can cause the wallet to display incorrect balances, fail to send the asset, or create confusion about which version of a token is being held.

The Keplr wallet extension and its companion apps provide strong foundational security through non-custodial architecture and private key control, but that foundation only works correctly if the user understands what token they are actually managing. This guide covers the precise steps required to add custom tokens to your Keplr wallet, the information you must gather before starting, and the verification process that confirms the token is configured correctly. Whether you are working with Osmosis pool tokens, Secret Network assets, or experimental chains, the same methodology applies: gather metadata, configure systematically, and verify against the blockchain before moving significant value.

Understanding the metadata required for custom token import

Before opening the Keplr wallet extension or app, you must identify three core pieces of information: the chain ID, the token’s on-chain denomination, and the decimal places. These are not arbitrary choices; they correspond to how the blockchain itself defines the asset. The chain ID is a unique identifier for a specific blockchain—for example, “cosmoshub-4” for Cosmos Hub mainnet or “osmo-test-5” for Osmosis testnet. If you enter the wrong chain ID, the wallet will attempt to use the token on an entirely different network, producing either an error or a false balance.

The token denomination is the asset’s raw identifier on the blockchain. This is not the ticker symbol or trading name; it is the exact string the chain uses internally. On Cosmos Hub, the native token is “uatom” (microATOM). On Osmosis, the governance token is “uosmo” (microOsmosis). For custom tokens, the denomination might be something like “ibc/27394FB092D2ECCD56123C74F36F7B01B87149A6375FAEFC38B6D9A65F45F8C8” if the token is bridged, or “factory/osmo1pfye5r8wdvv2jvx46n5hx63e2genxretg464azm4cjyltre2r2ys7yc627/MUFFIN” for a factory token on Osmosis. Copy the exact denomination string from the blockchain documentation, token contract details, or chain explorer rather than guessing based on how the token is marketed.

Decimal places determine how the wallet displays the token. Most Cosmos tokens use 6 decimals, meaning 1,000,000 of the smallest unit equals 1 token. This is why “uatom” means microATOM—the “u” prefix indicates 10^-6. Some tokens use different decimal counts: 8 decimals (like Bitcoin), 18 decimals (like Ethereum tokens), or other values. If you set decimals incorrectly, the wallet may show a balance of 0.000001 when you actually hold 1 token, or vice versa. This creates confusion during transfers and can lead to accidentally sending far more or less than intended.

Gathering this information before you open the Keplr wallet extension prevents unnecessary back-and-forth and reduces the risk of configuration errors. The best sources are the official project documentation, the blockchain’s mainnet or testnet explorer, or the JSON-RPC endpoint configuration files published by the chain. If you are working with a newly deployed token, the project team should provide this data explicitly. Do not rely on rumors, forum posts, or screenshots unless they can be cross-verified against the chain itself.

Accessing the custom token import interface in Keplr

The Keplr wallet extension, available as a Chrome extension or through the Keplr iOS and Android apps, includes a token import feature. On the web extension, navigate to the main wallet view and locate the “Add Token” or similar button, usually near the top of the assets list or within a menu. The exact interface may vary slightly between the Chrome extension version and the mobile app, but the underlying process is consistent. Some versions may require you to first select the blockchain you are adding the token to, while others may provide a dropdown menu to choose the chain after opening the import dialog.

On the Chrome extension, you typically click on the wallet interface, look for a menu or settings icon, and find “Add Token” or “Import Token.” Mobile apps may use a “+” icon or a dedicated token management section. Once you open the import dialog, you will see fields for chain selection, the denomination, and other metadata. The interface should clearly indicate which chain you are configuring for—this is your first verification point. Confirm that the dropdown is set to the correct network before proceeding further.

If you cannot find the token import feature in your version of the wallet, check that your Keplr wallet extension or app is up to date. The Keplr team periodically refines the interface and may have moved the feature or renamed it in recent updates. You can verify your version in the extension settings or app details. If you are testing on a testnet and it is not immediately visible in the chain list, it may need to be added through a testnet enablement setting or a separate configuration import process.

Entering chain ID, denomination, and decimal configuration

Once the import dialog is open and you have selected the correct chain, you will enter the token denomination. This field is case-sensitive and must match exactly. If the documentation specifies “uosmo”, entering “UOSMO” or “Uosmo” will not work. Copy the denomination directly from the authoritative source, or if you must type it manually, verify it character by character. A missing letter or extra space is enough to cause the wallet to fail to recognize the token or to misidentify which asset you are holding.

Next, you will set the decimal places. If the token documentation states “6 decimals,” enter 6 in that field. If you are unsure, the safest approach is to check the token’s smart contract code or the JSON RPC endpoint’s token metadata. For Cosmos SDK chains, you can query the chain directly if you have command-line access: a command like “gaiad query bank balances [address]” will show your balance in the raw denomination and help you reverse-engineer the decimals by comparing what the chain reports to what the wallet should display. Do not guess; an incorrect decimal count creates lasting confusion about how much you actually own.

Some custom tokens may require additional fields depending on the wallet version. For example, if the token is an IBC token (bridged from another chain), the import dialog may ask for the IBC hash or a source chain confirmation. The Keplr wallet extension usually handles much of this automatically if the token is already known to the ecosystem, but newly deployed or testnet tokens may not have pre-existing IBC paths. In those cases, consult the project’s documentation or ask the development team for the exact configuration string to use.

After filling in the denomination and decimal fields, double-check each entry before confirming. Some interfaces allow you to see a preview of how the token will be displayed; review it to ensure the balance and unit name look correct. If the preview shows an unexpectedly high or low number, cancel, and recheck the decimals. Once you confirm, the token should appear in your wallet’s asset list.

Verifying the token appears with correct balance and network

After importing, the token should appear in your Keplr wallet extension’s main asset list. The first check is visual: confirm that the token name, symbol (if available), and decimal representation match what you expect. If you own 1 OSMO and the wallet displays “1.000000 OSMO,” the decimals are correct. If it shows “0.000001 OSMO” or “1000000.000000 OSMO,” the decimal count is wrong and needs to be corrected.

The second check is network alignment. The token should only appear under the chain you imported it to. If you intended to add a token to Osmosis testnet but it appeared under Cosmos Hub mainnet, the chain ID is incorrect. Most Keplr wallet extension versions clearly label which network you are viewing, so switching between chains will help you confirm the token is in the right place. If it is on the wrong network, delete the import and try again with the correct chain ID.

The third check is balance verification. If you already hold the token on-chain, your wallet should display that balance after import. You can cross-verify this by checking a blockchain explorer. Visit mintscan.io or a similar explorer for your chain, search for your wallet address, and look for the token in the assets section. The balance shown on the explorer should match what appears in your Keplr wallet (accounting for any precision differences in how explorers display decimals). If the explorer shows 100 tokens but Keplr shows a different amount, something in the configuration is wrong.

If the balance is zero but you know you own the token, the issue may be that the denomination is incorrect, the chain selection is wrong, or the token has not yet been indexed by the wallet’s balance-fetching system. Wait a few seconds and refresh the wallet. If the balance still does not appear, delete the import and verify the denomination and chain ID against the official source one more time.

Common configuration errors and how to fix them

One frequent mistake is confusing the token’s display name with its denomination. For example, a token might be called “Muffin” in the user interface but have a denomination of “factory/osmo1pfye5r8wdvv2jvx46n5hx63e2genxretg464azm4cjyltre2r2ys7yc627/MUFFIN”. If you enter “muffin” or “MUFFIN” instead of the full factory string, the wallet will not recognize it. Always use the on-chain denomination, not the marketing name.

Another common error is using a testnet denomination on mainnet or vice versa. Testnet tokens and mainnet tokens are separate assets, even if they share the same name. If you are testing a token on “osmo-test-5” (Osmosis testnet), the denomination will only work on that testnet. If you then switch to mainnet expecting to see the token, it will not appear because the asset does not exist there. This is actually a safety feature—it prevents accidental mainnet transfers—but it requires discipline to remember which network you are on.

Decimal errors are often discovered only after a transaction. If you set decimals to 18 instead of 6 and then try to send 1 token, the wallet may calculate the transaction as if you are sending 1 million tokens (10^12 more than intended). Always verify decimals before making transfers. Most blockchain explorers and chain documentation state decimal counts explicitly; there is no reason to guess.

IBC tokens can be particularly tricky because the denomination string is a hash rather than a readable name. If you are importing an IBC token and the denomination looks like “ibc/ABC123DEF456…”, ensure you have copied it exactly from the IBC relayer documentation or an official source. A single character transposition will cause the wallet to treat it as a different asset. If you are uncertain, ask the token project or the IBC bridge operator for the exact denomination to use.

If you make a mistake, you can usually delete the token from your wallet and re-add it with the correct configuration. On the Keplr wallet extension, this is typically as simple as clicking a remove or trash icon next to the token, or accessing a token management menu. After deleting, verify that the token is gone from your asset list, then re-import with the correct details. This does not affect your on-chain balance; it only changes how your wallet displays the asset.

Using custom tokens on testnets and development networks

Testnets are the primary environment for testing token configurations before deploying to mainnet. If you are a developer or early adopter working with a testnet token, the same import process applies, but with more emphasis on verification. Testnet tokens often change or are reset; it is common for a testnet to be wiped and restarted, which means any balance you held will disappear when the network resets.

For testnet work, confirm the current testnet chain ID before importing. A chain might cycle through versions like “osmo-test-4” and “osmo-test-5″—using an outdated chain ID will cause the token to import on the wrong version of the testnet. The Keplr wallet extension and apps typically include testnet networks in their default chain list, but you can verify by checking the official chain documentation or asking the project team.

When testing custom tokens on a development network, you can often mint or transfer tokens to yourself using the project’s tools or a faucet. After the token appears in your account on-chain, import it into Keplr and verify the balance matches. This test confirms that the denomination and decimal configuration are correct. Only after successful testnet verification should you proceed to a mainnet token deployment or import using the same denomination and decimal settings.

Testnets are also where you should test token transfers and interactions before using mainnet assets. A misconfigured token on mainnet could result in sending funds to an unintended destination or losing track of your balance. By working through the same configuration and transfer process on a testnet first, using testnet tokens with no real value, you can build confidence that your setup is correct.

Security implications of custom token import

Adding a custom token does not change the security of your Keplr wallet extension or apps; your private keys remain offline and encrypted. However, importing a token that is not officially recognized or verified by the Keplr team introduces an indirect risk. If you import a token based on fraudulent denomination data, you may end up believing you own an asset that you do not actually hold. An attacker could provide false configuration information, causing you to send funds to a wrong address or wait indefinitely for a non-existent balance.

The safest approach is to verify custom token information through multiple independent sources. If you are importing a token for a new project, check the official project website, GitHub repository, and community channels such as Discord. Cross-verify the denomination and decimal count against at least two authoritative sources. If information conflicts or seems suspicious, do not proceed with the import or transfer.

For tokens launched on public testnets or announced in official channels, the risk is lower because the information is typically verifiable against the blockchain itself. You can always check a block explorer for the token’s properties, smart contract code (if applicable), or transaction history. This on-chain verification is the strongest guarantee that the token actually exists and behaves as documented.

When using custom tokens, avoid importing tokens from unknown sources or unverified projects. The Keplr wallet extension cannot validate whether a custom token configuration corresponds to a legitimate asset or a scam. The validation responsibility falls on you, the user. Take the time to verify before importing, and always test with small amounts before transferring significant value. You can access the official keplr wallet / keplr wallet extension / keplr wallet download page to ensure you have the legitimate version of the wallet before importing any tokens.

Best practices for managing multiple custom tokens

If you work regularly with multiple custom tokens—perhaps you are testing several projects or participating in early-stage DeFi protocols—develop a system for tracking which tokens are configured on which networks. A simple spreadsheet with columns for token name, denomination, decimal places, chain ID, and deployment date can prevent confusion. When you return to a wallet after weeks or months away, this reference prevents you from re-importing the same token or using the wrong configuration.

Name your imported tokens clearly within the wallet if the interface allows it. Some versions of the Keplr wallet extension may let you add custom labels or notes. Using descriptive names such as “OSMO-testnet-v2” or “IBC-ATOM-from-Juno” helps you immediately recognize which asset and network you are viewing. This becomes particularly valuable if you manage wallets across multiple chains and need to quickly identify which token is which.

Regularly audit your token list to remove outdated or testnet imports. Clutter makes it easier to make mistakes, especially if you accidentally send mainnet funds to a testnet chain because the token lists look similar. After a testnet is retired or a token is no longer needed, delete it from your Keplr wallet extension. This keeps your asset list clean and reduces the cognitive load when reviewing your holdings.

If you are working with IBC tokens across multiple chains, pay close attention to the token representation on each chain. The same token may have different denominations when transferred via IBC to different destinations. A token might exist as “factory/chain-a/token” on one chain and as “ibc/hash-value” on another. These are technically the same underlying asset, but they have different on-chain representations. Import each version separately for each network where you use them, and remember that moving a token between chains requires an IBC transfer, not a simple local transaction.