A standardized JSON schema for retrieving and verifying off-chain metadata (profile, visual assets, and links) for crypto assets, with built-in support for cross-chain identity discovery.
This proposal defines a minimal, chain-agnostic JSON structure for asset metadata. It addresses the fragmentation of token information across Web3 by standardizing how wallets and dApps fetch essential data (logo, name, symbol, decimals) and extended data (links, cross-chain locations). The standard prioritizes URI-based resource referencing and introduces a "locations" field to map a single asset's existence across multiple blockchains using CAIP-19 identifiers.
Currently, asset metadata is fragmented across various repositories (Coingecko, CoinMarketCap, TrustWallet Assets, Tokenlists.org), each using proprietary JSON structures.
twitter, social_twitter, x_url), requiring complex parsing logic.We propose a unified schema that is compatible with existing NFT standards (ERC-721/OpenSea) while adding specific support for fungible token needs and cross-chain peer discovery.
The metadata MUST be returned as a JSON object. The schema is defined as follows:
decimals: This field is mandatory. For NFTs or non-divisible assets, it MUST be set to 0. This eliminates ambiguity for consumers (wallets) regarding whether a value is missing or intentionally zero.external_url: Used instead of "website" to maintain compatibility with existing NFT metadata standards (e.g., OpenSea).links ObjectTo prevent key-name fragmentation (e.g., twitter_url vs socials.twitter), links are defined as an array of objects containing a mandatory rel attribute.
Recommended values for rel:
homepage: Main project website.whitepaper: Technical paper or economic model.documentation: Developer docs or wikis.source_code: Code repositories (GitHub, GitLab).governance: Voting portals or forums.audit: Security audit reports.social: Social media profiles (X/Twitter, Discord, Telegram).browser: Block explorer links.exchange: Direct links to trading pairs on DEXs or CEXs (e.g., Uniswap Pool, Binance Spot).bridge: Interfaces allowing users to bridge this asset across chains.locations (Cross-Chain Discovery)This field allows an asset to declare its "peer" contracts on other networks. The value MUST be an array of valid CAIP-19 strings.
USDT token on Ethereum mainnet can list its representations on BNB Chain and Solana in this field.We opted for a single image URI string rather than a complex object containing thumbnails or themes. Modern UI frameworks and CDNs handle image resizing and format negotiation efficiently. Sticking to a single string simplifies the parsing logic for wallets.
Arbitrary keys in a JSON object (e.g., "twitter": "...") lead to a chaotic ecosystem where consumers must maintain a mapping of thousands of non-standard keys. Using a structured array with a rel property enforces a controlled vocabulary while allowing flexibility for new types in the future.
Existing token lists often treat bridged assets as separate entries. By including locations, we embed the "cross-chain graph" directly into the asset's metadata. We use CAIP-19 because it is the standard for uniquely identifying asset instances in a multi-chain environment.
name, description, image, and external_url aligns with the widely adopted OpenSea metadata standard.external_url or links. We recommend displaying the domain clearly to the user before redirection.image field to prevent XSS attacks via embedded scripts.Copyright and related rights waived via CC0.