Skip to main content

Minting API


💡Minting API Enablement
The Minting API is now live.

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:

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:

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.

caution

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:

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.

note

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.

caution

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

ActionRate Limit
# of NFTs/Token IDs per request100
Total # of NFTs requested per minute2,000

Mainnet: Game Studios with an Immutable Relationship

ActionRate Limit
# of NFTs/Token IDs per request100
Total # of NFTs requested per minute2,000

Mainnet: Game Studios and Users

ActionRate Limit
# of NFTs/Token IDs per request100
Total # of NFTs requested per minute100
tip

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.

note

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.

New Immutable Hub Project

If you are not using the Immutable Hub to deploy your collection, you will need perform the following steps:

  1. Create an account in Immutable Hub

  2. 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.

  3. Get the contractAddress of the deployed contract

  4. Get 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.

  5. Grant the minter role to our minter wallet. Here is an example script for granting the minter role to our Minting API.

EnvironmentMinter wallet address
Testnet0x9CcFbBaF5509B1a03826447EaFf9a0d1051Ad0CF
Mainnet0xbb7ee21AAaF65a1ba9B05dEe234c5603C498939E
  1. 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(): 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

  1. Prepare the metadata for future assets in the specified format.
  2. Store the metadata in your baseURI/token_id directory.
  3. Utilise the Minting API, specifying the required token_id in the API call, and include the metadata prepared in Step 1. Provide and use reference_id to check the status of the mint request.

Example: Minting API with metadata in API call

ParameterDescriptionLocationRequired
chain_nameString representing the name of the chain. A list of available chains can be found here.BodyYes
contract_addressThe contract address of the ERC721 collectionBodyYes
owner_addressThe wallet address of the player who will own the minted NFTBodyYes
token_idA unique identifier within the collection for the NFT you are creating.BodyYes
reference_idThe 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.BodyYes
x-immutable-api-keySecret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallet's private key.HeaderYes

Run the following command to mint

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',
}
]
}
}
]
}
});

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"
}

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:

ParameterDescriptionLocationRequired
chain_nameString representing the name of the chain. A list of available chains can be found here.BodyYes
contract_addressThe contract address of the ERC721 collectionBodyYes
reference_idThe 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.BodyYes
chain_idString representing the ID of the chain. A list of available chain IDs can be found here.ResponseYes
token_idThe system-generated token_id revealed once the asset has been mintedResponseNo
x-immutable-api-keySecret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key.HeaderYes
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS;
const referenceId = REFERENCE_ID;
const response = await client.getMintRequest({chainName, contractAddress, referenceId});

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

note

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:

ParameterDescriptionLocationRequired
chain_nameString representing the name of the chain. A list of available chains can be found here.BodyYes
contract_addressThe contract address of the ERC721 collectionBodyYes
reference_idThe 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.BodyYes
chain_idString representing the ID of the chain. A list of available chain IDs can be found here.ResponseYes
token_idThe system-generated token_id revealed once the asset has been mintedResponseNo
x-immutable-api-keySecret key for your environment obtained from your Hub account. Follow this guide to set yours up. This is not your wallets private key.HeaderYes
const chainName = 'CHAIN_NAME';
const contractAddress = CONTRACT_ADDRESS';
const response = await client.listMintRequests({chainName, contractAddress});

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

CauseExample Error MessageTypeCode
>100 mints in a single requestrequest body has an error: doesn't match schema #/components/schemas/CreateMintRequestRequest: Error at \"/assets\": maximum number of items is 100VALIDATION_ERROR400
Duplicate reference_id in the requestduplicated reference id: 109VALIDATION_ERROR400
Duplicate token_id in the requestduplicated token id: 109VALIDATION_ERROR400
request reference_id already existsthere are already mint requests for reference_ids: 109VALIDATION_ERROR400
amount passed for ERC721 collectionamount is only relevant for ERC1155 collections. We do accept `amount="1" for convenience but all other values will return an errorVALIDATION_ERROR400
request with token_id already existsthere are already mint requests for token_ids: 109CONFLICT409
token_id already mintedtoken_ids already minted: 109CONFLICT409
Metadata for existing ERC1155 tokenstoken_ids already minted: 109, no metadata allowedCONFLICT409

Request authentication errors

CauseExample Error MessageTypeCode
Incorrect API keysecurity requirements failed: API key is invalidUNAUTHORISED_REQUEST401
Collection and API keys associated with different environmentsAPI Key is not allowed to access this collectionAUTHENTICATION_ERROR403
Minting API not enabled for API keyAPI Key is not sponsoredAUTHENTICATION_ERROR403
Rate limit exceededToo many requestsTOO_MANY_REQUESTS_ERROR429

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

CauseExample Error MessageRecommended Action
Minter role of collection not granted to Minting APItransaction failed to build: execution reverted: AccessControl: account 0x7ca12c6843adddbccdeb0efdf69a01028e274a70 is missing role 0x4d494e5445525f524f4c45000000000000000000000000000000000000000000Grant minter role to Minting API and try the request again.
Minting API failed to submit transactionExceeded a maximum of 5 submissionsSubmit request again

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us