aibtcdev NFT Skill
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>