Skip to main content

Overview

info

This documentation refers to the latest iteration of Candy Machine known as Candy Machine V3. If you’re looking for Candy Machine V2, please refer to this documentation instead.

Introduction​

The Metaplex Protocol Candy Machine is the leading minting and distribution program for fair NFT collection launches on Solana. Much like its name suggests, you can think of a Candy Machine as a temporary structure which is first loaded by creators and then unloaded by buyers. It allows creators to bring their digital assets on-chain in a secure and customisable way.

The name refers to the vending machines that dispense candy for coins via a mechanical crank. In this case the candy are NFTs and the payment is SOL or a SPL token.

a typical candy machine

A Typical Candy Machine

By September 2022, 78% of all NFTs in Solana were minted through Metaplex’s Candy Machine. This includes most of the well known NFT projects in the Solana ecosystem.

Here are some of the features it offers.

  • Accept payments in SOL, NFTs or any Solana token.
  • Restrict your launch via start/end dates, mint limits, third party signers, etc.
  • Protect your launch against bots via configurable bot taxes and gatekeepers like Captchas.
  • Restrict minting to specific NFT/Token holders or to a curated list of wallets.
  • Create multiple minting groups with different sets of rules.
  • Reveal your NFTs after the launch whilst allowing your users to verify that information.
  • And so much more!

Interested? Let’s give you a little tour of how Candy Machines work!

The Lifecycle of a Candy Machine​

The very first step is for the creator to create a new Candy Machine and configure it however they want.

Candy Machines V3 - Overview 1@2x.png

The created Candy Machine keeps track its own settings which helps us understand how all of its NFTs should be minted. For instance, there is a creators parameter which will be assigned to all NFTs minted from this Candy Machine. We will see how to create and configure Candy Machines in more details, including some code examples, in the following pages: Candy Machine Settings and Managing Candy Machines.

However, we still don’t know which NFTs should be minted from that Candy Machine. In other words, the Candy Machine is not loaded. So our next step, is to insert items into the Candy Machine.

Candy Machines V3 - Overview 2@2x.png

Each item is composed of two parameters:

  • A name: The name of the NFT.
  • A uri: The URI pointing to the JSON metadata of the NFT. This implies that the JSON metadata has already been uploaded via either an on-chain (e.g. Arweave, IPFS) or off-chain (e.g. AWS, your own server) storage provider.

All other parameters are shared between all NFTs and are therefore kept in the settings of the Candy Machine directly to avoid repetition. See Inserting Items for more details.

Notice how, at this point, no real NFTs have been created yet. We are simply loading the Candy Machine with all the data it needs to create NFTs on-demand, at mint time. Which brings us to the next step.

Candy Machines V3 - Overview 3@2x.png

Once the Candy Machine is loaded and all pre-configured conditions are met, users can start minting NFTs from it. It’s only at this point that an NFT is created on the Solana blockchain. Note that, before minting, some users may need to perform additional verification steps — such as doing a Captcha or sending a Merkle Proof. See Minting for more details.

Once all NFTs have been minted from a Candy Machine, it has served its purpose and can safely be deleted to free some storage space on the blockchain and claim some rent back. See Managing Candy Machines for more details.

Candy Machines V3 - Overview 4@2x.png

Candy Guards​

Now that we understand how Candy Machines work, let’s dig into the various ways creators can protect and customise the mint process of their Candy Machine.

Creators can use what we call “Guards” to add various features to their Candy Machine. The Metaplex Candy Machine ships with an additional Solana Program called Candy Guard that ships with a total of 16 default guards. By using an additional program, it allows advanced developers to fork the default Candy Guard program to create their own custom guards whilst still being able to rely on the main Candy Machine program.

Each guard can be enabled and configured at will so creators can pick and choose the features they need. Disabling all guards would be equivalent to allowing anyone to mint our NFTs for free at any time, which is likely not what we want. So let’s have a look at a few guards to create a more realistic example.

Say a Candy Machine has the following guards:

  • Sol Payment: This guard ensures the minting wallet has to pay a configured amount of SOL to a configured destination wallet.
  • Start Date: This guard ensures minting can only start after the configured time.
  • Mint Limit: This guard ensures each wallet cannot mint more than a configured amount.
  • Bot Tax: This guard is a bit special. It doesn’t guard against anything but it changes the behaviour of a failed mint to prevent bots from minting Candy Machines. When this guard is activated, if any other activated guard fails to validate the mint, it will charge a small configured amount of SOL to the wallet that tried to mint.

What we end up with is a bot-protected Candy Machine that charges SOL, launches at a specific time and only allows a limited amount of mints per wallet. Here’s a concrete example.

Candy Machines V3 - Overview 5@2x.png

As you can see, with more than 16 default guards and the ability to create custom guards, it enables creators to cherry-pick the features that matters to them and compose their perfect Candy Machine. This is such a powerful feature that we’ve dedicated many pages to it. The best place to start to know more about guards is the Candy Guards page.

Next steps​

Whilst this provides a good overview of Candy Machines, there is a lot more to discover and learn about them. Here’s what you can expect in the other pages of this Candy Machine documentation.