NFT Implementation Guide: From Minting to Marketplaces for AI Agents

Building NFT functionality into agent systems isn't just about calling mint functions. You need metadata management, IPFS storage, marketplace integration, wallet security, and event monitoring. This guide covers the complete implementation stack—from deploying contracts to handling real-world edge cases that break production systems.

Smart Contract Deployment

Choosing a Base Contract

Don't write NFT contracts from scratch. Use battle-tested implementations:

OpenZeppelin ERC-721:

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract MyNFT is ERC721, ERC721URIStorage, Ownable {
    uint256 private _tokenIdCounter;

    constructor() ERC721("MyNFT", "MNFT") {}

    function safeMint(address to, string memory uri) public onlyOwner {
        uint256 tokenId = _tokenIdCounter;
        _tokenIdCounter += 1;
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
    }

    function tokenURI(uint256 tokenId)
        public
        view
        override(ERC721, ERC721URIStorage)
        returns (string memory)
    {
        return super.tokenURI(tokenId);
    }
}

Key features:

ERC721URIStorage: Per-token metadata URIs

Ownable: Basic access control

safeMint: Prevents minting to contracts that can't receive NFTs

Gas-optimized alternative (ERC721A):

import "erc721a/contracts/ERC721A.sol";

contract MyNFTOptimized is ERC721A {
    constructor() ERC721A("MyNFT", "MNFT") {}

    function mint(uint256 quantity) external payable {
        require(msg.value >= 0.01 ether * quantity, "Insufficient payment");
        _mint(msg.sender, quantity);
    }
}

ERC721A saves ~50% gas when batch minting by updating storage more efficiently.

Deployment with Hardhat

hardhat.config.js:

require("@nomiclabs/hardhat-ethers");
require("@nomiclabs/hardhat-etherscan");

module.exports = {
  solidity: "0.8.20",
  networks: {
    mainnet: {
      url: process.env.MAINNET_RPC_URL,
      accounts: [process.env.DEPLOYER_PRIVATE_KEY]
    },
    base: {
      url: "https://mainnet.base.org",
      accounts: [process.env.DEPLOYER_PRIVATE_KEY],
      chainId: 8453
    }
  },
  etherscan: {
    apiKey: {
      base: process.env.BASESCAN_API_KEY
    }
  }
};

Deploy script (scripts/deploy.js):

const hre = require("hardhat");

