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

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 ERC721 and ERC1155 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.

Using the Minting API​

To access the Minting API, you must have a Hub account, as it requires your organization’s Secret API Key.

Send a POST request to the mint-requests endpoint to initiate minting. The Minting API processes requests asynchronously and supports batch minting. Immutable optimizes these batches, meaning multiple mint requests may share the same transaction hash to reduce gas costs.

Metadata can be set during the minting process or added later via the Metadata Refresh API.

A reference_id is required for each minting request and must be unique within a collection. It can be the same value as the token_id if using the mintBatch() function. If a mint attempt fails, the same reference_id can be reused until successful. However, reusing a reference_id from a successfully minted asset or using the same reference_id for multiple assets within the same request will result in an error. This rule also applies to ERC1155 collections, even when the token_id is repeated.

caution

Regardless of the chosen method for metadata setup, content creators must ensure that their local metadata is synchronized with Immutable's Blockchain Data API. Marketplaces and other ecosystem partners may not always use the Blockchain Data API to reference an asset's metadata.

While the Minting API allows minters to set up asset metadata via a simple POST request, this feature does not remove the necessity for studios to host their own metadata.

For a comprehensive understanding of how an asset's metadata file, the Blockchain Data API, and the baseURI field work together to index a collection's metadata, please refer to this guide.

Minting API rate limits​

The following rate limits exist for the Minting API.

Testnet: All Game Studios and Users

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

Mainnet: Game Studios with an Immutable Relationship

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

Mainnet: Game Studios and Users

ActionRate Limit
# of Token IDs per request100
Total # of NFTs/SFTs 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, NFT/SFT only refers to the number of different token_ids included in the request.

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
Testnethttps://api.sandbox.immutable.com/v1/chains returns minter_address
Mainnethttps://api.immutable.com/v1/chains returns minter_address
  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 Functions by Collection​

The Minting API is currently compatible with Immutable's ERC721 and ERC1155 preset contracts, providing flexibility for both non-fungible tokens (NFTs) and semi-fungible tokens (SFTs).

The Minting API utilizes the safeMintBatch() function for ERC1155 collections. This function is generally more gas-efficient when minting multiple instances of the same asset (i.e., identical token_id), as it requires less blockchain storage.

Compatible Preset Contract:

When using the Minting API with ERC1155 collections:

  • The `token_id` must be specified
  • The `amount` must be greater than 0
  • Metadata can only be passed on the first mint for a new `token_id`. Attempting to pass metadata for an existing token will result in a 409 conflict error

Using the Minting API​

Select on the tabs below for a step-by-step guide on how to mint with the different contract functions:

The mintBatch() function of Immutable's recommended ERC721 and Mint-By-ID preset contracts are used when token_id is specified in the mint request.

The example below demonstrates including metadata with the mint request, which is the recommended method for optimizing system performance. By doing so, the Blockchain Data API doesn't need to crawl a game's baseURI/token_id metadata directory, leading to an improved player experience.

However, game studios must ensure that the asset's metadata file is still placed in the baseURI/token_id directory at the time of mint. This synchronization is essential for Immutable's Blockchain Data API, as some ecosystem partners may depend on the original metadata source file to publish 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_idAn optional unique identifier within the collection for the NFT you are creating. If this is not added, we will create an ID for you.BodyNo
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

create-erc721-mint-request-with-metadata.tsView on GitHub
import { blockchainData } from "@imtbl/sdk";
import { client } from "../lib";

export async function createMintRequestWithTokenIdAndMetadata(
  chainName: string,
  contractAddress: string,
  owner_address: string,
  reference_id: string,
  token_id: string
): Promise<blockchainData.Types.CreateMintRequestResult> {
  return await client.createMintRequest({
    chainName,
    contractAddress,
    createMintRequestRequest: {
      assets: [
        {
          owner_address,
          reference_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,
          reference_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.

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 or ERC1155 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
get-mint-request.tsView on GitHub
import { blockchainData } from "@imtbl/sdk";
import { client } from "../lib";

export async function getMintRequest(
  chainName: string,
  contractAddress: string,
  referenceId: string
): Promise<blockchainData.Types.ListMintRequestsResult> {
  return 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"
        },
    ]
}

Error handling​

The following tables details some of the errors that can occur when using the Minting API

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

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us