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
Keplr Wallet Extension: Custom Token Import Guide for New Cosmos Projects and Testnets Read More »
