Candy Guards

Summary

Candy Guards are modular, composable access-control components that attach to a Core Candy Machine to restrict and customize the minting process on Solana.

• Each guard handles a single responsibility such as payment, scheduling, or wallet gating.
• Guards are defined in a separate on-chain Core Candy Guard account that becomes the Mint Authority of the Candy Machine.
• Over 25 built-in guards ship with the default Candy Guard program, covering SOL/token payments, allow lists, time windows, bot protection, and more.
• Custom guards can be created by forking and deploying your own Candy Guard program.

What Is a Candy Guard?

A Candy Guard is a modular on-chain component that enforces a single access-control rule during the minting process of a Core Candy Machine. Each guard activates independently and can be combined with other guards to build the exact minting experience you need.

There is a large set of guards to choose from and each of them can be activated and configured at will.

We'll touch on all available guards later in this documentation but let's go through a few examples here to illustrate that.

• When the Start Date guard is enabled, minting will be forbidden before the preconfigured date. There is also an End Date guard to forbid minting after a given date.
• When the Sol Payment guard is enabled, the minting wallet will have to pay a configured amount to a configured destination wallet. Similar guards exist for paying with tokens or NFTs of a specific collection.
• The Token Gate and NFT Gate guards restrict minting to certain token holders and NFT holders respectively.
• The Allow List guard only allows minting if the wallet is part of a predefined list of wallets. Kind of like a guest list for minting.

As you can see, each guard takes care of one responsibility and one responsibility only which makes them composable. In other words, you can pick and choose the guards your need to create your perfect Candy Machine.

Core Candy Guard Account

The Core Candy Guard account is the on-chain account that stores every activated guard and its configuration for a given Core Candy Machine. Each Core Candy Machine account should typically be associated with its own Core Candy Guard account which will add a layer of protection to it.

This works by creating a Core Candy Guard account and making it the Mint Authority of the Core Candy Machine account. By doing so, it is no longer possible to mint directly from the main Core Candy Machine program. Instead, we must mint via the Core Candy Guard program which, if all guards are resolved successfully, will defer to the Core Candy Machine Core program to finish the minting process.

Note that, since Core Candy Machine and Core Candy Guard accounts work hand and hand together, our SDKs treat them as one entity. When you create a Core Candy Machine with our SDKs, an associated Core Candy Guard account will also be created by default. The same goes when updating Core Candy Machines as they allow you to update guards at the same time. We will see some concrete examples on this page.

Why Guards Use a Separate Program

Guards live in a dedicated Candy Guard program — separate from the Core Candy Machine Core program — so that access-control logic is fully decoupled from mint logic. The reason guards don't live in the main Core Candy Machine program is to separate the access control logic from the main Core Candy Machine responsibility which is to mint an NFT.

This enables guards to not only be modular but extendable. Anyone can create and deploy their own Core Candy Guard program to create custom guards whilst relying on the Core Candy Machine Core program for all the rest.

Note that our SDKs also offer ways to register your own Core Candy Guard programs and their custom guards so you can leverage their friendly API and easily share your guards with others.

Available Guards

The default Core Candy Guard program ships with over 25 built-in guards covering payment, scheduling, gating, and bot protection. In the following list, we'll provide a short description of each guard with a link pointing to their dedicated page for more advanced reading.

• Address Gate: Restricts the mint to a single address.
• Allocation: Allows specifying a limit on the number of NFTs each guard group can mint.
• Allow List: Uses a wallet address list to determine who is allowed to mint.
• Asset Burn Multi: Restricts the mint to holders of a specified collection, requiring a burn of one or more core assets.
• Asset Burn: Restricts the mint to holders of a specified collection, requiring a burn of a single core asset.
• Asset Gate: Restricts the mint to holders of a specified collection.
• Asset Mint Limit: Restricts minting to holders of a specified collection and limits the number of mints that can be executed for a provided Core Asset.
• Asset Payment Multi: Set the price of the mint as multiple Core Assets of a specified collection.
• Asset Payment: Set the price of the mint as a Core Asset of a specified collection.
• Bot Tax: Configurable tax to charge invalid transactions.
• Edition: Adds the Edition Plugin to the minted Core Asset. See the Print Editions guide for more information.
• End Date: Determines a date to end the mint.
• Freeze Sol Payment: Set the price of the mint in SOL with a freeze period.
• Freeze Token Payment: Set the price of the mint in token amount with a freeze period.
• Gatekeeper: Restricts minting via a Gatekeeper Network e.g. Captcha integration.
• Mint Limit: Specifies a limit on the number of mints per wallet.
• Nft Burn: Restricts the mint to holders of a specified collection, requiring a burn of the NFT.
• Nft Gate: Restricts the mint to holders of a specified collection.
• Nft Payment: Set the price of the mint as an NFT of a specified collection.
• Program Gate: Restricts the programs that can be in a mint transaction
• Redeemed Amount: Determines the end of the mint based on the total amount minted.
• Sol Fixed fee: Set the price of the mint in SOL with a fixed price. Similar to the Sol Payment guard.
• Sol Payment: Set the price of the mint in SOL.
• Start Date: Determines the start date of the mint.
• Third Party Signer: Requires an additional signer on the transaction.
• Token Burn: Restricts the mint to holders of a specified token, requiring a burn of the tokens.
• Token Gate: Restricts the mint to holders of a specified token.
• Token Payment: Set the price of the mint in token amount.
• Token22 Payment: Set the price of the mint in token22 (token extension) amount.
• Vanity Mint: Restricts the mint to by expecting the new mint address to match a specific pattern.

Notes

• Guards are fully composable. You can activate any combination of the built-in guards on a single Core Candy Machine to create the exact minting experience you need.
• Creating custom guards requires forking and deploying your own Candy Guard program. The Core Candy Machine Core program itself does not need to change.
• Updating the guards on a Core Candy Machine overwrites the entire guard configuration. Always re-specify every guard you want active, not just the ones you are modifying.
• Some guards such as Allow List require a route instruction to be called before minting to validate prerequisites.
• You can organize guards into multiple named sets using guard groups, enabling different rules for different minting phases or wallet tiers.

FAQ

Can I create custom Candy Guards?

Yes. Because guards live in a separate Candy Guard program, anyone can fork and deploy their own Candy Guard program with custom guard logic while still relying on the Core Candy Machine Core program for minting. The Metaplex SDKs also let you register custom Candy Guard programs so you can use their standard API.

How many guards can I use at once on a single Core Candy Machine?

You can enable any combination of the available guards simultaneously. Guards are composable, so you activate only the ones you need. For more complex scenarios you can also use guard groups to define multiple sets of guards on a single machine.

Do all guards require mint settings or route instructions?

No. Only certain guards need additional on-chain accounts (mint settings) or a dedicated route instruction. Most guards are self-contained. Check the individual guard page to see whether mint settings or a route instruction applies.

What happens if a minter fails a guard check?

The transaction is rejected. If the Bot Tax guard is enabled, the failing wallet is charged a configurable SOL penalty instead of receiving an outright error, which discourages bots from spamming invalid mint attempts.

Does updating guards on a Core Candy Machine replace all existing guard settings?

Yes. A guard update overwrites the entire guard configuration. You must re-specify every guard you want active, not just the ones you are changing.

What is the difference between a Candy Guard and a guard group?

A Candy Guard is the on-chain account that holds one default set of guards. Guard groups let you define multiple named sets of guards within the same Candy Guard account so different wallets or phases can follow different rules.

Glossary