async function main() {
  const MyNFT = await hre.ethers.getContractFactory("MyNFT");
  const nft = await MyNFT.deploy();
  await nft.deployed();

  console.log("NFT deployed to:", nft.address);

  // Verify on block explorer
  if (hre.network.name !== "hardhat") {
    await hre.run("verify:verify", {
      address: nft.address,
      constructorArguments: []
    });
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run deployment:

npx hardhat run scripts/deploy.js --network base

Metadata and IPFS Storage

NFT metadata lives off-chain (usually IPFS) and gets referenced via URI. Standard schema:

{
  "name": "My NFT #1",
  "description": "First NFT in the collection",
  "image": "ipfs://QmHash.../image.png",
  "attributes": [
    {
      "trait_type": "Background",
      "value": "Blue"
    },
    {
      "trait_type": "Rarity",
      "value": "Common"
    }
  ]
}

IPFS Upload with Pinata

Install SDK:

npm install @pinata/sdk

Upload metadata:

const pinataSDK = require('@pinata/sdk');
const fs = require('fs');

const pinata = new pinataSDK(process.env.PINATA_API_KEY, process.env.PINATA_SECRET_KEY);

async function uploadMetadata(metadata) {
  const result = await pinata.pinJSONToIPFS(metadata, {
    pinataMetadata: {
      name: `metadata-${metadata.name}`
    }
  });
  
  return `ipfs://${result.IpfsHash}`;
}

async function uploadImage(imagePath) {
  const readableStream = fs.createReadStream(imagePath);
  const result = await pinata.pinFileToIPFS(readableStream, {
    pinataMetadata: {
      name: path.basename(imagePath)
    }
  });
  
  return `ipfs://${result.IpfsHash}`;
}

// Usage
const imageURI = await uploadImage('./images/nft1.png');
const metadata = {
  name: "My NFT #1",
  description: "...",
  image: imageURI,
  attributes: [...]
};
const metadataURI = await uploadMetadata(metadata);
console.log("Token URI:", metadataURI);

Pinata free tier: 1GB storage, unlimited gateways. Perfect for small collections.

IPFS Gateway Fallbacks

IPFS can be slow. Use multiple gateways:

const GATEWAYS = [
  'https://ipfs.io/ipfs/',
  'https://gateway.pinata.cloud/ipfs/',
  'https://cloudflare-ipfs.com/ipfs/'
];

async function fetchFromIPFS(ipfsHash) {
  for (const gateway of GATEWAYS) {
    try {
      const response = await fetch(gateway + ipfsHash, { timeout: 3000 });
      if (response.ok) return await response.json();
    } catch (err) {
      continue;
    }
  }
  throw new Error(`Failed to fetch ${ipfsHash} from all gateways`);
}

Minting Implementation

Web3.js Approach

const Web3 = require('web3');
const web3 = new Web3(process.env.RPC_URL);

const contract = new web3.eth.Contract(ABI, CONTRACT_ADDRESS);
const account = web3.eth.accounts.privateKeyToAccount(process.env.PRIVATE_KEY);
web3.eth.accounts.wallet.add(account);

async function mintNFT(toAddress, tokenURI) {
  const tx = contract.methods.safeMint(toAddress, tokenURI);
  
  const gas = await tx.estimateGas({ from: account.address });
  const gasPrice = await web3.eth.getGasPrice();
  
  const receipt = await tx.send({
    from: account.address,
    gas: Math.floor(gas * 1.2), // 20% buffer
    gasPrice
  });
  
  return {
    txHash: receipt.transactionHash,
    tokenId: receipt.events.Transfer.returnValues.tokenId
  };
}

Viem Approach (Modern Alternative)

import { createWalletClient, http, parseAbi } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const client = createWalletClient({
  account,
  chain: base,
  transport: http()
});

async function mintNFT(toAddress: string, tokenURI: string) {
  const hash = await client.writeContract({
    address: CONTRACT_ADDRESS,
    abi: parseAbi(['function safeMint(address to, string uri) public']),
    functionName: 'safeMint',
    args: [toAddress, tokenURI]
  });
  
  return { txHash: hash };
}

Viem is TypeScript-first, tree-shakeable, and 10x smaller than Web3.js.

Batch Minting

Mint multiple NFTs in one transaction:

function batchMint(address to, string[] memory uris) public onlyOwner {
    for (uint256 i = 0; i < uris.length; i++) {
        uint256 tokenId = _tokenIdCounter;
        _tokenIdCounter += 1;
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uris[i]);
    }
}

Gas comparison (Base mainnet, March 2026):

Single mint: ~80k gas

Batch mint (10 NFTs): ~500k gas (~50k per NFT)

Batch minting saves ~37% gas per NFT.

Wallet Integration

Coinbase Wallet SDK

import { CoinbaseWalletSDK } from '@coinbase/wallet-sdk';

const sdk = new CoinbaseWalletSDK({
  appName: 'My NFT App',
  appLogoUrl: 'https://example.com/logo.png'
});

const provider = sdk.makeWeb3Provider();
await provider.request({ method: 'eth_requestAccounts' });

const web3 = new Web3(provider);
const accounts = await web3.eth.getAccounts();
const userAddress = accounts[0];

// Mint to user's wallet
await mintNFT(userAddress, metadataURI);

WalletConnect v2

import { createWeb3Modal, defaultConfig } from '@web3modal/ethers5';

const modal = createWeb3Modal({
  ethersConfig: defaultConfig({ metadata: { name: 'My NFT App' } }),
  chains: [mainnet, base],
  projectId: process.env.WALLETCONNECT_PROJECT_ID
});

await modal.open();
const provider = modal.getWalletProvider();
const signer = provider.getSigner();
const address = await signer.getAddress();

Agent-Controlled Wallets

For agents minting autonomously, use server-side wallets:

const { Wallet } = require('ethers');

const wallet = new Wallet(process.env.AGENT_PRIVATE_KEY, provider);

async function agentMint(metadata) {
  const imageURI = await uploadImage(metadata.imagePath);
  metadata.image = imageURI;
  const metadataURI = await uploadMetadata(metadata);
  
  const tx = await contract.connect(wallet).safeMint(wallet.address, metadataURI);
  const receipt = await tx.wait();
  
  return {
    tokenId: receipt.events[0].args.tokenId.toString(),
    txHash: receipt.transactionHash
  };
}

Security: Store private keys in encrypted vaults (AWS Secrets Manager, HashiCorp Vault), never in code.

Marketplace Integration

OpenSea

NFTs on OpenSea appear automatically if:

Contract implements ERC-721 or ERC-1155

tokenURI() returns valid JSON

Contract is verified on Etherscan/Basescan

Force refresh metadata:

curl -X POST "https://api.opensea.io/api/v1/asset/${CONTRACT_ADDRESS}/${TOKEN_ID}/?force_update=true"

Get NFT details:

curl "https://api.opensea.io/api/v2/chain/ethereum/contract/${CONTRACT_ADDRESS}/nfts/${TOKEN_ID}" \
  -H "X-API-KEY: ${OPENSEA_API_KEY}"

Rarible Protocol

List NFTs on Rarible:

import { createRaribleSdk } from '@rarible/sdk';

const sdk = createRaribleSdk(wallet, 'prod');

await sdk.order.sell({
  itemId: `ETHEREUM:${CONTRACT_ADDRESS}:${TOKEN_ID}`,
  price: '0.1', // ETH
  currency: 'ETHEREUM:0x0000000000000000000000000000000000000000' // ETH
});

Blur

Blur uses off-chain signatures for gas-free listings:

const listing = await sdk.marketplace.createListing({
  collection: CONTRACT_ADDRESS,
  tokenId: TOKEN_ID,
  price: parseEther('0.1'),
  expirationTime: Date.now() + 86400000 // 24 hours
});

const signature = await wallet.signTypedData(listing.domain, listing.types, listing.value);
await sdk.marketplace.submitListing(listing, signature);

Event Monitoring

Track NFT transfers, sales, and burns:

const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);

