NFT Metadata Guide
Complete guide for creating OpenSea-compatible NFT metadata on Base
What is NFT Metadata?
Metadata is the JSON data that describes your NFT's properties, including its name, description, image, and attributes (traits). This data is stored off-chain (usually on IPFS) and referenced by your smart contract's tokenURI.
Properly formatted metadata ensures your NFTs display correctly on OpenSea, Rarible, and other marketplaces.
Basic Metadata Structure
{
"name": "My NFT #1",
"description": "A detailed description of this NFT",
"image": "ipfs://QmXxx.../1.png",
"external_url": "https://yourwebsite.com/nft/1",
"attributes": [
{
"trait_type": "Background",
"value": "Blue"
},
{
"trait_type": "Rarity",
"value": "Legendary"
},
{
"trait_type": "Power Level",
"value": 95,
"display_type": "number",
"max_value": 100
}
]
}Required Fields
name
The NFT's display name
"My NFT #1"description
Detailed description (supports markdown)
"A detailed..."image
IPFS URI or HTTPS URL
"ipfs://..."Attributes (Traits)
String Attributes
For text-based traits like "Hat", "Background", etc.
{
"trait_type": "Hat",
"value": "Top Hat"
}Numeric Attributes
For stats and scores with optional max_value
{
"trait_type": "Speed",
"value": 85,
"display_type": "number",
"max_value": 100
}Date Attributes
For timestamps (Unix timestamp)
{
"trait_type": "Birthday",
"value": 1672531200,
"display_type": "date"
}Boost Attributes (OpenSea)
For gaming NFTs with stat boosts
{
"trait_type": "Attack Boost",
"value": 10,
"display_type": "boost_percentage"
}Recommended File Structure
project/
├── images/
│ ├── 0.png
│ ├── 1.png
│ ├── 2.png
│ └── ...
└── metadata/
├── 0.json
├── 1.json
├── 2.json
└── ...Each JSON file corresponds to a token ID. Token #0 → 0.json, Token #1 → 1.json, etc.
Upload Process (IPFS)
Upload Images Folder
Upload your entire images folder to IPFS using Pinata or NFT.storage
Result: ipfs://QmImageHash/Update Metadata Files
Edit all JSON files to point to the IPFS image URLs
"image": "ipfs://QmImageHash/0.png"Upload Metadata Folder
Upload the metadata folder to IPFS
Result: ipfs://QmMetadataHash/Set Base URI in Contract
Use the metadata IPFS hash as your baseURI when deploying
baseURI = "ipfs://QmMetadataHash/"Collection-Level Metadata (Optional)
For enhanced collection display on OpenSea, create a contract.json file:
{
"name": "My NFT Collection",
"description": "A collection of unique NFTs",
"image": "ipfs://QmXxx.../logo.png",
"external_link": "https://yourwebsite.com",
"seller_fee_basis_points": 500,
"fee_recipient": "0xYourAddress"
}Common Issues & Solutions
NFT not showing on OpenSea
Wait 10-15 minutes for indexing, then click "Refresh Metadata" on OpenSea
Image not loading
Check IPFS gateway accessibility. Try different gateways: gateway.pinata.cloud, ipfs.io
Traits not displaying correctly
Ensure exact spelling: "trait_type" (not "traitType") and "display_type" for numeric values