Understanding Token Management in Web3 Wallets
When users access their OKX Web3 Wallet, they see a comprehensive display of digital assets including various tokens. While the wallet automatically detects and displays major tokens, most alternative tokens require manual addition by the user.
Traditional methods of adding tokens through UI buttons can be cumbersome and potentially risky due to direct contract interactions. The wallet_watchAsset API (defined in EIP-747) offers a more secure and user-friendly alternative.
How to Programmatically Add Tokens
Implementing the wallet_watchAsset API
Here's the complete implementation for adding ERC-20 tokens to user wallets:
const tokenAddress = '0xd00981105e61274c8a5cd5a88fe7e037d935b513';
const tokenSymbol = 'TUT';
const tokenDecimals = 18;
const tokenImage = 'http://placekitten.com/200/300';
try {
const wasAdded = await okxwallet.request({
method: 'wallet_watchAsset',
params: {
type: 'ERC20',
options: {
address: tokenAddress,
symbol: tokenSymbol,
decimals: tokenDecimals,
image: tokenImage,
},
},
});
if (wasAdded) {
console.log('Token successfully added!');
} else {
console.log('User declined token addition');
}
} catch (error) {
console.error('Error adding token:', error);
}👉 Learn more about wallet integration best practices
Key Parameters Explained
| Parameter | Description | Example |
|---|---|---|
| address | The token's contract address | 0xd009...b513 |
| symbol | Token ticker (max 5 chars) | TUT |
| decimals | Token divisibility | 18 |
| image | URL of token logo | http://.../logo.png |
Practical Applications
Several live implementations demonstrate this functionality:
- Token sharing via generated links
- DEX integration workflows
- Custom token onboarding flows
👉 Explore advanced Web3 wallet features
FAQ: Token Management in Web3 Wallets
Q: Why doesn't my token appear automatically?
A: Wallets only auto-detect major tokens to avoid clutter. Less popular tokens require manual addition.
Q: Is wallet_watchAsset safe to use?
A: Yes, it simply adds view permissions without granting spending approvals.
Q: Can I add non-ERC20 tokens?
A: Currently only ERC-20 is supported, but future updates may include other standards.
Q: What happens if I enter wrong token details?
A: The wallet will display incorrect information. Always verify contract details.
Q: How can users remove added tokens?
A: Removal is handled through the wallet's UI, not programmatically.
Best Practices for Token Integration
- Verify contract addresses - Always use official sources
- Optimize token images - Use square format (200x200px recommended)
- Provide clear instructions - Guide users through the addition process
- Handle errors gracefully - Account for various rejection scenarios
For developers building DEX applications or Web3 integrations, proper token management significantly improves user experience while maintaining security standards.