Candy Machine
Candy Machine is Metaplex's fair minting protocol for launching NFT collections with guards (allowlists, payment, start dates, limits). Candy Machine v3 (CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdedBYaPJrtzc) targets Token Metadata assets; large drops often use cNFT instead.
Recipe
# Sugar CLI orchestrates Candy Machine deploy + reveal
sugar launch
sugar deploy
sugar mintimport { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import { mplCandyMachine } from "@metaplex-foundation/mpl-candy-machine";When to reach for this:
- Fair public mint with configurable guards
- Allowlist phases (merkle, token gate)
- Paid mints routing SOL to treasury
- Token Metadata collection launches with reveal workflow
Working Example
import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import { mplCandyMachine } from "@metaplex-foundation/mpl-candy-machine";
import { generateSigner, publicKey } from "@metaplex-foundation/umi";
import { fetchCandyMachine } from "@metaplex-foundation/mpl-candy-machine";
const umi = createUmi("https://api.devnet.solana.com").use(mplCandyMachine());
// High-level: Sugar generates config.json + assets, deploys CM account
// Programmatic mint from deployed machine:
const candyMachine = publicKey("CANDY_MACHINE_PUBKEY");
const cm = await fetchCandyMachine(umi, candyMachine);
console.log("items available:", cm.data.itemsAvailable);
console.log("items minted:", cm.itemsRedeemed);# Typical Sugar workflow
sugar validate
sugar upload # assets to Arweave/IPFS
sugar deploy # create Candy Machine on-chain
sugar mint # test mintWhat this demonstrates:
- Candy Machine account tracks supply and redeemed count
- Guards enforce payment, time, and allowlist rules per mint tx
- Sugar CLI is the standard operator toolchain for CM launches
Deep Dive
How It Works
- Candy Machine holds config: price, go-live date, guard sets, hidden settings
- Each
mintinstruction incrementsitemsRedeemedand creates NFT per config - Guards modular: sol payment, token payment, merkle allowlist, mint limit
- Reveal: hidden settings swap placeholder URI for final metadata post-mint
CM vs cNFT at Scale
| Approach | Cost per mint | Standard |
|---|---|---|
| Candy Machine v3 | Higher (full mint accounts) | Token Metadata |
| Bubblegum cNFT | Very low | Compressed |
TypeScript Notes
// Always simulate mint before public launch
// Monitor itemsRedeemed vs itemsAvailable during mint windowGotchas
- Sold out race - concurrent mints exceed supply. Fix: guards + adequate CU priority fees.
- Unrevealed metadata forever - reveal tx not run. Fix: automate reveal crank post-mint.
- Wrong guard config - free mint exploit. Fix: audit guards on devnet with adversarial tests.
- Arweave upload failures - broken images at mint. Fix:
sugar validate+ spot-check URIs. - Using CM for 100k+ drop - prohibitive rent. Fix: use Bubblegum cNFT pipeline.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Bubblegum mass mint | 10k+ items | Need full on-chain Token Metadata |
| Core custom mint site | Full control, smaller supply | Need battle-tested guard library |
| Manual mint from treasury | Friends-and-family only | Public fair launch |
FAQs
What is Candy Machine?
Metaplex minting contract with guard system for fair NFT drops.
Candy Machine program ID?
v3: CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdedBYaPJrtzc.
What is Sugar?
CLI bundling asset upload, CM deploy, and mint testing.
What are guards?
Composable rules: SOL payment, start date, allowlist, mint limit per wallet, etc.
Hidden settings?
Placeholder URI at mint; authority reveals final metadata later.
Core support?
Candy Machine historically Token Metadata - check Metaplex docs for Core mint integrations.
Devnet rehearsal?
Full Sugar deploy on devnet before mainnet - test guards and reveal.
Bot mitigation?
Mint limits, allowlists, and priority fees - no single silver bullet.
Failed mint refunds?
SOL payment guard returns failed tx without mint - user pays network fee only.
Track mint progress?
Read itemsRedeemed on Candy Machine account or index mint events.
Upgrade machine?
Plan immutable config carefully - changes often need new deployment.
vs custom Anchor mint?
CM gives audited guards; custom for novel mechanics.
Related
- Metadata & Storage - asset hosting
- Collections & Verification - collection setup
- Compressed NFTs (Bubblegum) - large drops
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.