Token Metadata APIs: Identity, Decimals and Search
Build token lookup and search around stable asset identities while treating names, symbols and images as descriptive metadata.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A token metadata API supplies the descriptive context that turns a contract identifier into a readable asset entry. Names, symbols, decimal precision and images help users navigate wallets and token search screens. They also introduce assumptions that applications need to manage deliberately.
The central design problem is separating an asset's identity from the information used to describe it. A changed logo should update a presentation field. It should not create a different asset, merge unrelated contracts or rewrite the quantities already associated with a record.
Build the identity before the display label
Use a network-qualified contract reference as the starting point for a contract token. A familiar symbol is not a unique identifier. Two contracts can publish the same symbol, and similar address formats can appear on different networks.
Keep the original contract representation alongside any documented canonical form. Search, cache keys, export rows and transaction details should preserve that qualification. A frontend that fetches a network-specific asset but caches it only by symbol can still display another asset's metadata. Follow the identity through every consumer rather than checking only the database schema. Display shortening should never become the identifier used for storage or comparison.
Handle optional metadata without inventing values
The ERC-20 specification makes name, symbol and decimals optional descriptive methods. A token can therefore require a more careful presentation than a record whose fields are always assumed to exist.
Represent missing, failed and confirmed observations distinctly. A missing name can fall back to a shortened contract reference. An unavailable decimal observation should not silently become eighteen. Keep retrieval status and observation time with the metadata so a later refresh can explain why the description changed. This also lets an application retry one unresolved field without discarding the confirmed identity and other useful observations.
Use decimal precision to format an exact quantity
An integer quantity and its decimal scale are different pieces of information. Retain the integer as an exact string or suitable integer type, then apply the documented scale for display. Formatting a value should not overwrite the original quantity.
Consider a synthetic quantity of 1234500 atomic units with six decimals. The formatted amount is 1.2345 units. A display rounded to 1.23 can be convenient, but an export or comparison still needs the exact original. If the decimal field is unresolved, explain that formatting is unavailable instead of presenting an apparently precise amount based on a guessed scale. Store display preferences separately from asset observations.
Make token search useful under ambiguous names
Accepting a name, symbol or contract address creates different search intents. An exact contract lookup should prioritize the correctly qualified asset. A symbol search should return distinguishable candidates rather than treating the first result as an authoritative match.
Include the network, contract reference and relevant descriptive fields in each result. Retain the reason for a match and the scope of the search. A query over one network is not a global discovery result. Test a name shared by multiple contracts, a renamed token and an exact address without descriptive metadata. These cases reveal whether the interface communicates ambiguity and preserves the selected identity.
Treat remote metadata and images as untrusted content
A useful image does not establish that an asset is legitimate. Keep media retrieval separate from token identity and avoid interpreting a polished logo as evidence of safety or endorsement. Descriptions can contain misleading claims or arbitrary markup.
Use an explicit media policy: allowed schemes, bounded download sizes, supported types and a controlled rendering path. Apply the same boundaries when metadata is fetched from a URI rather than a contract method. A failed image can use a neutral placeholder while the asset record remains available. The IPFS CID documentation provides context for content-addressed references and their distinct identity rules.
Refresh descriptive fields without rewriting the record
Metadata can be corrected, become unavailable or change at its origin. Keep a clear observation time and preserve enough revision context to explain meaningful changes. An updated description should not alter the network or contract identity attached to past activity.
Define separate refresh behavior for a current cache and a reproducible export. A search result may use the latest accepted metadata, while an earlier report may need the description observed when it was prepared. Test missing decimals, conflicting symbols, a broken image, an updated name and a repeated request. A practical integration remains useful even when attractive descriptive fields are incomplete.
Questions about the topic
Frequently asked questions
Are token symbols unique?
No. A symbol is descriptive metadata. Use the network and applicable contract or native-asset identifier to distinguish assets, and preserve that identity in search results and exports.
Can an application assume eighteen decimals?
Only when a documented asset-specific contract establishes that scale. Optional or failed metadata should remain unresolved; a convenient default can produce a materially incorrect displayed quantity.
Should a missing logo hide the token?
Usually the media and asset states should remain separate. A neutral placeholder preserves access to confirmed identity and quantity without implying that an image or description is verified.
Standards & technical documentation
