How to Add a Custom Token to a Sui Wallet

Understanding Custom Token Integration

1. Sui Wallet does not automatically detect or display all tokens deployed on the Sui blockchain.

2. Tokens must be explicitly registered in the wallet’s token list using their on-chain identifier, known as the Object ID of the coin type.

3. The coin type follows a strict format: 0x[address]::[module]::[struct], where each segment is derived from the Move package deployment.

4. Users cannot add arbitrary strings—only valid, deployed, and verified coin types recognized by the Sui network are accepted.

5. Failure to match the exact case, spacing, or module path results in rejection during token addition.

Prerequisites for Manual Addition

1. A fully synced Sui Wallet extension or mobile app with an active account.

2. Access to the token’s official documentation or explorer page confirming its coin type ID.

3. Confirmation that the token contract has been published on the mainnet or targeted network, not just devnet or testnet.

4. Ownership of at least one instance of the token object in the user’s address, verified via sui client objects CLI command.

5. Knowledge of whether the token implements the Coin interface correctly—custom structs lacking proper Coin trait adherence will not appear in balances.

Step-by-Step Token Registration

1. Open the Sui Wallet interface and navigate to the Tokens tab.

2. Tap or click the + Add Token button located in the top-right corner.

3. Select Custom Token instead of searching through the default list.

4. Paste the full coin type string into the input field—no truncation or aliasing permitted.

5. Confirm network compatibility; the wallet will validate the type against the current connected network (e.g., mainnet vs. testnet).

6. Upon successful validation, the token symbol, name, and decimal precision are auto-fetched from on-chain metadata.

7. Click Add to finalize registration and trigger balance synchronization.

Verification and Visibility Issues

1. After adding, check the Assets view—tokens may take up to 30 seconds to reflect if the node is under load.

2. If the token remains invisible, verify the object ownership using sui client objects --address [your-address] in CLI.

3. Cross-check the coin type against the Sui Explorer by pasting the Object ID into the search bar and inspecting the package structure.

4. Ensure no trailing whitespace or invisible Unicode characters were copied alongside the coin type string.

5. Disable any third-party browser extensions that interfere with wallet injection or script execution.

Frequently Asked Questions

Q: Can I add a token without owning any of it?A: No. The wallet requires at least one owned instance of the coin object to populate balance data. Adding a token without ownership results in zero balance and no transaction history.

Q: Why does my custom token show “Unknown” as the name?A: This occurs when the on-chain package lacks metadata publishing or the name and symbol fields are empty in the Move module’s CoinMetadata struct.

Q: Is it safe to paste a coin type from an untrusted source?A: Not inherently unsafe—the coin type itself is immutable and public—but verifying its origin prevents accidental addition of maliciously named clones or reentrancy-prone variants.

Q: Do I need to re-add the token after updating my wallet version?A: No. Token configurations are stored locally in encrypted wallet storage and persist across updates unless manually cleared or the wallet data is reset.