Skip to main content

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.

Sections
💡Minting API Enablement
The Minting API is now live on mainnet.

To gain access to the minting API on mainnet, please complete the following steps in Hub. Kindly note that during the initial launch period, the minting API is exclusively available to partners under contract with Immutable.

The Minting API is available to all developers using Immutable's preset contracts on testnet.

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 preset contracts. At present, ERC1155 minting functionality is unavailable through the Minting API.

Expanding the capabilities of the Minting API to accommodate ERC1155 minting is a planned enhancement on Immutable's roadmap. Kindly refer back to this page for forthcoming updates.

Function: 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: 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.

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.

Using the Minting API​

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 Minting API during its Beta phase has the following rate limits applied.

If your product requires higher rate limits please reach out to your Immutable representitive.

ActionRate Limit
# of NFTs per request100
# of requests per second5
Total # of NFTs requested per minute2,000

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.

Minting API prerequisites​

To use the Minting API you will need to have performed the following steps:

  1. Create an account in 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 Hub account.
  3. Get the contractAddress of the deployed contract
  4. Get a secretAPIKey from 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. Mainnet Enablement: Follow these steps for Mainnet enablement. During our initial launch period mainnet access is available to partners that have a contract with Immutable.

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:

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

Sequence of Actions for Using 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
  • 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 recieving 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
request with token_id already existsthere are already mint requests for token_ids: 109CONFLICT409
token_id already mintedtoken_ids already minted: 109CONFLICT409

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.

Request validation 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

Request access to Minting API on Mainnet​

Complete the following steps to request Minting API access on Mainnet. During our initial launch period mainnet access is available to partners that have a contract with Immutable.

  • Log into Immutable Hub, and locate "Help" on the bottom left of your menu
  • Here locate and click on "Minting API on Mainnet"
Minting API Help Menu
  • Follow the prompts and fill in the application details to join our Waitlist