Minting from a Core Candy Machine

Summary

The mintV1 instruction creates a Core Asset from a loaded Core Candy Machine by routing through the Candy Guard program for access control, then delegating the actual mint to the Core Candy Machine program.

• Two minting paths: mint via the Candy Guard program (recommended, supports guards) or directly via the Core Candy Machine program (requires mint authority signature).
• Mint Settings: guards that need runtime data (such as Third Party Signer or NFT Payment) require additional mintArgs passed at mint time.
• Guard groups: when guard groups are configured, you must specify which group label to mint from, and Mint Settings apply to the resolved guards of that group.
• Pre-validation: some guards (such as Allow List and Gatekeeper) require a separate verification step before the mint instruction can succeed.

Basic Minting

The Core Candy Machine uses two on-chain programs to handle minting: the Core Candy Machine program (responsible for the actual mint logic) and the Candy Guard program (which adds a configurable access-control layer on top). As described on the Candy Guards page, these programs work together to enable flexible minting workflows.

There are two ways to mint from a Core Candy Machine:

• From a Candy Guard program which will then delegate the minting to the Candy Machine Core program. Most of the time, you will want to do this as it allows for much more complex minting workflows. You may need to pass extra remaining accounts and instruction data to the mint instruction based on the guards configured in the account. Fortunately, our SDKs make this easy by requiring a few extra parameters and computing the rest for us.

• Directly from the Core Candy Machine Core program. In this case, only the configured mint authority can mint from it and, therefore, it will need to sign the transaction.

If everything went well, an NFT will be created following the parameters configured in the Core Candy Machine. For instance, if the given Core Candy Machine uses Config Line Settings with Is Sequential set to false, then we will get the next item at random.

import { mintV1 } from "@metaplex-foundation/mpl-core-candy-machine";
import { setComputeUnitLimit } from "@metaplex-foundation/mpl-toolbox";
import { generateSigner } from "@metaplex-foundation/umi";

const candyMachineId = publicKey("11111111111111111111111111111111");
const coreCollection = publicKey("22222222222222222222222222222222");
const asset = generateSigner(umi);

await mintV1(umi, {
  candyMachine: candyMachineId,
  asset,
  collection: coreCollection,
}).sendAndConfirm(umi);

import { mintFromCandyMachineV2 } from '@metaplex-foundation/mpl-core-candy-machine'
import { setComputeUnitLimit } from '@metaplex-foundation/mpl-toolbox'
import { transactionBuilder, generateSigner } from '@metaplex-foundation/umi'

const candyMachineId = publicKey('11111111111111111111111111111111')
const coreCollection = publicKey('22222222222222222222222222222222')
const asset = generateSigner(umi)

await mintAssetFromCandyMachine(umi, {
  candyMachine: candyMachineId,
  mintAuthority: umi.identity,
  assetOwner: umi.identity.publicKey,
  asset,
  collection: coreCollection,
}).sendAndConfirm(umi);

Minting With Guards

Guards that require runtime information use Mint Settings -- additional parameters passed via mintArgs to supply guard-specific data such as signer references, token mint addresses, or limit identifiers. If you were to build the mint instruction manually, that information would be provided as a mixture of instruction data and remaining accounts. However, using our SDKs, each guard that requires additional information at mint time defines a set of settings that we call Mint Settings. These Mint Settings will then be parsed into whatever the program needs.

A good example of a guard that requires Mint Settings is the NFT Payment guard which requires the mint address of the NFT we should use to pay for the mint amongst other things.

Each available guard contains its own documentation page and it will tell you whether or not that guard expects Mint Settings to be provided when minting.

If you were to only use guards that do not require Mint Settings, you may mint in the same way described by the "Basic Minting" section above. Otherwise, you'll need to provide an additional object attribute containing the Mint Settings of all guards that require them. Let's have a look at what that looks like in practice using our SDKs.

import {
  some,
  generateSigner,
  transactionBuilder,
} from '@metaplex-foundation/umi'
import { create, mintV1 } from '@metaplex-foundation/mpl-core-candy-machine'
import { setComputeUnitLimit } from '@metaplex-foundation/mpl-toolbox'

