How to create a Metaplex NTF fair launch with a candy machine and bot protection (white list)

This is a technical post about how to create your own white listed Fair Launch using Metaplex. For a thorough definition of the Fair Launch protocol have a look at this post.

To complete this tutorial you will need some knowledge using git and some other command line tools.


Upload the NTFS assets

Now we upload some testing images and the associated metadata located at metaplex/js/packages/cli/example-assets. Note that the files within the example-assets folder have the following structure:


The *.png are the NFT assets and the json files contains the metadata for each of them. Please ensure that seller_fee_basis_points and creators are defined within the *.json files.

Go to the CLI root folder:

cd js/packages/cli

and upload all NTF assets from the folder example-assets by running the upload command:

build/candy-machine-cli.js upload \
  -e devnet \
  -k ~/.config/solana/devnet.json \

Params explained:

  • e: The environment used (dev mode)
  • k: The key pair used (dev)

Create a fair launch

To create a fair launch run the following command:

node build/fair-launch-cli.js new_fair_launch \
  -e devnet \
  -k ~/.config/solana/devnet.json \
  -u dev001 \
  -f 0.1 \
  -s 0.1 \
  -pe 2 \
  -pos "2021 Nov 10 10:00:00 GMT" \
  -poe "2021 Nov 10 10:10:00 GMT" \
  -pte "2021 Nov 10 10:20:00 GMT" \
  -ts 0.1 \
  -n 2 \
  -arbp 5000 \
  -atc 1 \
  -sd "2021 Nov 15 10:00:00 GMT"

Params explained:

  • k: The authority key pair used (dev mode)
  • u: 6 character alphanumeric string (must be unique relative to your keypair)
  • f: The fee that every person has to pay.
  • s: Minimum price accepted for bidding.
  • pe: Maximum price accepted for bidding.
  • pos: Phase 1 starting date.
  • poe: Phase 1 ending date.
  • pte: Phase 2 ending date.
  • ts: Tick size.
  • n: Number of tokens to sell.
  • arbp: Anti-rug treasury reserve, the percent of the treasury that will be locked to pay refunds (50% = 5000) .
  • atc: Anti-rug token requirement, when the total remaining tokens is equal or lower than this number, the treasury will be unlocked and not more refunds will be issued.
  • sd: Anti-rug self destruct date, if the NFTs were not provided by this date the users can start getting refunds.

Hit Enter and you will get the Fair Launch ID:

Create fair launch Done: BTdh5E4ryNwVhcpZahEaXy1AmKsNK1gEvFScnWbJD4Jk

Display the created Fair Launch

Now we use the show command to see exactly how the Fair launch looks like:

node build/fair-launch-cli.js show \
  -e devnet \
  -k ~/.config/solana/devnet.json \

Params explained:

  • k: Key pair (You can actually use any for this command).
  • f: The fair launch id (generated in the previous step).

Copy the Token Mint, in my case: DPeh5E4ryNwVhcpZahEaXy1AmKsNK9rEvFScnjbJDO8u

Add Token Mint into your Authority/Treasury account

Now we need to add the Token Mint generated in the previous step into our Authority/Treasury account (the account defined within the ~/.config/solana/devnet.json file).

  • Create an account for the Token mint using the following Solana CLI command:
spl-token create-account <TOKEN_MINT_HERE>
  • Copy the generated account address, in my case I9R74KjryNwVhcpZ5hEaXy1AmKsNK9rEvFSc5jbJDOI9 (this address will be needed on the next step creating the candy machine)

Create the Candy Machine

node build/candy-machine-cli.js create_candy_machine \
  -e devnet \
  -k ~/.config/solana/devnet.json \
  -p 0 \
  --spl-token <TOKEN_MINT_HERE> \
  --spl-token-account <ACCOUNT_ADDRESS_HERE>

Params explained:

  • e: The environment used (dev mode)
  • k: The key pair used (dev)
  • p: The Price denominated in SOL or spl-token in this case.
  • spl-token: The Token Mint generated when creating the fair launch.
  • spl-token-account: The Token account that receives the mint payments.

Run the command and copy the Candy Machine ID, in mi case: KoR99egryNwVhcpZ5hEaXy1AmKsNK9rEvFSc5j8fToY9

Edit the metaplex/js/packages/fair-launch/.env settings adding the Candy machine address, the Fair launch address and devnet network:


Start the Fair Launch frontend

Go into the metaplex/js/packages/fair-launch/ folder and start the server:

Create a white list (list of allowed winners)

The white list is a json file containing the wallet addresses (pubkeys) of the people allowed to buy NTFs. This is a great measure to avoid bots.

  • Create the json file at js/packages/cli/build/whitelist.json
  • Edit the file adding an array of the wallets allowed to buy, for instance:

Starting the raffle/lottery

First we need to run the following command which creates a PDA (Program Derived Address) with all the tickets created:

node build/fair-launch-cli.js create_missing_sequences \
  -e devnet \
  -k ~/.config/solana/devnet.json \

Params explained:

  • e: The environment used (dev mode)
  • k: The key pair used (dev)
  • f: The Fair launch address.

Then we need to run the lottery:

node build/fair-launch-cli.js create_fair_launch_lottery \
  -e devnet \
  -k ~/.config/solana/devnet.json \
  -w build/whitelist.json

Params explained:

  • w: The JSON file containing the white list os customers (list of addresses allowed to win the lottery)

The output will show the lottery results. For a detailed view of the winners run:

node build/fair-launch-cli.js show_lottery \
  -e devnet \
  -k ~/.config/solana/devnet.json \

(Optional) Keep some NFTs

If you want to keep some NFTs instead of selling them all, you can start the Candy Machine at some date in the future:

node build/candy-machine-cli.js update_candy_machine \
    -e devnet \
    -k ~/.config/solana/devnet.json \
    --date "2050 Nov 10 00:00:00 GMT"

Now use the following command as many times as needed to mint the tokens one by one:

node build/candy-machine-cli.js mint_one_token -k ~/.config/solana/devnet.json

The minted tokens will be stored within the Token Authority/Treasury account.

Important!! remember to set back the price before going live ! Otherwise the bots may get for free all your NFTs! Just don’t forget to follow the next step.

Set starting date for the Candy machine

Before starting the last phase we need to set the candy machine starting date (for instance any date in the past):

node build/candy-machine-cli.js update_candy_machine \
  -e devnet \
  -k ~/.config/solana/devnet.json \
  -p 0.000000001 \
  --date "2021 Nov 10 00:00:00 GMT"

Note that here we set the price to 0.000000001 to avoid this bug. It will be translated into just 1.

Start phase 3, refunds and withdraws

Now that the candy machine is active we can start phase 3, and users will be able to cash out their tickets:

node build/fair-launch-cli.js start_phase_three \
  -e devnet \
  -k ~/.config/solana/devnet.json \

You cannot withdraw the money until all tickets has been punched or refunded. They users can do that manually by revisiting the site or you can just run the following command to apply it for all at once. It will prevent people from forgetting to claim their refunds:

node build/fair-launch-cli.js punch_and_refund_all_outstanding \
  -e devnet \
  -k ~/.config/solana/devnet.json \

Withdraw funds from the Fair Lunch

Once the withdraws and refunds are over the lottery owner can withdraw all the funds by running the following command:

node build/fair-launch-cli.js withdraw_funds \
  -e devnet \
  -k ~/.config/solana/devnet.json \

Comments 1

Leave a Reply

Your email address will not be published. Required fields are marked *