Every token on Solana has a mint address, but that address alone tells you nothing about what the token actually is. The name, symbol, image, description, and any additional attributes -- all of that information is stored separately as metadata. On Solana, the dominant standard for token metadata is the Metaplex Token Metadata program. Understanding how this standard works is essential whether you are building a token, creating an NFT collection, or simply trying to understand what you are looking at when you inspect a token on an explorer.
This guide explains how Solana token metadata works, what gets stored on-chain versus off-chain, how to create and update metadata, and what tools are available for working with it.
What Is Token Metadata?
Token metadata is the human-readable information attached to a token mint. Without metadata, a token is just a cryptographic address -- a long string of characters with no context. Metadata transforms that address into something meaningful by associating it with:
- Name -- the full name of the token (e.g., "Jupiter")
- Symbol -- the ticker symbol (e.g., "JUP")
- URI -- a link to a JSON file containing extended metadata like images and descriptions
- Seller fee basis points -- royalty percentage for NFTs
- Creators -- list of creator addresses and their shares
- Collection -- for NFTs, the parent collection it belongs to
This metadata is what allows wallets, explorers, DEXes, and other applications to display token names, logos, and descriptions instead of raw addresses.
On-Chain vs. Off-Chain Metadata
One of the most important concepts to understand is the split between on-chain and off-chain metadata. Solana's Metaplex standard uses a hybrid approach.
What Lives On-Chain
The Metaplex Token Metadata program creates a Program Derived Address (PDA) for each token mint. This PDA account stores the following data directly on the Solana blockchain:
| Field | Description | Stored On-Chain |
|---|
| Name | Token name (up to 32 chars) | Yes |
| Symbol | Token ticker (up to 10 chars) | Yes |
| URI | Link to off-chain JSON | Yes |
| Seller Fee | Royalty in basis points | Yes |
| Creators | Array of addresses + shares | Yes |
| Collection | Parent collection mint | Yes |
| Uses | Consumable use tracking | Yes |
| Primary Sale Happened | Whether first sale occurred | Yes |
| Is Mutable | Whether metadata can be updated | Yes |
| Update Authority | Address that can modify metadata | Yes |
The metadata PDA address is derived deterministically from the token mint address using seeds: ["metadata", metaplex_program_id, mint_address]. This means anyone can compute the metadata address for any token mint without querying the chain first.
What Lives Off-Chain
The URI field in the on-chain metadata points to a JSON file hosted externally. This JSON file follows a standard schema and typically contains:
{
"name": "Token Name",
"symbol": "TKN",
"description": "A detailed description of the token and its purpose.",
"image": "https://arweave.net/abc123...",
"external_url": "https://example.com",
"attributes": [
{ "trait_type": "Category", "value": "DeFi" }
],
"properties": {
"files": [
{ "uri": "https://arweave.net/abc123...", "type": "image/png" }
]
}
}
This off-chain JSON is where the token image, detailed description, and any custom attributes live. The JSON file itself is typically hosted on decentralized storage like Arweave or IPFS, though some projects use centralized hosting.
Why the Split?
Storing large data like images directly on Solana would be prohibitively expensive. Solana charges rent for account storage, and even a small image would cost hundreds of SOL to store on-chain. The hybrid approach keeps costs low -- the on-chain metadata PDA is typically around 600-700 bytes -- while still allowing rich metadata through the off-chain JSON.
The trade-off is that off-chain metadata depends on the hosting service remaining available. If an Arweave gateway goes down or a centralized server is shut off, the image and description become inaccessible even though the on-chain data remains. This is why decentralized storage is strongly recommended for the URI target.
The Metaplex Token Metadata Program
The Metaplex Token Metadata program (address: metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s) is the standard on Solana. Nearly every token and NFT uses it. The program provides several key instructions:
CreateMetadataAccountV3
This instruction creates the metadata PDA for a token mint. It requires:
- The mint address
- The mint authority signature
- The payer account
- The update authority address
- The metadata fields (name, symbol, URI, etc.)
For fungible tokens, this is typically called once right after creating the mint. For NFTs, it is called as part of the minting process.
UpdateMetadataAccountV2
If the metadata is marked as mutable (is_mutable: true), the update authority can modify the metadata fields using this instruction. Common use cases include:
- Updating the URI to point to a new off-chain JSON (e.g., for a token rebrand)
- Changing the name or symbol
- Transferring the update authority to a new address
- Setting
is_mutable to false to permanently lock the metadata
Once metadata is set to immutable, it cannot be changed. This is an irreversible action and is often done for NFTs to guarantee the metadata will never be altered.
Other Instructions
The program also includes instructions for verifying creators, setting and verifying collections, utilizing the "uses" feature, and working with programmable NFTs (pNFTs) that enforce royalties at the protocol level.