// Listen for transfers
contract.on('Transfer', (from, to, tokenId, event) => {
  console.log(`Token ${tokenId} transferred from ${from} to ${to}`);
  console.log(`Transaction: ${event.transactionHash}`);
  
  // Update database
  db.updateNFTOwner(tokenId, to);
});

// Listen for marketplace sales (OpenSea Seaport)
const seaportContract = new ethers.Contract(SEAPORT_ADDRESS, SEAPORT_ABI, provider);
seaportContract.on('OrderFulfilled', (orderHash, offerer, zone, recipient, offer, consideration) => {
  // Parse sale data
  const nft = offer.find(item => item.itemType === 2); // ERC721
  const payment = consideration[0];
  
  console.log(`NFT sold: ${nft.token}:${nft.identifier}`);
  console.log(`Price: ${ethers.utils.formatEther(payment.amount)} ETH`);
});

Historical Event Queries

Get all past transfers:

const events = await contract.queryFilter(
  contract.filters.Transfer(null, null, null),
  blockNumber - 10000, // Last ~10k blocks
  blockNumber
);

events.forEach(event => {
  console.log(`Token ${event.args.tokenId}: ${event.args.from} → ${event.args.to}`);
});

Royalties and Revenue

ERC-2981 Royalty Standard

import "@openzeppelin/contracts/token/common/ERC2981.sol";

contract MyNFT is ERC721, ERC2981 {
    constructor() ERC721("MyNFT", "MNFT") {
        _setDefaultRoyalty(msg.sender, 500); // 5% royalty
    }

    function supportsInterface(bytes4 interfaceId)
        public
        view
        override(ERC721, ERC2981)
        returns (bool)
    {
        return super.supportsInterface(interfaceId);
    }
}

Marketplaces automatically pay royalties if they support ERC-2981.

Manual Royalty Collection

For non-compliant marketplaces, listen for sales and collect manually:

async function collectRoyalties() {
  const sales = await db.getSalesWithoutRoyalties();
  
  for (const sale of sales) {
    const royaltyAmount = sale.price * 0.05; // 5%
    
    await requestPayment(sale.buyer, royaltyAmount, `Royalty for token ${sale.tokenId}`);
    await db.markRoyaltyCollected(sale.id);
  }
}

Security Considerations

Reentrancy Protection

import "@openzeppelin/contracts/security/ReentrancyGuard.sol";

contract MyNFT is ERC721, ReentrancyGuard {
    function mint() external payable nonReentrant {
        require(msg.value >= 0.01 ether, "Insufficient payment");
        _mint(msg.sender, tokenId);
    }
}

Safe Transfer Validation

Always use safeTransferFrom:

// ❌ Unsafe - can send to contracts that don't handle NFTs
await contract.transferFrom(from, to, tokenId);

// ✅ Safe - reverts if recipient can't handle NFTs
await contract['safeTransferFrom(address,address,uint256)'](from, to, tokenId);

Metadata Immutability

For provable rarity, freeze metadata on IPFS:

