Token Metadata
Metaplex Token Metadata is the legacy NFT standard: a mint account plus metadata PDA, master edition, and optional token record accounts. It still powers a large share of secondary market liquidity and older collections.
Recipe
const TOKEN_METADATA_PROGRAM = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s";
// Metadata PDA: ["metadata", program_id, mint_id]# Prefer Metaplex Umi / Sugar tooling over manual CLI for new legacy-compatible mintsWhen to reach for this:
- Integrating with marketplaces requiring Token Metadata layout
- Maintaining existing collections already on Token Metadata
- Reading historical NFTs in indexers
- pNFT (programmable NFT) rules with token record accounts
Working Example
import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import { mplTokenMetadata } from "@metaplex-foundation/mpl-token-metadata";
import { fetchMetadataFromSeeds } from "@metaplex-foundation/mpl-token-metadata";
import { publicKey } from "@metaplex-foundation/umi";
const umi = createUmi("https://api.mainnet-beta.solana.com").use(mplTokenMetadata());
const mint = publicKey("MINT_PUBKEY");
const metadata = await fetchMetadataFromSeeds(umi, { mint });
console.log(metadata.name, metadata.uri);
console.log("seller fee bps:", metadata.sellerFeeBasisPoints);// DAS read (preferred for wallets)
const asset = await dasRpc("getAsset", { id: mint.toString() });What this demonstrates:
- Metadata PDA derived from mint + program ID
sellerFeeBasisPointsstores royalty percentage (500 = 5%)- DAS abstracts PDA math for portfolio reads
Deep Dive
How It Works
- Program ID:
metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s - Mint: SPL token with supply 1, decimals 0
- Metadata account: name, symbol, uri, creators, collection
- Master edition: print supply for editions;
max_supplyfor limited prints
Account Set
| Account | Purpose |
|---|---|
| Mint | SPL ownership token |
| Metadata PDA | JSON uri, creators, royalty bps |
| Master edition | Edition/scarcity rules |
| Token record | pNFT authorization state |
TypeScript Notes
// Verify collection: setCollectionV1 + verifyCollectionV1 instructions
// Use @metaplex-foundation/mpl-token-metadata for all instruction buildersGotchas
- Unverified collection field - spoofed collection names. Fix: run on-chain verification instruction.
- High rent from many accounts - expensive mints. Fix: prefer Core or cNFT for new projects.
- pNFT authorization complexity - token record required for transfers. Fix: follow marketplace compatibility matrix.
- Mutable metadata surprises - update authority can change uri. Fix: revoke or use immutable flag when appropriate.
- Manual PDA derivation bugs - wrong metadata address. Fix: use SDK seeds helpers or DAS.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Metaplex Core | New collections | Must stay on Token Metadata |
| cNFT | Mass drops | Need full on-chain mint per item |
| DAS-only reads | Wallet display | Building mint instructions |
FAQs
Is Token Metadata deprecated?
Not removed - but Metaplex recommends Core for new NFTs while Token Metadata remains supported.
What is a metadata PDA?
Program-derived account storing NFT name, uri, creators, and collection fields.
What are pNFTs?
Programmable NFTs with token record accounts gating transfers via rulesets.
How are royalties set?
sellerFeeBasisPoints on metadata - enforced by cooperating marketplaces.
Can metadata change?
Yes if update authority retained and not immutable.
How to verify collection?
Collection authority signs verify_collection instruction linking metadata to collection mint.
DAS vs GPA?
DAS preferred for wallets; GPA still used by indexers ingesting raw updates.
Edition NFTs?
Master edition + print mint instructions for numbered prints.
Sugar CLI?
Metaplex Sugar targets Token Metadata collection launches - check docs for Core alternatives.
Anchor programs reading metadata?
Deserialize metadata account via mpl-token-metadata crate in Rust programs.
Mainnet program ID?
metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.
When still required?
Marketplace/listing requirements explicitly demanding Token Metadata layout.
Related
- Metaplex Core - modern alternative
- Collections & Verification - verified collections
- Royalties & Enforcement - royalty bps
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.