Web3 Development
Oct 20, 2025
Metaplex Protocol: Complete Guide to Building NFTs on Solana
Comprehensive guide to Metaplex Protocol for Solana NFT development. Learn Candy Machine v3 for collection launches, Token Metadata for on-chain data, Auction House for marketplaces, and how to integrate Metaplex into your dApps with JavaScript/TypeScript SDKs.
What is Metaplex?
Metaplex is the complete NFT infrastructure for Solana, providing open-source protocols, SDKs, and tools for creating, selling, and managing NFTs at scale. Built specifically for Solana's high-performance architecture, Metaplex enables NFT operations that would be cost-prohibitive on Ethereum.
Core Metaplex Protocols:
Token Metadata: Standardized on-chain metadata for NFTs
Candy Machine: Fair, reliable NFT minting and distribution
Auction House: Decentralized NFT marketplace protocol
Bubblegum: Compressed NFTs at massive scale (1M NFTs for ~50 SOL)
Token Metadata Program
The foundation of Metaplex, Token Metadata creates on-chain metadata accounts linked to SPL tokens. Unlike Ethereum where metadata is typically off-chain, Metaplex stores critical information on Solana for permanence and composability.
Metadata Structure:
Name: NFT name (32 chars max on-chain)
Symbol: Collection symbol (10 chars max)
URI: Link to off-chain JSON (Arweave, IPFS)
Creators: Array of creator addresses with royalty shares
Seller Fee Basis Points: Royalty percentage (500 = 5%)
Collection: Parent collection for verified grouping
Creating an NFT with Token Metadata:
typescript
import { Metaplex } from '@metaplex-foundation/js';
const { nft } = await metaplex.nfts().create({
name: 'My NFT',
uri: 'https://arweave.net/metadata.json',
sellerFeeBasisPoints: 500, // 5% royalty
creators: [
{ address: creatorPublicKey, share: 100 }
]
});
Candy Machine v3: NFT Collection Launches
Candy Machine is Metaplex's battle-tested solution for launching NFT collections. It handles minting, payment processing, allowlists, and fair distribution at scale.
Key Features:
Configurable Guards: Control who can mint (allowlist, token gates, payment types)
Multiple Payment Options: SOL, USDC, or custom SPL tokens
Mint Limits: Per-wallet limits to prevent whale dominance
Freeze Authority: Prevent transfers until reveal
Programmable NFTs: Advanced royalty enforcement
Setting Up Candy Machine v3:
bash
# Install Sugar CLI
bash <(curl -sSf https://sugar.metaplex.com/install.sh)
# Create configuration
sugar create-config
# Upload assets
sugar upload
# Deploy Candy Machine
sugar deploy
Configuration Example (config.json):
json
{
"number": 10000,
"symbol": "MYNFT",
"sellerFeeBasisPoints": 500,
"creators": [
{ "address": "YOUR_WALLET", "share": 100 }
],
"guards": {
"default": {
"solPayment": {
"value": 1.5,
"destination": "TREASURY_WALLET"
},
"startDate": { "date": "2025-11-01 12:00:00" },
"mintLimit": { "id": 1, "limit": 3 }
}
}
}
Auction House: Building NFT Marketplaces
Auction House is Metaplex's protocol for peer-to-peer NFT trading. It's gas-efficient and allows anyone to create their own NFT marketplace.
Core Operations:
Listing: Sellers create sell orders with price and expiry
Bidding: Buyers create buy orders (offers)
Execution: When bid matches ask, trade executes atomically
Escrow: Funds held securely until sale completes
Creating Auction House:
typescript
const { auctionHouse } = await metaplex.auctionHouse().create({
sellerFeeBasisPoints: 200, // 2% marketplace fee
requiresSignOff: false,
canChangeSalePrice: true
});
Compressed NFTs with Bubblegum
Bubblegum enables minting millions of NFTs for a fraction of normal costs using Solana's state compression. A collection of 1 million NFTs costs ~50 SOL instead of 12,000+ SOL.
How It Works:
Compressed NFTs use Merkle trees to store NFT data efficiently. Only the tree root lives on-chain; full data is stored in cheaper Solana ledger space and reconstructed via proofs when needed.
Integrating Metaplex into Your dApp
Using Metaplex JS SDK:
typescript
import { Metaplex } from '@metaplex-foundation/js';
import { Connection, clusterApiUrl } from '@solana/web3.js';
const connection = new Connection(clusterApiUrl('mainnet-beta'));
const metaplex = Metaplex.make(connection);
// Find NFTs by owner
const nfts = await metaplex.nfts().findAllByOwner({
owner: walletPublicKey
});
// Fetch NFT metadata
const nft = await metaplex.nfts().load({ metadata });
console.log(nft.json); // Off-chain metadata
Real-World Use Cases
PFP Collections: Launch 10k avatar projects with Candy Machine
Gaming Assets: Use Bubblegum for millions of in-game items
Marketplaces: Build custom NFT marketplaces with Auction House
Ticketing: Create event tickets with transfer restrictions
Music NFTs: Distribute music with automatic royalties
Best Practices
Store metadata on Arweave for permanent availability
Use Collections to group related NFTs and enable verification
Implement proper royalty enforcement with programmable NFTs
Test thoroughly on Devnet before mainnet launches
Use Sugar CLI for Candy Machine management
Conclusion
Metaplex has become the de facto standard for NFTs on Solana, powering billions of dollars in NFT volume. Its comprehensive tools, from Token Metadata to Candy Machine to compressed NFTs, provide everything needed to build production-ready NFT applications. For developers entering the Solana ecosystem, mastering Metaplex is essential for creating competitive NFT projects.