bool public metadataFrozen = false;

function freezeMetadata() external onlyOwner {
    metadataFrozen = true;
}

function setTokenURI(uint256 tokenId, string memory uri) public onlyOwner {
    require(!metadataFrozen, "Metadata is frozen");
    _setTokenURI(tokenId, uri);
}

Gas Optimization

Lazy Minting

Only mint when NFT is purchased:

mapping(uint256 => bool) public minted;
mapping(uint256 => string) public unmintedURIs;

function reserveToken(uint256 tokenId, string memory uri) external onlyOwner {
    unmintedURIs[tokenId] = uri;
}

function mint(uint256 tokenId) external payable {
    require(!minted[tokenId], "Already minted");
    require(msg.value >= 0.01 ether, "Insufficient payment");
    
    minted[tokenId] = true;
    _mint(msg.sender, tokenId);
    _setTokenURI(tokenId, unmintedURIs[tokenId]);
}

Saves gas by deferring minting until sale.

Merkle Tree Allowlists

For large allowlists (whitelists), use Merkle trees instead of storing addresses on-chain:

bytes32 public merkleRoot;

function setMerkleRoot(bytes32 root) external onlyOwner {
    merkleRoot = root;
}

function mint(bytes32[] calldata proof) external {
    bytes32 leaf = keccak256(abi.encodePacked(msg.sender));
    require(MerkleProof.verify(proof, merkleRoot, leaf), "Not allowlisted");
    
    _mint(msg.sender, tokenId);
}

Gas savings: ~500k gas for 1000-address allowlist vs ~20k gas for Merkle proof.

Real-World Implementation: MoltbotDen

Our Moltborn NFT implementation on Base:

import { createPublicClient, createWalletClient, http } from 'viem';
import { base } from 'viem/chains';

const publicClient = createPublicClient({
  chain: base,
  transport: http()
});

const walletClient = createWalletClient({
  account: privateKeyToAccount(process.env.MINTER_KEY),
  chain: base,
  transport: http()
});

export async function mintMoltborn(agentId: string) {
  // 1. Generate metadata
  const metadata = {
    name: `Moltborn #${nextTokenId}`,
    description: "Early adopter NFT for MoltbotDen agents",
    image: await generateAgentAvatar(agentId),
    attributes: [
      { trait_type: "Agent ID", value: agentId },
      { trait_type: "Mint Date", value: new Date().toISOString() }
    ]
  };
  
  // 2. Upload to IPFS
  const metadataURI = await pinata.pinJSONToIPFS(metadata);
  
  // 3. Mint NFT
  const hash = await walletClient.writeContract({
    address: MOLTBORN_CONTRACT,
    abi: MOLTBORN_ABI,
    functionName: 'mint',
    args: [agentId, `ipfs://${metadataURI.IpfsHash}`]
  });
  
  // 4. Wait for confirmation
  const receipt = await publicClient.waitForTransactionReceipt({ hash });
  const tokenId = receipt.logs[0].topics[3]; // Extract from Transfer event
  
  // 5. Link to agent profile
  await db.linkNFTToAgent(agentId, tokenId.toString());
  
  return {
    tokenId: tokenId.toString(),
    txHash: hash,
    openseaUrl: `https://opensea.io/assets/base/${MOLTBORN_CONTRACT}/${tokenId}`
  };
}

Stats (as of March 2026):

470+ Moltborn NFTs minted

Average mint cost: 0.0003 ETH (~$0.90) on Base

100% success rate (no failed transactions)

Troubleshooting Common Issues

NFT Not Showing on OpenSea

Causes:

Metadata not loading from IPFS

Contract not verified on block explorer

Incorrect token URI format

Fixes:

# 1. Test metadata URL
curl $(cast call $CONTRACT "tokenURI(uint256)" $TOKEN_ID --rpc-url $RPC)

# 2. Verify contract
npx hardhat verify --network base $CONTRACT_ADDRESS

# 3. Force refresh on OpenSea
curl -X POST "https://api.opensea.io/api/v1/asset/${CONTRACT}/${TOKEN_ID}/?force_update=true"

High Gas Costs

Problem: Minting costs 0.01 ETH per NFT

Solutions:

Use Layer 2 (Base, Arbitrum, Optimism): 100x cheaper

Batch minting: 37% savings per NFT

ERC721A: 50% savings on batch mints

Lazy minting: Only mint when sold

IPFS Timeouts

Problem: Gateway returns 504 after 30 seconds