// Create a Core Candy Machine with guards.
const thirdPartySigner = generateSigner()
await create(umi, {
  // ...
  guards: {
    thirdPartySigner: some({ signer: thirdPartySigner.publicKey }),
    mintLimit: some({ id: 1, limit: 3 }),
  },
}).sendAndConfirm(umi)

// Mint from the Core Candy Machine.
const nftMint = generateSigner(umi)
await transactionBuilder()
  .add(setComputeUnitLimit(umi, { units: 300_000 }))
  .add(
    mintV1(umi, {
      candyMachine: candyMachineId,
      asset,
      collection: coreCollection,
      mintArgs: {
        thirdPartySigner: some({ signer: thirdPartySigner }),
        mintLimit: some({ id: 1 }),
      },
    })
  )
  .sendAndConfirm(umi)

Minting With Guard Groups

When guard groups are configured, the mint instruction requires an explicit group label to select which group to mint from. The Mint Settings then apply to the Resolved Guards of the selected group -- the combination of that group's guards merged with any default guards.

For instance, imagine a Core Candy Machine with the following guards:

• Default Guards:
  • Bot Tax
  • Third Party Signer
  • Start Date
• Group 1
  • Label: "nft"
  • Guards:
    • NFT Payment
    • Start Date
• Group 2
  • Label: "public"
  • Guards:
    • Sol Payment

The Resolved Guards of Group 1 -- labelled "nft" -- are:

• Bot Tax: from the Default Guards.
• Third Party Signer: from the Default Guards.
• NFT Payment: from Group 1.
• Start Date: from Group 1 because it overrides the default guard.

Therefore, the provided Mint Settings must be related to these Resolved Guards. In the example above, Mint Settings must be provided for the Third Party Signer guard and the NFT Payment guard.

// Create a Core Candy Machine with guards.
const thirdPartySigner = generateSigner()
await create(umi, {
  // ...
  guards: {
    botTax: some({ lamports: sol(0.001), lastInstruction: true }),
    thirdPartySigner: some({ signer: thirdPartySigner.publicKey }),
    startDate: some({ date: dateTime('2022-10-18T17:00:00Z') }),
  },
  groups: [
    {
      label: 'nft',
      guards: {
        nftPayment: some({ requiredCollection, destination: nftTreasury }),
        startDate: some({ date: dateTime('2022-10-18T16:00:00Z') }),
      },
    },
    {
      label: 'public',
      guards: {
        solPayment: some({ lamports: sol(1), destination: solTreasury }),
      },
    },
  ],
}).sendAndConfirm(umi)

// Mint from the Core Candy Machine.

const candyMachineId = publicKey('11111111111111111111111111111111')
const coreCollection = publicKey('22222222222222222222222222222222')
const asset = generateSigner(umi)

await transactionBuilder()
  .add(setComputeUnitLimit(umi, { units: 300_000 }))
  .add(
    mintV1(umi, {
      candyMachine: candyMachineId,
      asset,
      collection: coreCollection,
      group: some('nft'),
      mintArgs: {
        thirdPartySigner: some({ signer: thirdPartySigner }),
        nftPayment: some({
          mint: nftFromRequiredCollection.publicKey,
          destination: nftTreasury,
          tokenStandard: TokenStandard.NonFungible,
        }),
      },
    })
  )
  .sendAndConfirm(umi)

Minting With Pre-Validation

Some guards require an additional verification step before the mint instruction can succeed. This pre-validation step typically creates an on-chain account or issues a token that serves as proof of eligibility, which the mint instruction then checks during execution.

Pre-Validation via the Route Instruction

The route instruction allows a guard to execute its own custom instruction for pre-mint verification. The guard defines what the route instruction does, and the resulting on-chain proof is checked during the subsequent mint call.

A good example of that is the Allow List guard. When using this guard, we must verify that our wallet belongs to a predefined list of wallets by calling the route instruction and providing a valid Merkle Proof. If this route instruction is successful, it will create an Allow List PDA for that wallet which the mint instruction can then read to validate the Allow List guard. You can read more about the Allow List guard on its dedicated page.

Pre-Validation via External Services

Some guards delegate pre-validation to an external service rather than using the route instruction. The external service issues a token or credential that the guard checks during mint.

