Loot Box

In this guide we'll teach you what are loot boxes, where you can use them and how they work.

What are loot boxes?

Loot Boxes are a structure designed to bundle several tokens into a single "box" that can be opened in order to retrieve a random reward. For example, you can store many different NFTs in a loot box and randomize the distribution for the users who open these boxes.

How can I use loot boxes in my business?

There are many different use cases for loot boxes. The concept of randomized rewards is prevalent in the gaming industry, where the loot box is a virtual item that can be redeemed in order to receive other randomly selected virtual goods. It is also highly applicable in any area that features collectibles, where instead of directly giving the user a certain collectible item, they have to roll their chance of getting the item they wanted. Yet another popular use case of loot boxes is as a reward mechanism.

How do loot boxes work?

The high-level workings of the loot box mechanism are very simple:
  1. 1.
    The owner of the system must deploy the smart contract that manages the boxes;
  2. 2.
    The owner gives the smart contract access to transfer all the possible prizes;
  3. 3.
    The owner creates the loot boxes;
  4. 4.
    Loot boxes are sold or distributed to users;
  5. 5.
    Users open their boxes and receive a random reward;

Technical guide

Step 1
The first prerequisite you will need is the creation of an account and a Project (API Key) on the Cryptum Dashboard.
Step 2
With a valid Cryptum API Key, you can then instantiate the SDK as follows:
const CryptumSdk = require('cryptum-sdk')
const sdk = new CryptumSdk({
environment: 'testnet', // 'testnet', 'mainnet'
Step 3
Now you must instantiate the wallet that will be used throughout the application:
const wallet = await sdk.wallet.generateWallet({
protocol: 'BSC', // Or any other protocol ('ETHEREUM','CELO','POLYGON'...)
mnemonic: 'lorem ipsum dolor sit amet consectetur adipiscing.....',
derivation: { account: 0, address: 0 }
Make sure the wallet has sufficient funds to pay for the transactions.
Step 4
Now that our environment is ready, we can start the workflow described in the "How Loot Boxes Work" section. The first step is to deploy the loot box smart contract:
let { hash } = await sdk.lootBox.deploy({
protocol: 'BSC', // Only EVM protocols are supported at the moment
name: 'My Lootbox!',
symbol: 'ML'
Step 5
Right now our contract has been deployed, but we don't know its address just yet - only the address of the transaction that created the contract. In order to fetch the contract's address (and not just the transaction address) we must do the following:
const { address: lootBoxAddress } = await sdk.transaction.getProxyAddressByHash({
Step 6
The next step is to approve the contract to use all the tokens that will be used as rewards.
await sdk.lootBox.approve({
lootBoxAddress, // This variable was created in the previous step
protocol: 'BSC',
tokenAddress: '0xa4...E17', // Address of the token or collection
tokenType: 'ERC1155', // 'ERC20','ERC721' or 'ERC1155'
tokenId, // Only for 'ERC721'
amount // Only for 'ERC20'
Step 7
Now we can finally create our loot boxes:
const { hash: creationHash } = await sdk.lootBox.createLootBox({
contents: [{ tokenAddress, tokenId: '0', tokenType: 'ERC1155', amount: '100' }],
openStartTimestamp: '0',
recipient: wallet.address
Note that the resulting packs are ERC-1155 NFTs themselves.
The "contents" variable is an array of all the prizes. They can include all types of tokens (ERC-20/721/1155) simultaneously.
Step 8
Right now the loot boxes are created and ready to be opened, however, it's important to note that the original wallet currently holds all the boxes. Usually, this is where you'd distribute the boxes (or sell them). Since the boxes are NFTs, see how you can transfer them in our NFTs section.
Step 9
To open the boxes, the following function should be used:
const { hash: openingHash } = await sdk.lootBox.openLootBox({
protocol: 'BSC',
lootBoxId: '0' // ID of the loot box to be opened
The full loot box documentation is available at: