ERC-721 (NFTs)

ERC-721 tokens are unique, non-fungible assets—each has a distinct ID and metadata. Use them for characters, weapons, land, collectibles, or any asset that should be one-of-a-kind.

Why Use ERC-721?

True Ownership

Players own their assets on-chain. They can trade, sell, or use them across any compatible game or marketplace.

Provable Scarcity

Fixed supply is enforced by the blockchain. Players can verify rarity and authenticity of any item.

Secondary Revenue

Earn royalties on every resale. Set your percentage at deployment and receive automatic payments.

Interoperability

Standard ERC-721 works with all Ethereum wallets, marketplaces, and tools out of the box.

Features

Unique Token IDs: Each token has distinct metadata
EIP-2981 Royalties: Automatic royalty enforcement
Operator Allowlist: Control which contracts can transfer
Batch Minting: Create multiple tokens in one transaction
Minting API: Server-side minting at scale

Deploy via Hub

Deploy Contracts

Deploy ERC-721 contracts in Hub

Metadata

Each NFT needs metadata following the ERC-721 standard. Metadata defines how items appear in wallets, marketplaces, and your game.

Required Fields

{
  "name": "Legendary Sword",
  "description": "A powerful weapon forged in ancient fires",
  "image": "https://assets.example.com/sword.png"
}

Field	Required	Description
`name`	Yes	Item’s display name
`description`	Yes	Short description of the item
`image`	Yes	URL to item image (PNG, WEBP recommended)

Optional Fields

Field	Description
`animation_url`	URL to video, audio, or 3D asset (MP4, WEBM, GLB)
`external_url`	Link to item details on your website
`background_color`	Six-character hex (without #) for item background
`attributes`	Array of traits for filtering and display

Attributes

Use attributes to define item properties visible in marketplaces:

{
  "name": "Flame Blade",
  "description": "A legendary sword imbued with fire magic",
  "image": "https://assets.example.com/flame-blade.png",
  "attributes": [
    { "trait_type": "Rarity", "value": "Legendary" },
    { "trait_type": "Damage", "display_type": "number", "value": 150 },
    { "trait_type": "Element", "value": "Fire" },
    { "trait_type": "Level Requirement", "display_type": "number", "value": 25 }
  ]
}

Attribute Display Types

Control how attributes appear in wallets and marketplaces:

Display Type	Use For	Example Value	How It Displays
(none)	Text values	`"Legendary"`	Rarity: Legendary
`number`	Numeric stats	`150`	Damage: 150
`boost_percentage`	Percentage bonuses	`10`	Fire Resistance: +10%
`boost_number`	Numeric bonuses	`5`	Speed: +5
`date`	Timestamps	`1672531200`	Minted: Jan 1, 2023

Naming consistency: Use the same trait_type across all items. “Rarity” everywhere, not “Rarity” for some items and “Tier” for others. This improves marketplace filtering.

Metadata Hosting Options

Immutable Hosted (Recommended)

Include metadata directly in mint requests. Immutable stores and serves it automatically:

POST {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests
{
  "assets": [{
    "owner_address": "0xRecipient",
    "token_id": "1",
    "metadata": {
      "name": "Epic Sword",
      "image": "https://assets.example.com/sword.png",
      "attributes": [{ "trait_type": "Damage", "value": 100 }]
    }
  }]
}

Environment	Base URL
Testnet	`https://api.sandbox.immutable.com`
Mainnet	`https://api.immutable.com`

Pros:

No hosting infrastructure required
Automatic IPFS pinning for permanence
Included in Minting API workflow

Cons:

Metadata becomes immutable after minting
Images still need external hosting

IPFS (Decentralized)

Upload metadata JSON to IPFS for permanent, decentralized storage: Pros:

Fully decentralized and permanent
Content-addressed (tamper-proof)
No ongoing hosting costs

Cons:

Requires IPFS setup or pinning service (Pinata, NFT.Storage)
Metadata cannot be updated

Self-Hosted

Host metadata on your own servers. Set baseURI during contract deployment: Pros:

Full control over metadata
Can update metadata after minting
Dynamic attributes possible

Cons:

Hosting infrastructure required
Centralization (server downtime affects metadata)
Must maintain availability

Minting

Via Minting API

Enable Minting API access in Hub, then:

curl -X POST '{baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests' \
  -H 'x-immutable-api-key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "assets": [{
      "owner_address": "0xRecipient",
      "token_id": "1",
      "metadata": {
        "name": "Epic Sword",
        "image": "https://assets.example.com/sword.png",
        "attributes": [{ "trait_type": "Damage", "value": 100 }]
      }
    }]
  }'

Batch Minting

Mint up to 100 tokens per request:

const assets = Array.from({ length: 100 }, (_, i) => ({
  owner_address: recipientAddress,
  token_id: String(i + 1),
  metadata: {
    name: `Item #${i + 1}`,
    image: `https://assets.example.com/${i + 1}.png`,
  },
}));

await fetch(`${API_URL}/collections/${contract}/nfts/mint-requests`, {
  method: 'POST',
  headers: { 'x-immutable-api-key': secretKey },
  body: JSON.stringify({ assets }),
});

Deploy via Code

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@imtbl/contracts/contracts/token/erc721/preset/ImmutableERC721.sol";

contract MyGameNFT is ImmutableERC721 {
    constructor(
        address owner,
        string memory name,
        string memory symbol,
        string memory baseURI,
        string memory contractURI,
        address operatorAllowlist,
        address royaltyReceiver,
        uint96 royaltyFeeNumerator
    ) ImmutableERC721(
        owner, name, symbol, baseURI, contractURI,
        operatorAllowlist, royaltyReceiver, royaltyFeeNumerator
    ) {}
}

PRODUCTS

GUIDES

Why Use ERC-721?

Features

Deploy via Hub

Deploy Contracts

Metadata

Required Fields

Optional Fields

Attributes

Attribute Display Types

Metadata Hosting Options

Immutable Hosted (Recommended)

IPFS (Decentralized)

Self-Hosted

Minting

Via Minting API

Batch Minting

Deploy via Code

Next Steps

Primary Sales

Crafting

​Why Use ERC-721?

​Features

​Deploy via Hub

Deploy Contracts

​Metadata

​Required Fields

​Optional Fields

​Attributes

​Attribute Display Types

​Metadata Hosting Options

​Immutable Hosted (Recommended)

​IPFS (Decentralized)

​Self-Hosted

​Minting

​Via Minting API

​Batch Minting

​Deploy via Code

​Next Steps

Primary Sales

Crafting

Why Use ERC-721?

Features

Deploy via Hub

Metadata

Required Fields

Optional Fields

Attributes

Attribute Display Types

Metadata Hosting Options

Immutable Hosted (Recommended)

IPFS (Decentralized)

Self-Hosted

Minting

Via Minting API

Batch Minting

Deploy via Code

Next Steps