For instance, when using the Gatekeeper guard, we must request a Gateway Token by performing a challenge -- such as completing a Captcha -- which depends on the configured Gatekeeper Network. The Gatekeeper guard will then check for the existence of such Gateway Token to either validate or reject the mint. You can learn more about the Gatekeeper guard on its dedicated page.

Minting With Bot Taxes

The Bot Tax guard protects a Core Candy Machine against bots by charging a configurable SOL fee on failed mints instead of reverting the transaction. This amount is usually small to hurt bots without affecting genuine mistakes from real users. All bot taxes will be transferred to the Core Candy Machine account so that, once minting is over, you can access these funds by deleting the Core Candy Machine account.

This guard is a bit special and affects the minting behaviour of all other guards. When the Bot Tax is activated and any other guard fails to validate the mint, the transaction will pretend to succeed. This means no errors will be returned by the program but no NFT will be minted either. This is because the transaction must succeed for the funds to be transferred from the bot to the Core Candy Machine account. You can learn more about the Bot Tax guard on its dedicated page.

Notes

• Compute unit limits: Minting with multiple guards may exceed the default compute budget. Use setComputeUnitLimit from @metaplex-foundation/mpl-toolbox to increase the limit -- 300_000 units is a common starting point, but adjust based on the number of active guards.
• Minter vs. payer signers: Since Candy Guard program v1.0, the mintV1 instruction accepts separate minter and payer signers. The payer covers SOL fees (rent, SOL payment guards); the minter is validated against guards and covers token-based fees. Both default to Umi's identity and payer if not explicitly set.
• Bot Tax behavior: When Bot Tax is enabled and another guard rejects the mint, the transaction succeeds on-chain but no NFT is created. The bot tax SOL amount is transferred to the Candy Machine account. Always confirm NFT creation after minting when Bot Tax is active.
• Config Line sequencing: If the Core Candy Machine uses Config Line Settings with isSequential set to false, minted items are selected at random from the remaining pool. Setting it to true mints items in order.
• Guard group label required: When guard groups are configured, the group parameter is mandatory. Omitting it will cause the mint instruction to fail.

FAQ

What is the difference between minting via the Candy Guard program and minting directly from the Core Candy Machine program?

Minting via the Candy Guard program allows any user to mint as long as they satisfy the configured guards, enabling complex access-control workflows like payments, allow lists, and start dates. Minting directly from the Core Candy Machine program bypasses all guards but requires the configured mint authority to sign the transaction, making it suitable only for authority-controlled mints.

How do I increase the compute unit limit when minting with multiple guards?

Use the setComputeUnitLimit helper from @metaplex-foundation/mpl-toolbox in a transaction builder. A value of 300_000 units is a common starting point, but you should adjust based on the number of guards configured. More guards require more compute units.

What happens when a mint fails and Bot Tax is enabled?

When Bot Tax is active and another guard rejects the mint, the transaction still succeeds on-chain but no NFT is created. Instead, the configured bot tax amount (in SOL) is transferred from the minter to the Candy Machine account. This design prevents bots from cheaply probing guard conditions because failed attempts still cost SOL.

Do I need to provide Mint Settings for every guard when minting?

No. Only guards that require additional runtime information need Mint Settings. For example, Third Party Signer requires a signer reference and Mint Limit requires an ID. Guards like Start Date or End Date validate automatically and do not need Mint Settings. Each guard's documentation page specifies whether Mint Settings are required.

What is the difference between the minter signer and the payer signer?

Starting from Candy Guard v1.0, the mintV1 instruction accepts separate minter and payer signers. The payer covers SOL-based fees such as storage and SOL payment guards. The minter is validated against guard conditions (like allow lists and mint limits) and pays token-based fees. This separation enables gasless minting workflows where a backend payer covers SOL costs on behalf of the end user.

Next Steps

Here are some additional reading resources you might be interested in:

• All Available Guards: Have a look through all the guards available to you so you can cherry-pick the ones you need.
• Guard Groups: Learn how to configure multiple groups of guards for different minting phases.
• Route Instruction: Understand how guards use the route instruction for pre-validation.