Token Metadata

Q: How are royalties set?

sellerFeeBasisPoints on metadata - enforced by cooperating marketplaces.

Q: How to verify collection?

Collection authority signs verify_collection instruction linking metadata to collection mint.

Q: Anchor programs reading metadata?

Deserialize metadata account via mpl-token-metadata crate in Rust programs.

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 mints

When 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
sellerFeeBasisPoints stores 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_supply for 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 builders

Gotchas

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.

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.

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 mints

When 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
sellerFeeBasisPoints stores 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_supply for 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 builders

Gotchas

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.

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.

Token Metadata

Search Documentation

Token Metadata