nft

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NFT Skill

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.

提供Stacks L2上的SIP-009 NFT（非同质化代币）操作功能。转移操作需要解锁钱包（请先执行

bun run wallet/wallet.ts unlock

）。查询操作无需钱包即可使用。

Usage

使用方法

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

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:

json

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

列出指定地址拥有的所有NFT。

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

选项：

```
--address
```
（可选）——要查询的Stacks地址（若省略则使用当前激活的钱包）
```
--contract-id
```
（可选）——按特定NFT集合合约ID过滤
```
--limit
```
（可选）——结果的最大数量（默认值：20）
```
--offset
```
（可选）——分页偏移量（默认值：0）

输出：

json

{
  "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:

json

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

获取特定NFT的元数据（符合SIP-016标准）。

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

选项：

```
--contract-id
```
（必填）——NFT集合合约ID（例如：
```
SP2....my-nft
```
）
```
--token-id
```
（必填）——NFT的代币ID（整数）

输出：

json

{
  "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:

json

{
  "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"
}

将NFT（符合SIP-009标准）转移至接收方地址。此操作需要解锁钱包。

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

选项：

```
--contract-id
```
（必填）——NFT集合合约ID
```
--token-id
```
（必填）——要转移的NFT的代币ID（整数）
```
--recipient
```
（必填）——接收NFT的Stacks地址
```
--fee
```
（可选）——手续费预设值（low|medium|high）或具体micro-STX数量；若省略则自动估算

输出：

json

{
  "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:

json

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

获取特定NFT的当前所有者。

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

选项：

```
--contract-id
```
（必填）——NFT集合合约ID
```
--token-id
```
（必填）——NFT的代币ID（整数）

输出：

json

{
  "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:

json

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

获取NFT集合的相关信息，包括名称、总供应量和可用功能。

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

选项：

```
--contract-id
```
（必填）——NFT集合合约ID

输出：

json

{
  "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:

json

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

获取NFT集合中所有NFT的转移历史。

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

选项：

```
--contract-id
```
（必填）——NFT集合合约ID
```
--limit
```
（可选）——结果的最大数量（默认值：20）
```
--offset
```
（可选）——分页偏移量（默认值：0）

输出：

json

{
  "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>
```

查询操作（get-holdings、get-metadata、get-owner、get-collection-info、get-history）使用公开的Hiro API
转移操作需要解锁钱包
NFT代币ID通常为从1开始的正整数
集合合约ID采用以下格式：
```
SP<部署者地址>.<合约名称>
```