Sui NFT Minting Process Documentation

Overview

This document describes the complete process of minting NFTs on the Sui blockchain using our platform. The process involves several steps that must be executed in a specific order to successfully create and mint NFTs.

Base URL: Belong v3 API

Process Flow

Detailed Process Steps

1. Publish Collection

Endpoint: POST /crypto/sui/collection/publish

Publishes a collection to the Sui blockchain. This step creates the initial collection data and returns transaction bytes that need to be signed.

Input:

{
  "walletAddress": "0x...",
  "name": "Collection Name",
  "symbol": "SYMBOL",
  "description": "Collection Description",
  "image_url": "https://...",
  "feeNumerator": 2,
  "mintPrice": 2,
  "whitelistMintPrice": 1,
  "transferable": true,
  "maxTotalSupply": 9999,
  "collectionExpire": 1785508320,
  "isSui": false
}

Output:

{
  "transactionBytes": "base64_encoded_transaction",
  "name": "Collection Name",
  "symbol": "SYMBOL",
  "collectionCap": "0x..."
}

2. Create Collection

Endpoint: POST /crypto/sui/collection/create

Creates the collection on the blockchain using the signed transaction from step 1.

Input:

{
  "signature": {
    "signature": "0x...",
    "bytes": "0x..."
  },
  "walletAddress": "0x...",
  "name": "Collection Name",
  "symbol": "SYMBOL",
  "collectionCap": "0x..."
}

Output:

{
  "transactionBytes": "base64_encoded_transaction"
}

3. Save Collection

Endpoint: POST /crypto/sui/collection/save

Saves the collection data to the database after successful blockchain creation.

Input:

{
  "signature": {
    "signature": "0x...",
    "bytes": "0x..."
  },
  "name": "Collection Name",
  "symbol": "SYMBOL"
}

Output:

{
  "collectionAddress": "0x...",
  "produce_data": {
    "name": "Collection Name",
    "symbol": "SYMBOL",
    "creator": "0x...",
    "feeReceiver": "0x..."
  }
}

4. Kiosk Management

4a. Get Existing Kiosk

Endpoint: GET /crypto/sui/kiosk

Retrieves an existing kiosk for the collection if one already exists.

Query Parameters:

collection=0x...&owner=0x...

Output:

{
  "kioskId": "0x...",
  "kioskCap": "0x...",
  "collection": "0x...",
  "owner": "0x..."
}

4b. Create New Kiosk

Step 1: Sign KioskEndpoint: POST /crypto/sui/kiosk/sign

Gets transaction data for kiosk creation.

Input:

{
  "walletAddress": "0x..."
}

Output:

{
  "transactionBytes": "base64_encoded_transaction"
}

Step 2: Create KioskEndpoint: POST /crypto/sui/kiosk/create

Creates the kiosk using the signed transaction.

Input:

{
  "signature": {
    "signature": "0x...",
    "bytes": "0x..."
  },
  "owner": "0x...",
  "collection": "0x..."
}

Output:

{
  "kioskId": "0x...",
  "kioskCap": "0x...",
  "collection": "0x...",
  "owner": "0x..."
}

5. Sponsor Management (Optional)

5a. Skip Sponsor

If you don't want to sponsor gas payments, you can proceed directly to minting.

5b. Create Sponsor

Endpoint: POST /crypto/sui/collection/create-sponsored

Creates a gas payment sponsor for the collection.

Input:

{
  "collectionAddress": "0x...",
  "walletAddress": "0x..."
}

Output:

{
  "sponsorAddress": "0x...",
  "ownerAddress": "0x...",
  "collectionAddress": "0x..."
}

5c. Fund Sponsor Account

Important: After creating a sponsor, you must fund the sponsor account with SUI tokens to cover gas fees for minting operations.

6. Mint NFT

6a. Sign Mint Transaction

Endpoint: POST /crypto/sui/mint/sign

Gets transaction data for minting the NFT.

Input:

{
  "collectionName": "Collection Name",
  "collectionSymbol": "SYMBOL",
  "mintCapProps": {
    "name": "NFT Name",
    "description": "NFT Description",
    "metadataLink": "https://...",
    "imageUrl": "https://...",
    "whitelisted": true,
    "uses": 1,
    "capReceiver": "0x..."
  },
  "senderAddress": "0x...",
  "kioskId": "0x...",
  "kioskCap": "0x..."
}

Output:

{
  "transactionBytes": "base64_encoded_transaction",
  "sponsorSignature": {
    "signature": "0x...",
    "bytes": "0x..."
  }
}

6b. Execute Mint

Endpoint: POST /crypto/sui/mint

Executes the mint transaction using the provided signatures.

Input:

{
  "senderSignature": {
    "signature": "0x...",
    "bytes": "0x..."
  },
  "sponsorSignature": {
    "signature": "0x...",
    "bytes": "0x..."
  }
}

Output:

{
  "id": { "id": "0x..." },
  "name": "NFT Name",
  "description": "NFT Description",
  "metadataLink": "https://...",
  "image_url": "https://...",
  "block_number": 12345,
  "hash": "0x..."
}

Error Handling

Common Errors

1. Invalid Address: Ensure all Sui addresses are valid and properly formatted
2. Insufficient Balance: Make sure the wallet has enough SUI for gas fees
3. Sponsor Not Funded: If using a sponsor, ensure the sponsor account is funded
4. Collection Already Exists: Check if the collection name/symbol combination is unique
5. Kiosk Not Found: Verify the kiosk exists for the collection/owner combination

Error Response Format

{
  "error": "Error description"
}

Best Practices

1. Always verify addresses before submitting transactions
2. Test on testnet before deploying to mainnet
3. Keep track of transaction hashes for debugging
4. Monitor gas fees and ensure sufficient balance
5. Use sponsors for better UX when possible
6. Validate metadata URLs before minting

Sui Transaction Signature Example

import { Transaction } from '@mysten/sui/transactions'
import { fromBase64 } from '@mysten/sui/utils'

// Get transaction bytes from API
const transactionBytes = await apiV3(
  `https://api.nomadcalendar.io/api/v3/crypto/sui/collection/publish`,
  {
    method: 'POST',
    body: payload,
  }
)

// Decode transaction bytes
const builtTx = fromBase64(transactionBytes.transactionBytes)

// Sign the transaction
const signature = await walletInstance.signTransaction(builtTx)

// Send signature back to API
const result = await apiV3(
  `https://api.nomadcalendar.io/api/v3/crypto/sui/collection/create`,
  {
    method: 'POST',
    body: {
      signature: signature,
      walletAddress: address,
      // ... other parameters
    },
  }
)

API Tools

The same functionality is also available through MCP tools for AI integration:

• publish-collection
• create-collection
• save-collection
• get-kiosk
• sign-kiosk
• create-kiosk
• create-sponsored-collection
• mint-sign
• mint

Each tool follows the same input/output schema as the corresponding API endpoints.