Minting API
On this page we show you how to use Immutable's Minting API. Our Minting API streamlines the minting process, enabling seamless creation of NFTs with just one API call. Whether you're minting one NFT or hundreds, our API makes it easy and efficient.
Th Minting API is now available for all game studios and users with Hub accounts. See rate limits for more details.
The Minting API is available to all developers using Immutable's preset contracts.
Benefits of Minting API?
Immutable's Minting API simplifies the process of minting NFTs at scale by providing a user-friendly API interface. This makes Immutable's platform more accessible as Immutable solves the following issues when minting at scale:
- Local nonce tracking and management
- Transaction lifecycle tracking
- Continuously sourcing IMX for minting
- Expedited metadata indexing by submitting metadata through APIs
- Token ID reconciliation for the
mintBatchByQuantity()
function
To ensure compatibility with the Minting API, game studios are required to use Immutable's preset contracts.
Contract functions supported by Minting API
The Minting API currently is supported with Immutable's ERC721 and ERC1155 preset contracts.
Function: ERC721 mintBatch()
The Minting API uses the mintBatch()
function if a token_id
is used in the API call. It supports the minting of single or multiple assets from the same collection in a single request via the Minting API.
The following preset contracts are compatible with the Minting API mintBatch()
function:
- Recommended ERC721 preset: ImmutableERC721.sol
- ERC721 Mint-By-ID: ImmutableERC721MintByID.sol
This function allows studios to specify the token_id
at the time of minting. Although less gas-efficient compared to mintBatchByQuantity()
, mintBatch()
is useful for asset migrations where maintaining the same token_id
across platforms is required.
Function: ERC721 mintBatchByQuantity() - Most gas efficient!
The Minting API uses the mintBatchByQuantity()
function if a token_id
is not used in the API call. It supports the minting of single or multiple assets from the same collection in a single request via the Minting API.
The following preset contract is compatible with the Minting API mintBatchByQuantity()
function:
- Recommended ERC721 preset: ImmutableERC721.sol
Due to the gas efficiencies associated with mintBatchByQuantity()
, the token_id
cannot be specified during the minting process. Instead, mint requesters must provide a unique internal reference_id
for each asset being minted. After the minting process is complete, the mint-requests
Blockchain Data API endpoint can be utilised to link the onchain token_id
with its corresponding offchain reference_id
See the following section for a step by step guide on how to map reference_id
to token_id
.
Due to the design features implemented to optimise gas efficiency with mintBatchByQuantity()
, utilising this method for minting over approximately 80,000 tokens within the collection may lead to incomplete results from the balanceOf()
function.
Should you require concurrent use of both mintBatchByQuantity()
and the balanceOf()
function, please contact your Immutable representative.
Function: ERC1155 safeMintBatch()
The Minting API uses the safeMintBatch()
function if the collection you mint on is an ERC1155 collection.
The following preset contract is compatible with the Minting API safeMintBatch()
function:
- Recommended ERC1155 preset: ImmutableERC1155.sol
For requests on ERC1155 collections the token_id
field must be specified. You also need to pass an amount
greater than 0.
Passing metadata is only valid on the first mint for a specific token_id
. Passing metadata for tokens that already exist will result in a 409 conflict error.
We recommend creating ERC1155 tokens explicitly before trying to mint tokens to users during the regular flow of your game.
Each reference_id
must be unique for every successfully minted asset from each collection. If a minting attempt fails, the same reference_id
can be used again until the mint is successful.
However, attempting to reuse an existing reference_id
from a previously minted asset in a new minting request for the same collection, or using the same reference_id
for multiple assets within the same minting request, will result in an error.
This also applies to ERC1155 collections, even though token_id
can be passed multiple times.
Using the Minting API
You must have a Hub account to have access to the Minting API, as it requires your organisation's Secret API Key.
To access the Minting API, send a POST request to the mint-requests
endpoint.
The Minting API will accept your mint requests and process them asynchronously. The API supports batch mint requests, however Immutable optimises batches which can result in multiple mint requests sharing the same transaction hash (i.e. Immutable batches multiple separate Minting API requests to reduce gas).
Metadata can be set up through the Minting API or be added later via the Metadata Refresh APIs.
A reference_id
is always required when using the Minting API; it can be the same as token_id
if using the mintBatch()
feature.
Regardless of the method chosen for metadata setup, content creators must ensure that their local copy of metadata is synchronised with Immutable's Blockchain Data API. Marketplaces and other ecosystem partners may not utilise the Blockchain Data API to reference an asset's metadata.
While the Minting API allows minters to set up their asset's metadata via a simple POST request, this feature does not eliminate the need for studios to host their own metadata.
Please read the following guide to understand how an assets metadata file, the Blockchain Data API and baseURI
field work together to index a collection's metadata.
Minting API rate limits
The following rate limits exist for the Minting API.
Testnet: All Game Studios and Users
Action | Rate Limit |
---|---|
# of NFTs/Token IDs per request | 100 |
Total # of NFTs requested per minute | 100 |
Mainnet: Game Studios with an Immutable Relationship
Action | Rate Limit |
---|---|
# of NFTs/Token IDs per request | 100 |
Total # of NFTs requested per minute | 2,000 |
Mainnet: Game Studios and Users
Action | Rate Limit |
---|---|
# of NFTs/Token IDs per request | 100 |
Total # of NFTs requested per minute | 100 |
See default rate limits for all API calls here.
The above rate limits reflect rate new mint requests are accepted by the Minting API, they do not represent the rate that assets are minted to the chain which varies due to a variety of factors.
Note that for ERC1155 collections the amount minted does not impact rate limits, NFTs only refers to the number of different assets
included in the request.
The Immutable Hub currently only supports the deployment of ERC721 collections. If you wish to use the minting API for ERC1155 collections, you will need to deploy an ERC1155 preset contract manually and link it via Hub.
Support for ERC1155 preset deployment is in the works. Please check back on this page for updates.
Minting API prerequisites
If you are deploying a collection via Hub, checking the 'Enable Minting API' during deployment will automatically grant the minter role to the Immutable Minting API.
If you are not using the Immutable Hub to deploy your collection, you will need perform the following steps:
Create an account in Immutable Hub
Deploy a collection to testnet or mainnet using Immutable's preset contracts. This can be done via Hub or manual deployment. If you manually deploy your contract ensure you link the collection to your Immutable Hub account.
Get the
contractAddress
of the deployed contractGet a
secretAPIKey
from Immutable Hub. This will be required in the header of the API call. If using the SDK please check out this guide as a reference.Grant the minter role to our minter wallet. Here is an example script for granting the minter role to our Minting API.
Environment | Minter wallet address |
---|---|
Testnet | 0x9CcFbBaF5509B1a03826447EaFf9a0d1051Ad0CF |
Mainnet | 0xbb7ee21AAaF65a1ba9B05dEe234c5603C498939E |
- Ensure your application is configured around the Minting API rate limits detailed here.
SDK Usage
Minting API functionality can be accessed by using the Immutable SDK as well as calling the APIs directly. The code examples on this page refer to both approaches. When using the SDK approach, please ensure you have set up the SDK client correctly in your project as per these instructions on how to set up an Immutable SDK client.
Minting with different functions
Select on the tabs below for a step-by-step guide on how to mint with the different contract functions:
- ERC721 mintBatch(): With Metadata
- ERC721 mintBatch(): Without Metadata
- ERC721 mintBatchByQuantity(): With Metadata
- ERC721 mintBatchByQuantity(): Without Metadata
- ERC1155 safeMintBatch()
ERC721 mintBatch(): Using the Minting API with token_id
The Minting API uses the mintBatch()
function of Immutable's preset contracts if token_id
is present in the mint request.
If no token_id
is present, the mintBatchByQuantity()
function will be used by default.
Using ERC721 mintBatch() with metadata
When using the Minting API, including metadata in the API request is recommended by Immutable to expedite the asset creation process.
Incorporating metadata in the Minting API requests eliminates the need for the Blockchain Data API to index the metadata from your local backend in the baseURI/token_id
directory, which takes additonal time.
Game studios must ensure that the assets' metadata file is still placed in the baseURI/token_id
directory at time of mint. This ensures synchronisation with Immutable's Blockchain Data API, as some ecosystem partners may rely on the assets metadata source file for publishing an asset's metadata (e.g. Immutable Explorer).
Sequence of Actions for using ERC721 mintBatch() with Metadata
- Prepare the metadata for future assets in the specified format.
- Store the metadata in your
baseURI/token_id
directory. - Utilise the Minting API, specifying the required
token_id
in the API call, and include the metadata prepared in Step 1. Provide and usereference_id
to check the status of the mint request.
Example: Minting API with metadata in API call
Parameter | Description | Location | Required |
---|---|---|---|
chain_name | String representing the name of the chain. A list of available chains can be found here. | Body | Yes |
contract_address | The contract address of the ERC721 collection | Body | Yes |
owner_address | The wallet address of the player who will own the minted NFT | Body | Yes |
token_id | A unique identifier within the collection for the NFT you are creating. | Body | Yes |
reference_id | The internal content creator reference ID of the asset being minted. Each number must be unique for each collection's successful mints. Can be the same value as token_id . | Body | Yes |
x-immutable-api-key | Secret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallet's private key. | Header | Yes |
Run the following command to mint
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const response = await client.createMintRequest({
chainName,
contractAddress,
createMintRequestRequest: {
assets: [
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID,
token_id: TOKEN_ID,
metadata: {
name: 'Brown Dog Green Car',
description: 'This NFT is a Brown Dog in a Green Car',
image: 'https://mt-test-2.s3.ap-southeast-2.amazonaws.com/BDGC.png',
external_url: null,
animation_url: null,
youtube_url: null,
attributes: [
{
trait_type: 'Pet',
value: 'Dog',
},
{
trait_type: 'Pet Colour',
value: 'Brown',
},
{
trait_type: 'Vehicle',
value: 'Car',
},
{
trait_type: 'Vehicle Colour',
value: 'Green',
}
]
}
},
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID,
token_id: TOKEN_ID,
metadata: {
name: 'Brown Dog Red Car',
description: 'This NFT is a Brown Dog in a Red Car',
image: 'https://mt-test-2.s3.ap-southeast-2.amazonaws.com/BDRC.png',
external_url: null,
animation_url: null,
youtube_url: null,
attributes: [
{
trait_type: 'Pet',
value: 'Dog',
},
{
trait_type: 'Pet Colour',
value: 'Brown',
},
{
trait_type: 'Vehicle',
value: 'Car',
},
{
trait_type: 'Vehicle Colour',
value: 'Red',
}
]
}
}
]
}
});
POST {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
A successful request will receive a response like the one shown below:
{
"imx_mint_requests_limit": "2000",
"imx_mint_requests_limit_reset": "2024-02-13 07:20:00.778434 +0000 UTC",
"imx_mint_requests_retry_after": "59.98-seconds",
"imx_remaining_mint_requests": "1999"
}
ERC721 mintBatch(): Using the Minting API with token_id
The Minting API uses the mintBatch()
function of Immutable's preset contracts if token_id
is present in the mint request.
If no token_id
is present, the mintBatchByQuantity()
function will be used by default.
Using ERC721 mintBatch() without Metadata
Immutable strongly recommends sending asset metadata when using mintBatch()
via the Minting API. Additionally, ensure your metadata files are saved in your local directory in the baseURI/token_id
file structure pre-mint. This will ensure your assets are correctly represented on marketplaces and Immutable Explorer.
If you do not prepare your metadata files correct prior to the mint request being completed, you may need to perform a metadata refresh on the assets to update ecosystem partners such as marketplaces.
For more information on preparing metadata pre-mint, please refer to our documentation.
While Immutable recommends using the Minting API with metadata in the API call to expedite the minting process, if metadata is not included the Blockchain Data API indexer will source the future asset's metadata from your game's local backend.
Once an asset is created using the Minting API with a specified token_id
, the indexer will retrieve the baseURI
from your collection and search in the baseURI/token_id
directory to index the new asset's metadata.
For more information on the metadata source file, please refer to the following product page.
Sequence of actions for using ERC721 mintBatch() without metadata
- Prepare the future assets' metadata in the specified format
- Store the metadata in your
baseURI/token_id
directory - Utilise the Minting API, specifying the required
token_id
in the API call
Example: Minting API without metadata
Parameter | Description | Location | Required |
---|---|---|---|
chain_name | String representing the name of the chain. A list of available chains can be found here. | Body | Yes |
contract_address | The contract address of the ERC721 collection | Body | Yes |
owner_address | The wallet address of the player who will own the minted NFT | Body | Yes |
token_id | A unique identifier within the collection for the NFT you are creating. | Body | Yes |
reference_id | The internal content creator reference ID of the asset being minted. Each number must be unique for each collection's successful mints. Can be the same value as token_id . | Body | Yes |
x-immutable-api-key | Secret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key. | Header | Yes |
- Run the following command to mint
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const response = await client.createMintRequest({
chainName,
contractAddress,
createMintRequestRequest: {
assets: [
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID,
token_id: TOKEN_ID
},
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID,
token_id: TOKEN_ID
}
]
}
});
POST {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
A successful request will receive a response like the one shown below:
{
"imx_mint_requests_limit": "2000",
"imx_mint_requests_limit_reset": "2024-02-13 07:20:00.778434 +0000 UTC",
"imx_mint_requests_retry_after": "59.98-seconds",
"imx_remaining_mint_requests": "1999"
}
ERC721 mintBatchByQuantity(): Gas efficient minting
The Minting API uses the mintBatchByQuantity()
function of Immutable's preset contracts if token_id
is not present in the mint request.
This method offers the most gas-efficient minting process.
reference_id
is used to map a Minting API request to the system generated token_id
via the Blockchain Data API.
Using ERC721 mintBatchByQuantity() with Metadata in API call
When using the mintBatchByQuantity() via the Minting API, Immutable strongly recommends including metadata in the API request to prevent the need from having to perform a metadata refresh after the asset has been minted to index the assets metadata.
As token_id
is not specified at the start of the minting process, the metadata file cannot be located in the game studio's local backend using the baseURI/token_id
directory structure at the time of mint.
Mint requesters should still create a corresponding metadata file (filename=token_id
) in their local metadata directory (defined by the baseURI
) after the asset has been minted. This ensures synchronisation between the Blockchain Data API and the source of the asset's metadata.
If you do not prepare your metadata files within 10 seconds of receiving the token_id
, you may need to perform a metadata refresh on the assets to update ecosystem partners such as marketplaces.
For more information on preparing metadata pre-mint, please refer to our documentation.
Sequence of actions for using Minting API with metadata
- Mint the asset via the Minting API with the
reference_id
and corresponding metadata in the mint request. - Use webhooks or poll the
mint-requests
endpoint for updates on mint status and to establish thereference_id
->token_id
mapping. - Create a metadata file
../[baseURI]/[token_id]
and populate it with the metadata used in Step 1.
Example: Minting API with Metadata in the Request
Parameter | Description | Location | Required |
---|---|---|---|
chain_name | String representing the name of the chain. A list of available chains can be found here. | Body | Yes |
contract_address | The contract address of the ERC721 collection | Body | Yes |
owner_address | The wallet address of the player who will own the minted NFT | Body | Yes |
reference_id | The internal content creator reference ID of the asset being minted. This internal ID is used to link the request to the system-generated token ID. Each number must be unique for each collection's successful mints | Body | Yes |
x-immutable-api-key | Secret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key. | Header | Yes |
- Run the following command to mint:
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const response = await client.createMintRequest({
chainName,
contractAddress,
createMintRequestRequest: {
assets: [
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID,
metadata: {
name: 'Brown Dog Green Car',
description: 'This NFT is a Brown Dog in a Green Car',
image: 'https://mt-test-2.s3.ap-southeast-2.amazonaws.com/BDGC.png',
external_url: null,
animation_url: null,
youtube_url: null,
attributes: [
{
trait_type: 'Pet',
value: 'Dog',
},
{
trait_type: 'Pet Colour',
value: 'Brown',
},
{
trait_type: 'Vehicle',
value: 'Car',
},
{
trait_type: 'Vehicle Colour',
value: 'Green',
}
]
}
},
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID,
metadata: {
name: 'Brown Dog Red Car',
description: 'This NFT is a Brown Dog in a Red Car',
image: 'https://mt-test-2.s3.ap-southeast-2.amazonaws.com/BDRC.png',
external_url: null,
animation_url: null,
youtube_url: null,
attributes: [
{
trait_type: 'Pet',
value: 'Dog',
},
{
trait_type: 'Pet Colour',
value: 'Brown',
},
{
trait_type: 'Vehicle',
value: 'Car',
},
{
trait_type: 'Vehicle Colour',
value: 'Red',
}
]
}
}
]
}
});📚API referencePOST {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
A successful request will receive a response like the one shown below:
{
"imx_mint_requests_limit": "2000",
"imx_mint_requests_limit_reset": "2024-02-13 07:20:00.778434 +0000 UTC",
"imx_mint_requests_retry_after": "59.98-seconds",
"imx_remaining_mint_requests": "1999"
} - To verify the mint status and determine the `token_id` from the `reference_id`, follow [these steps](#get-minting-status-of-a-single-reference-id).
- Prepare a metadata file with a filename equal to the `token_id`. Save this file in the following location corresponding to the `baseURI` of your collection: `../[baseURI]/[token_id]`
ERC721 mintBatchByQuantity(): Gas efficient minting
The Minting API uses the mintBatchByQuantity()
function of Immutable's preset contracts if token_id
is not present in the mint request.
This method offers the most gas-efficient minting process.
reference_id
is used to map a Minting API request to the system generated token_id
via the Blockchain Data API.
Using ERC721 mintBatchByQuantity() without Metadata in API call
The Minting API can be utilised without submitting metadata upfront. A metadata refresh call will be required after the asset has been minted to update the Blockchain Data API.
Immutable strongly recommends sending asset metadata when using the Minting API. Additionally, ensure your metadata files are saved in your local directory in the baseURI/token_id
file structure within 10 seconds of receiving the token_id
from the Blockchain Data API. This will ensure your assets are correctly represented on marketplaces and Immutable Explorer.
If you do not prepare your metadata files within 10 seconds of receiving the token_id
, you may need to perform a metadata refresh on the assets to update ecosystem partners such as marketplaces.
For more information on preparing metadata pre-mint, please refer to our documentation.
Sequence of actions for using Minting API without metadata
- Mint the asset via the Minting API with the
reference_id
and no metadata. - Use webhooks or poll the
mint-requests
endpoint for updates on mint status and to establish thereference_id
->token_id
mapping. - Create a metadata file
../[baseURI]/[token_id]
and populate it with metadata used in Step 1 above. - Trigger a metadata refresh to update Immutable's Blockchain Data API.
Example: Minting API without metadata in request
Parameter | Description | Location | Required |
---|---|---|---|
chain_name | String representing the name of the chain. A list of available chains can be found here. | Body | Yes |
contract_address | The contract address of the ERC721 collection | Body | Yes |
owner_address | The wallet address of the player who will own the minted NFT | Body | Yes |
reference_id | The internal content creator reference ID of the asset being minted. This internal ID is used to link the request to the system-generated token ID. Each number must be unique for each collection's successful mints | Body | Yes |
x-immutable-api-key | Secret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key. | Header | Yes |
Run the following command to mint
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const response = await client.createMintRequest({
chainName,
contractAddress,
createMintRequestRequest: {
assets: [
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID
}
]
}
});
POST {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
ERC1155 safeMintBatch():
The Minting API uses the safeMintBatch()
function of Immutable's preset contracts if you have an ERC1155 collection.
Compared to ERC721 it is possible to send multiple mint requests with the same token ID, either in one HTTP request or multiple requests. However, it is only possible to pass metadata the first time a token ID is used.
Immutable strongly recommends sending asset metadata when creating a new token_id
with the Minting API. Additionally, ensure your metadata files are saved in your local directory in the baseURI/token_id
file structure. This practice ensures your assets are correctly represented on marketplaces and Immutable Explorer.
If you do not prepare your metadata files in your local directory in the baseURI/token_id
file structure, you may need to perform a metadata refresh post-mint to ensure all ecosystem partners, such as marketplaces, are updated with your asset's metadata.
For more information on preparing metadata pre-mint, please refer to our documentation.
Parameters to use Minting API for ERC1155 collections
Parameter | Description | Location | Required |
---|---|---|---|
chain_name | String representing the name of the chain. A list of available chains can be found here. | Body | Yes |
contract_address | The contract address of the ERC1155 collection | Body | Yes |
owner_address | The wallet address of the player who will own the minted NFT | Body | Yes |
reference_id | The internal content creator reference ID of the asset being minted. This internal ID is used to link the request to the system-generated token ID. Each number must be unique for each collection's successful mints | Body | Yes |
token_id | A unique identifier within the collection for the NFT you are creating. | Body | Yes |
amount | How many tokens to mint for this token ID. | Body | Yes |
x-immutable-api-key | Secret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key. | Header | Yes |
Using ERC1155 safeMintBatch() to create a new NFT
The Minting API can be utilised to create an ERC1155 NFT by using the API the same way as ERC721 mintBatch() with an additional amount
field.
Run the following command to mint
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const response = await client.createMintRequest({
chainName,
contractAddress,
createMintRequestRequest: {
assets: [
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID,
token_ID: TOKEN_ID,
amount: AMOUNT,
metadata: {
name: 'Brown Dog Red Car',
description: 'This NFT is a Brown Dog in a Red Car',
image: 'https://mt-test-2.s3.ap-southeast-2.amazonaws.com/BDRC.png',
external_url: null,
animation_url: null,
youtube_url: null,
attributes: [
{
trait_type: 'Pet',
value: 'Dog',
},
{
trait_type: 'Pet Colour',
value: 'Brown',
},
{
trait_type: 'Vehicle',
value: 'Car',
},
{
trait_type: 'Vehicle Colour',
value: 'Red',
}
]
}
]
}
});
POST {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
Using ERC1155 safeMintBatch() to mint to an existing NFT
Minting additional NFTs for a specific token ID looks almost the same as creating a new NFT. The main difference is that metadata cannot be passed anymore. If you need to change the metadata on an existing NFT please refer to our Metadata Refresh APIs. The minting API necessitates that your system distinguishes between creating a new Token ID and increasing the value of an existing Token ID. Metadata must be included in the initial request for creating the Token ID, while it should be omitted when adding quantities to existing Token IDs.
Providing metadata in an ERC1155 Minting API request for an existing NFT will result in a 409 conflict response.
Example: Minting API to mint additional NFTs
Run the following command to mint
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const response = await client.createMintRequest({
chainName,
contractAddress,
createMintRequestRequest: {
assets: [
{
owner_address: OWNER_ADDRESS,
reference_id: REFERENCE_ID
token_ID: TOKEN_ID,
amount: AMOUNT
}
]
}
});
POST {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
Verifying the status of a Minting request
The mint-requests
webhook or polling endpoint can be utilised to check the status of a Minting API request.
For successful mints, the following data will be returned:
chain
reference_id
status
contract_address
owner_address
token_id
amount
activity_id
transaction_hash
created_at
updated_at
For unsuccessful mints, the following data will be returned:
chain
reference_id
status
error
contract_address
owner_address
created_at
updated_at
The status
field can have the following values:
- Succeeded: The mint was successful
- Pending: The mint request is waiting in a queue
- Fail: The mint was unsuccessful; see
error
for more details
These endpoints can be queried using the below methods.
Get Minting status of a single reference ID
To retrieve the status of a single reference_id
, execute the following command:
Parameter | Description | Location | Required |
---|---|---|---|
chain_name | String representing the name of the chain. A list of available chains can be found here. | Body | Yes |
contract_address | The contract address of the ERC721 collection | Body | Yes |
reference_id | The internal content creator reference ID of the asset being minted. This internal ID is used to link the request to the system-generated token ID. | Body | Yes |
chain_id | String representing the ID of the chain. A list of available chain IDs can be found here. | Response | Yes |
token_id | The system-generated token_id revealed once the asset has been minted | Response | No |
x-immutable-api-key | Secret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key. | Header | Yes |
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const referenceId = REFERENCE_ID;
const response = await client.getMintRequest({chainName, contractAddress, referenceId});
GET {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests/{reference_id}
This will return the following results if the request is in a pending state.
{
"page": {
"next_cursor": null,
"previous_cursor": null
},
"result": [
{
"chain": {
"id": "CHAIN_ID",
"name": "CHAIN_NAME"
},
"collection_address": "CONTRACT_ADDRESS",
"created_at": "2024-02-12T05:35:35.743242Z",
"error": null,
"owner_address": "0x68209e7086032941a8Cb14352c2F43b086288791",
"reference_id": "REFERENCE_ID",
"status": "pending",
"token_id": null,
"activity_id": "null",
"transaction_hash": null,
"updated_at": "2024-02-12T05:35:35.743242Z"
},
]
}
The request will return the following request when it is successful, allowing you to map the REFERENCE_ID -> TOKEN_ID
{
"page": {
"next_cursor": null,
"previous_cursor": null
},
"result": [
{
"chain": {
"id": "CHAIN_ID",
"name": "CHAIN_NAME"
},
"collection_address": "0xe2e94d611d50370612e9721254807b7874093fb6",
"created_at": "2024-02-12T05:35:35.743242Z",
"error": null,
"owner_address": "0x68209e7086032941a8Cb14352c2F43b086288791",
"reference_id": "REFERENCE_ID",
"status": "succeeded",
"token_id": "TOKEN_ID",
"activity_id": "4e28df8d-f65c-4c11-ba04-6a9dd47b179b",
"transaction_hash": "0x6890c450a43e6f3e90b311e2c0e80e1e6880cbc93ab977fc5357ac66cd255800",
"updated_at": "2024-02-12T05:35:35.743242Z"
},
]
}
Get minting status of all Minting API requests for a collection
The preferred method of receiving Minting API status updates is via the Mint Requests webhook event.
In the below scenarios we should you how to use the Blockchain Data API mint-request
endpoint to recieve updates.
To get the status of all reference IDs used for a collection, the following command can be run:
Parameter | Description | Location | Required | |
---|---|---|---|---|
chain_name | String representing the name of the chain. A list of available chains can be found here. | Body | Yes | |
contract_address | The contract address of the ERC721 collection | Body | Yes | |
reference_id | The internal content creator reference ID of the asset being minted. This internal ID is used to link the request to the system-generated token ID. | Body | Yes | |
chain_id | String representing the ID of the chain. A list of available chain IDs can be found here. | Response | Yes | |
token_id | The system-generated token_id revealed once the asset has been minted | Response | No | |
x-immutable-api-key | Secret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key. | Header | Yes |
- SDK
- API
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS';
const response = await client.listMintRequests({chainName, contractAddress});
GET {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
The request will return the following results, allowing you to map the reference_id
-> token_id
for successful requests.
The most recent mint requests will be located as the top of the results.
{
"page": {
"next_cursor": null,
"previous_cursor": null
},
"result": [
{
"chain": {
"id": "CHAIN_ID",
"name": "CHAIN_NAME"
},
"collection_address": "CONTRACT_ADDRESS",
"created_at": "2024-02-12T05:35:35.743242Z",
"error": null,
"owner_address": "0x68209e7086032941a8Cb14352c2F43b086288791",
"reference_id": "REFERENCE_ID",
"status": "succeeded",
"token_id": "TOKEN_ID",
"activity_id": "4e28df8d-f65c-4c11-ba04-6a9dd80e1e6",
"transaction_hash": "0x6890c450a43e6f3e90b311e2c0e80e1e6880cbc93ab977fc5357ac66cd255800",
"updated_at": "2024-02-12T05:35:35.743242Z"
},
{
"chain": {
"id": "CHAIN_ID",
"name": "CHAIN_NAME"
},
"collection_address": "CONTRACT_ADDRESS",
"created_at": "2024-02-12T05:35:35.743242Z",
"error": null,
"owner_address": "0x68209e7086032941a8Cb14352c2F43b086288791",
"reference_id": "REFERENCE_ID",
"status": "succeeded",
"token_id": "TOKEN_ID",
"activity_id": "4e28df8d-f65c-4c11-ba04-6a9dd47b179b",
"transaction_hash": "0x6890c450a43e6f3e90b311e2c0e80e1e6880cbc93ab977fc5357ac66cd255800",
"updated_at": "2024-02-12T05:35:35.743242Z"
}
]
}
Error handling
The following tables details some of the errors that can occur when using the Minting API
Minting API request errors
The following errors can occur when making a Minting API call.
If these errors occur no event will be visible in Immutable's Blockchain Data API as the request would not have been accepted
Request validation errors
Cause | Example Error Message | Type | Code |
---|---|---|---|
>100 mints in a single request | request body has an error: doesn't match schema #/components/schemas/CreateMintRequestRequest: Error at \"/assets\": maximum number of items is 100 | VALIDATION_ERROR | 400 |
Duplicate reference_id in the request | duplicated reference id: 109 | VALIDATION_ERROR | 400 |
Duplicate token_id in the request | duplicated token id: 109 | VALIDATION_ERROR | 400 |
request reference_id already exists | there are already mint requests for reference_ids: 109 | VALIDATION_ERROR | 400 |
amount passed for ERC721 collection | amount is only relevant for ERC1155 collections. We do accept `amount="1" for convenience but all other values will return an error | VALIDATION_ERROR | 400 |
request with token_id already exists | there are already mint requests for token_ids: 109 | CONFLICT | 409 |
token_id already minted | token_ids already minted: 109 | CONFLICT | 409 |
Metadata for existing ERC1155 tokens | token_ids already minted: 109, no metadata allowed | CONFLICT | 409 |
Request authentication errors
Cause | Example Error Message | Type | Code |
---|---|---|---|
Incorrect API key | security requirements failed: API key is invalid | UNAUTHORISED_REQUEST | 401 |
Collection and API keys associated with different environments | API Key is not allowed to access this collection | AUTHENTICATION_ERROR | 403 |
Minting API not enabled for API key | API Key is not sponsored | AUTHENTICATION_ERROR | 403 |
Rate limit exceeded | Too many requests | TOO_MANY_REQUESTS_ERROR | 429 |
Minting API Idempotency
Networks can have issues and a client might not receive a response, even though the mint request was accepted successfully. To make sure we never process a mint request twice we don't accept the same reference_id
twice.
In case of network failure you can safely re-submit any requests that you aren't sure have been accepted. If the Minting API has already processed a reference_id
you will get a 409 Conflict
error with the following body:
{
code: "CONFLICT",
message: "there are already mint requests for reference_ids: 100",
details: {
id: "reference_id",
values: ["100"]
}
}
Minting API transaction errors
The following errors can occur after making a Minting API call.
These errors occur once a Blockchain Data API event has been triggered. They are visible from the mint request polling endpoint or the imtbl_zkevm_mint_request_updated webhook event.
Transaction errors
Cause | Example Error Message | Recommended Action |
---|---|---|
Minter role of collection not granted to Minting API | transaction failed to build: execution reverted: AccessControl: account 0x7ca12c6843adddbccdeb0efdf69a01028e274a70 is missing role 0x4d494e5445525f524f4c45000000000000000000000000000000000000000000 | Grant minter role to Minting API and try the request again. |
Minting API failed to submit transaction | Exceeded a maximum of 5 submissions | Submit request again |