Token Metadata Standards
Metadata standards ensure your tokens can be properly displayed and interpreted by wallets, marketplaces, and other applications. This guide explains how to structure metadata for different token types on Ettios.
Why Metadata Matters
Properly structured metadata makes your tokens compatible with all major platforms and improves user experience. Standardized metadata enables wallets to display token information consistently and allows your tokens to be easily listed on marketplaces.
ERC-721 Metadata (NFTs)
The metadata for NFTs typically follows the ERC-721 Metadata JSON Schema. It's served via the tokenURI function which returns a URL to a JSON file with the following structure:
{
"name": "Asset Name",
"description": "Detailed description of the asset",
"image": "https://example.com/image.png",
"external_url": "https://example.com/asset/123",
"attributes": [
{
"trait_type": "Color",
"value": "Blue"
},
{
"trait_type": "Size",
"value": "Large"
},
{
"trait_type": "Rarity",
"value": "Legendary",
"display_type": "string"
},
{
"trait_type": "Level",
"value": 5,
"display_type": "number"
},
{
"trait_type": "Power",
"value": 75,
"max_value": 100,
"display_type": "boost_percentage"
},
{
"trait_type": "Unlocked Date",
"value": 1632501274,
"display_type": "date"
}
]
}Required and Optional Fields
Required Fields
- name: The name of the asset
- description: A human-readable description of the asset
- image: A URI pointing to the asset's image
Recommended Fields
- external_url: URL to view the asset on your site
- attributes: Traits/properties of the asset (important for filtering and sorting)
- animation_url: URI for multi-media attachments (for 3D models, videos, etc.)
- background_color: Background color when previewing the NFT (hex format, no #)
Attribute Display Types
The display_type field in attributes controls how the trait is displayed in compatible marketplaces:
Standard Displays
- string (default): Displayed as simple text
- number: Displayed as a number
- boost_percentage: Displayed as a percentage with a progress bar
- boost_number: Displayed as a number with a progress bar
- date: Unix timestamp converted to a date display
Marketplace Examples
- OpenSea: Supports all display types listed
- Rarible: Supports most display types
- LooksRare: Displays traits but with limited formatting options
- Ettios Marketplace: Supports all standard display types
ERC-1155 Metadata
For ERC-1155 tokens, the metadata format is similar to ERC-721 but uses a base URI plus token ID pattern and includes a decimal field for fungible tokens:
{
"name": "Gold Coin",
"description": "A gold coin used for in-game purchases",
"image": "https://example.com/images/gold-coin.png",
"decimals": 18,
"properties": {
"category": "currency",
"rarity": "common",
"max_supply": 1000000
}
}The ERC-1155 standard also supports batch operations, so the metadata structure allows for both fungible and non-fungible tokens within the same contract.
For Fungible Tokens (e.g., ID: 0)
{
"name": "Gold Coin",
"description": "In-game currency",
"image": "https://example.com/gold.png",
"decimals": 18
}For Non-Fungible Tokens (e.g., ID: 1)
{
"name": "Legendary Sword",
"description": "Unique weapon",
"image": "https://example.com/sword.png",
"attributes": [
{"trait_type": "Attack", "value": 150}
]
}Metadata Storage Solutions
Where and how you store your metadata is critical for the long-term accessibility and permanence of your tokens:
IPFS (Recommended)
InterPlanetary File System is a decentralized storage network that uses content addressing instead of location addressing. This ensures your metadata remains accessible as long as at least one node in the network has it pinned.
Example URI: ipfs://QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/1.json
Arweave
Arweave provides permanent storage for a one-time fee. Data is stored indefinitely through a novel consensus mechanism and economic structure.
Example URI: ar://AcuH5BdC_ib67Z2LQz2h2sptto5XmmPvYdCvLLDCGsA/1.json
On-Chain Storage
Storing metadata directly on the blockchain ensures the highest level of permanence, but comes at a much higher gas cost. Suitable for small metadata or high-value tokens where permanence is critical.
Implementation: The token contract itself stores and returns metadata, eliminating external dependencies.
Important Warning
Never store metadata on centralized servers without a migration plan.If your server goes down or your company ceases operations, NFT metadata could be permanently lost, rendering the tokens essentially worthless. Always use decentralized storage solutions like IPFS or Arweave for production tokens.
Best Practices
📝 Comprehensive Documentation
Include detailed descriptions and accurate attributes. This improves marketplace discoverability and user experience.
🔄 Multiple Image Formats
Provide both high-resolution images for detailed viewing and optimized thumbnails for faster loading. Consider including SVG versions for scalable display across different platforms.
🎭 Consistent Attribute Names
Use consistent naming conventions for attributes across your entire collection to enable proper filtering and sorting.
💾 Multiple Storage Solutions
Consider using multiple storage solutions (e.g., both IPFS and Arweave) for critical tokens to enhance resilience.
Metadata Gateways
When using decentralized storage systems like IPFS, you often need to use a gateway to serve the content to users who don't have IPFS nodes:
// IPFS URI
ipfs://QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/1.json
// Gateway URLs for the same content
https://ipfs.io/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/1.json
https://gateway.pinata.cloud/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/1.json
https://cloudflare-ipfs.com/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/1.json
https://nftstorage.link/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/1.jsonAlways store and reference the canonical URI (ipfs://) in your smart contracts, even if you use gateways in your frontend applications. This ensures that the content remains accessible even if specific gateways become unavailable.
Next Steps
Now that you understand metadata standards, you might want to explore: