Overview
HTS represents NFTs as token type + serial numbers, with optional per-mint metadata bytes (often a UTF-8 URI pointing at JSON). Pair NFT modeling with HIP-412 NFT metadata standard guidance mirrored in references/nft-metadata-schema.md.
When to use this skill
- Launching collections with capped supply (
maxSupply) vs infinite mint strategies (still finite max typically). - Encoding royalties via
CustomRoyaltyFee+ fallback fixed fee for fungible royalty denominators. - Evaluating HTS-native NFT vs deploying ERC-721 contracts for marketplace compatibility trade-offs.
Prerequisites
- Treasury account with funded association capacity.
- Supply key custody for mint operations.
Workflow
Create collection —
TokenType.NonFungibleUnique,TokenSupplyType.Finite,setMaxSupply(n), treasury + keys.Reference: scripts/create-nft-collection.js.
Mint serials —
TokenMintTransaction.setMetadata([...])supplies one metadata blob per minted NFT batch.Reference: scripts/batch-mint.js.
Transfer NFT —
TransferTransaction.addNftTransfer(tokenId, serial, sender, recipient)(confirm overload ordering against SDK typings when upgrading).Reference: scripts/transfer-nft.js.
Royalties / fees — Use
CustomRoyaltyFee+ optionalCustomFixedFeefallback per docs.Reference: scripts/set-royalty.js.
Marketplaces — Mirror Node REST + wallet signing patterns in references/marketplace-patterns.md.
Examples
Example 1
“Mint 50 NFTs with IPFS metadata URIs.”
Prepare UTF-8 URI strings, convert to Uint8Array, batch via setMetadata([...]).
Example 2
“Take 5% royalty on secondary sales payable in HBAR.”
Model custom royalty numerator/denominator + fallback fee per CustomRoyaltyFee rules — validate fee collector account & exemptions.
Example 3
“Should we deploy ERC-721 instead?”
Compare marketplace pipeline expectations: ERC-721 gives maximal EVM tool compatibility; HTS NFT minimizes contract attack surface but may require bridges/indexers for some exchanges.
Troubleshooting
| Issue | Hint |
|---|---|
| Mint rejects metadata length | Check transaction memo/message limits — chunk external metadata |
| Cannot transfer | Recipient associated? Sender owns serial? |
| Royalty not firing | Secondary sale structure might bypass royalty conditions — verify HIP/custom fee interplay |
References
- Local: references/nft-metadata-schema.md, references/custom-fees.md, references/marketplace-patterns.md
- Docs: Mint a token, Custom token fees