nft

Provides SIP-009 NFT (Non-Fungible Token) operations on Stacks L2. Transfer operations require an unlocked wallet (use bun run wallet/wallet.ts unlock first). Query operations work without a wallet.

Usage

bun run nft/nft.ts <subcommand> [options]

Subcommands

get-holdings

List all NFTs owned by an address.

bun run nft/nft.ts get-holdings [--address <addr>] [--contract-id <id>] [--limit <n>] [--offset <n>]

Options:

• --address (optional) — Stacks address to check (uses active wallet if omitted)
• --contract-id (optional) — Filter by specific NFT collection contract ID
• --limit (optional) — Maximum number of results (default: 20)
• --offset (optional) — Offset for pagination (default: 0)

Output:

{
  "address": "SP2...",
  "network": "mainnet",
  "total": 5,
  "nfts": [
    { "collection": "SP2....nft-contract::my-nft", "tokenId": "u1" },
    { "collection": "SP2....nft-contract::my-nft", "tokenId": "u2" }
  ]
}

get-metadata

Get metadata for a specific NFT (SIP-016).

bun run nft/nft.ts get-metadata --contract-id <id> --token-id <n>

Options:

• --contract-id (required) — NFT collection contract ID (e.g., SP2....my-nft)
• --token-id (required) — Token ID of the NFT (integer)

Output:

{
  "contractId": "SP2....my-nft",
  "tokenId": 1,
  "network": "mainnet",
  "metadata": {
    "name": "My NFT #1",
    "description": "...",
    "image": "https://..."
  }
}

transfer

Transfer an NFT (SIP-009) to a recipient address. Requires an unlocked wallet.

bun run nft/nft.ts transfer --contract-id <id> --token-id <n> --recipient <addr> [--fee low|medium|high|<microStx>]

Options:

• --contract-id (required) — NFT collection contract ID
• --token-id (required) — Token ID of the NFT to transfer (integer)
• --recipient (required) — Stacks address to send to
• --fee (optional) — Fee preset (low|medium|high) or micro-STX amount; auto-estimated if omitted

Output:

{
  "success": true,
  "txid": "abc123...",
  "from": "SP2...",
  "recipient": "SP3...",
  "contractId": "SP2....my-nft",
  "tokenId": 1,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

get-owner

Get the current owner of a specific NFT.

bun run nft/nft.ts get-owner --contract-id <id> --token-id <n>

Options:

• --contract-id (required) — NFT collection contract ID
• --token-id (required) — Token ID of the NFT (integer)

Output:

{
  "contractId": "SP2....my-nft",
  "tokenId": 1,
  "network": "mainnet",
  "owner": "SP2..."
}

get-collection-info

Get information about an NFT collection including its name, total supply, and available functions.

bun run nft/nft.ts get-collection-info --contract-id <id>

Options:

• --contract-id (required) — NFT collection contract ID

Output:

{
  "network": "mainnet",
  "contractId": "SP2....my-nft",
  "name": "my-nft",
  "totalSupply": 10000,
  "functions": ["transfer", "get-owner", "get-last-token-id", "get-token-uri"]
}

get-history

Get the transfer history of NFTs in a collection.

bun run nft/nft.ts get-history --contract-id <id> [--limit <n>] [--offset <n>]

Options:

• --contract-id (required) — NFT collection contract ID
• --limit (optional) — Maximum number of results (default: 20)
• --offset (optional) — Offset for pagination (default: 0)

Output:

{
  "contractId": "SP2....my-nft",
  "network": "mainnet",
  "total": 150,
  "events": [
    {
      "sender": "SP2...",
      "recipient": "SP3...",
      "tokenId": "u1",
      "txId": "abc123...",
      "blockHeight": 150000
    }
  ]
}

Notes

• Query operations (get-holdings, get-metadata, get-owner, get-collection-info, get-history) use the public Hiro API
• Transfer operations require an unlocked wallet
• NFT token IDs are typically positive integers starting from 1
• Collection contract IDs use the format: SP<deployer-address>.<contract-name>