Lootboxes are virtual gift boxes that provide a random selection of items, typically used in video games with virtual in-game items.
In this tutorial, we’ll use Thirdweb to create the same kind of effect, but with an NFT collection. There will be a variety of NFTs with multiple copies, some with many copies and some with only a few copies to create a sense of ‘rarity’ amongst the different NFTs in the lootbox.
For example, if our lootbox collection has a total of 100 NFTs, and 75 of them are copies of NFT A, and 25 of them are NFT B, then the probability of getting NFT A is 75%, and the probability of getting NFT B is 25%, making NFT B more ‘rare’ than NFT A.
To execute this, we’ll use Thirdweb, an easy to use web dashboard for building Web3 applications, to create an NFT ‘bundle collection’, that we’ll use to create a ‘pack’. Each pack will have a randomly generated number which will determine if the NFT inside is either NFT A or NFT B. Our NFT metadata and assets will be stored in a Filebase IPFS bucket.
Before we get started, you will need:
- A cryptowallet, such as MetaMask.
- Create a folder of images you’d like to use as NFT images for your lootbox.
- Download and install NodeJS.
- Have an IDE or text editor for making changes to snippets of code.
- Have a Filebase account. If you don’t have one yet, sign up here.
For this project, we’ll be using the Polygon Mumbai Test network, which uses the cryptocurrency MATIC.
We’ll need some test MATIC for the transactions we’ll do later in this tutorial, so first let’s get some test currency by heading over to the Polygon Faucet, selecting Mumbai and MATIC, and sending some to our wallet address.


Next, let’s download the open source Github repo for this project:
Then, navigate inside of the newly downloaded project directory and install the project’s dependencies:
Start the project by starting the next.js dev server:
Login to the Thirdweb dashboard and connect your crypto wallet of choice to Thirdweb.

Once you’ve connected your wallet, select ‘Create Project’ to get started making your NFT Lootbox project.

Then, choose the ‘Mumbai’ Network for your project:

Give your project a name and a description then click ‘Create’. You will be prompted to authorize a transaction through your crypto wallet which will use the MATIC we got from the faucet at the beginning of this tutorial:

Navigate into the project directory we cloned from git earlier.
Create a .env file that will hold our cryptowallet’s private key to be referenced in our project’s scripts. Use the following format, replacing X with your crypto wallet’s private key. For instructions on how to get your wallet’s private key, see here.
Next, install additional dependencies for our project’s scripts:
Create a new script in the scripts directory called helpers.js. Input the following content into the script file:
Replace the appAddress with your project’s address from Thirdweb. You can find it on your project dashboard under your project’s name:

This script initializes the project environment and sets up dependencies for use by our other scripts. It ‘helps’ the project, so that’s why it's called a helper script.
Next, create a script called 1-create-bundle-module.js in the scripts directory.
This script will create our bundle collection module that we’ll use to create our NFT collection. Input the following content into the script file:
Now let’s run this script to deploy the bundle collection module onto our project:
You should get an output similar to the following. Note that your output might include some warnings about experimental features. These are coming from the Thirdweb SDK and are safe to disregard.
Deployed bundle collection module with address 0x0844EbdcFc584BdF42334D69CBEB6092f8Ba07Fb
Take note of this bundle collection module address since we’ll need it for our next step.
You can confirm that this was successful by looking at your project’s dashboard in Thirdweb:

Before we can upload our NFTs, we need to upload the NFT image files to IPFS through Filebase.
For this project, we’ll be uploading 3 images to Filebase for us to use. To do this, navigate to console.filebase.com. If you don’t have an account already, sign up, then log in. Use code "IPFS" for a 5TB free trial for one-month. (5GB always free)
Select ‘Buckets’ from the left side bar menu, or navigate to console.filebase.com/buckets.
Select ‘Create Bucket’ in the top right corner to create a new bucket for your NFTs.

Enter a bucket name and choose the IPFS storage network to create the bucket.
In this guide, we’re calling the bucket nft-collection.
Bucket names must be unique across all Filebase users, be between 3 and 63 characters long, and can contain only lowercase characters, numbers, and dashes.

Next, select the bucket from your list of buckets, then select ‘Upload’ in the top right corner to upload your image files.

Select your images to be uploaded. Once uploaded, they will be listed in the bucket.

Click on each uploaded object to display the metadata for the object. Take note of the IPFS CID for each object.

Now it's time to mint our NFTs. To do so, we need a script that will create our NFT bundle. Create a new script in the scripts directory with the name 2-mint-bundle-nfts.js. Enter the following content in the new script:
Replace the following values to match your configuration:
- bundleModuleAddress: The bundle collection module address for your project’s bundle module. You can find it here:

- name: The name for each NFT you’re creating.
- description: The description for each NFT you’re creating.
- image: The IPFS CID you copied from the Filebase console, in the format ipfs://[CID]
Once you’ve configured the script to match your NFT Lootbox collection’s information, run the script:
You will receive an output similar to this:
You will also see the NFTs listed in your Bundle Module on your Thirdweb dashboard:

Your collection is now live, and you can view it on testnets.opensea.io by searching for your Bundle Collection Module Address:

You can click on any of these NFTs and view their collection rarity and other metadata:

Now we need to create the Lootbox pack module to bundle our NFTs into a pack. Create a new script in your project’s scripts directory called 3-pack-module.js and enter the following content:
Now, run the 3-pack-module.js script:
You will receive the following output:
Deployed pack module with address 0x6164eE4fC3173773B5e8a8A4745c67C3DAc0025b
Now that we have the pack module created on our project, we need to add our NFTs into the pack.
To do this, we’ll need to create another script in the scripts directory called 4-create-pack-from-bundle.js with the following content:
Replace the following values to match your configuration:
- bundleModuleAddress: Your Bundle Module Address
- packModuleAddress: Your Pack Module Address
- name: A name for your NFT Lootbox.
- image: An IPFS link using an IPFS CID for the image of your IPFS lootbox. In this example, we’re using one of the IPFS CIDs for one of the NFTs in the lootbox. If you’d like to use a different image, upload a new image to your Filebase IPFS bucket and use the CID associated with that image.
Next, run this script to create our Lootbox pack:
You should receive the following output:
You can find your pack on testnets.opensea.io by searching for the pack module address:

Note that the collection shows ‘110 owned’. This is the total number of NFTs we created when minting our NFTs for this bundle, since we made 50 copies of NFTs 1 and 2, and 10 copies of NFT 3.
Now, to open a pack we need a way to generate a random number for one of our pack’s NFTs.
To do this, we’ll use Chainlink, a popular tool for random selection of smart contracts. To use Chainlink, you need tokens called LINKs. Since we’re using the Mumbai test network, we’ll use faucets.chain.link to get some test LINKs to use.
Select the Polygon Mumbai network, enter your wallet address, and request your test LINKs.

Now that we have our test LINKs, we need to deposit them into our Lootbox project. Create a new script in the scripts directory called 5-deposit-links.js with the following content:
Replace the packModuleAddress value with your pack module address.
Now it’s time to open one of our Lootbox packs. Create another new script in your scripts directory called 6-open-packs.js with the following content:
Replace the packModuleAddress value with your pack module address. Run your open-pack.js script to open your pack:
You should receive the following output:
You opened your first Lootbox successfully! You can call this script a few more times to collect all the different NFTs in your Lootbox collection. If you check testnets.opensea.io, you can see the number of packs you own has decreased, but the number of NFTs owned has increased.
Questions? Check out our excellent documentation found here, or simply reach out to us: hello@filebase.com or by joining by our Discord.