SPL Token CLI 参考

spl-token 命令行界面可用于创建和管理 mint、token account、权限、转账以及 Token-2022 扩展。

本参考文档对应 spl-token-cli v5.6.1,即 Agave v4.2.1 附带的版本。请运行 spl-token --version,并使用 <command> --help 查看已安装版本中可用的确切选项。

创建 mint、转账、变更权限、销毁、冻结和关闭账户都会提交交易。运行命令前,请确认集群、Token Program、签名者和地址。主网上的更改会使用真实资产。

安装与获取帮助

Agave CLI 发行包中包含 spl-token。如果尚未安装,请使用已发布的 Rust crate:

cargo install spl-token-cli --version 5.6.1
spl-token --version

在根级别或命令级别查看帮助:

spl-token --help
spl-token create-token --help
spl-token transfer --help

全局选项

请将全局选项放在命令之前。

选项	用途
`-u, --url <URL_OR_MONIKER>`	选择 RPC URL,或 `mainnet-beta`、`testnet`、`devnet`、`localhost`。
`-C, --config <PATH>`	使用其他 Solana CLI 配置文件。
`--fee-payer <KEYPAIR>`	选择支付交易费用的账户。
`-p, --program-id <ADDRESS>`	使用明确指定的 Token Program ID。
`--program-2022`	使用 Token-2022(`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`)。
`--output <FORMAT>`	在支持的命令中返回 `json` 或 `json-compact` 格式。
`--with-compute-unit-limit <UNITS>`	设置交易的计算单元上限。
`--with-compute-unit-price <MICRO_LAMPORTS>`	设置每个计算单元的优先费价格。
`-v, --verbose`	显示更多输出。
`-V, --version`	打印已安装的 CLI 版本。

默认程序为原始的 Token Program。对于 Token-2022 的 mint 或账户,请使用 --program-2022,读取时也同样如此。如果所选程序并不拥有所提供的地址,命令将失败。

创建并使用代币

这些命令会打印所创建的地址。请保存 create-token 返回的 mint 地址,以便用于后续命令。

# Create a six-decimal mint under the original Token Program.
spl-token --url devnet create-token --decimals 6

# Create the default signer's associated token account for the mint.
spl-token --url devnet create-account <MINT_ADDRESS>

# Mint 100 tokens to that associated token account.
spl-token --url devnet mint <MINT_ADDRESS> 100

# Read supply, balance, and complete mint or account details.
spl-token --url devnet supply <MINT_ADDRESS>
spl-token --url devnet balance <MINT_ADDRESS>
spl-token --url devnet display <MINT_OR_TOKEN_ACCOUNT_ADDRESS>

# Transfer tokens to a wallet and create its associated account if needed.
spl-token --url devnet transfer \
  <MINT_ADDRESS> \
  10 \
  <RECIPIENT_WALLET_ADDRESS> \
  --fund-recipient

金额为 UI 代币数量,已按 mint 的小数位数进行调整。transfer、burn 和 unwrap-sol 等命令在其帮助中标明的位置接受 ALL。

创建 Token-2022 mint

扩展会分配额外的 mint 或账户状态,通常必须在创建 mint 时选定。以下示例创建一个 6 位小数、支持内嵌元数据的 mint:

spl-token --program-2022 create-token \
  --decimals 6 \
  --enable-metadata

spl-token --program-2022 initialize-metadata \
  <MINT_ADDRESS> \
  "Example Token" \
  EXAMPLE \
  https://example.com/token.json

常见的 create-token 扩展选项包括:

--enable-close
--enable-confidential-transfers auto|manual
--enable-freeze
--enable-group 和 --enable-member
--enable-metadata
--enable-non-transferable
--enable-pause
--enable-permanent-delegate
--enable-permissioned-burn
--enable-transfer-hook 或 --transfer-hook <PROGRAM_ID>
--interest-rate <BASIS_POINTS>
--transfer-fee-basis-points <BASIS_POINTS> 搭配 --transfer-fee-maximum-fee <AMOUNT>
--ui-amount-multiplier <MULTIPLIER>

仅可组合使用 Token-2022 程序允许同时启用的扩展。在创建不可逆的 mint 配置之前,请先查阅相关的 Token-2022 扩展指南。

管理权限与委托

# Change the mint authority.
spl-token authorize <MINT_ADDRESS> mint <NEW_AUTHORITY_ADDRESS>

# Permanently remove the mint authority.
spl-token authorize <MINT_ADDRESS> mint --disable

# Let a delegate spend up to 25 tokens from one token account.
spl-token approve \
  <TOKEN_ACCOUNT_ADDRESS> \
  25 \
  <DELEGATE_ADDRESS>

# Remove the current delegate.
spl-token revoke <TOKEN_ACCOUNT_ADDRESS>

authorize 支持 mint、冻结、所有者、关闭以及特定扩展的权限类型。如果没有其他程序机制可以恢复,使用 --disable 移除权限将是永久性的。

冻结、销毁与关闭

spl-token freeze <TOKEN_ACCOUNT_ADDRESS>
spl-token thaw <TOKEN_ACCOUNT_ADDRESS>

spl-token burn <TOKEN_ACCOUNT_ADDRESS> 5

# A token account must normally have a zero token balance before closing.
spl-token close --address <TOKEN_ACCOUNT_ADDRESS>

burn 会同时减少账户余额和总供应量。close 会将账户剩余的 lamport 返还给已配置的接收方;它不会找回已销毁的代币。

包装与解包 SOL

# Create or fund the owner's wrapped SOL token account.
spl-token wrap 1

# Unwrap part of the wrapped SOL balance.
spl-token unwrap-sol 0.25

# Close the wrapped SOL account and return its full lamport balance.
spl-token unwrap

在将 lamport 直接转入 wrapped SOL token account 之后,请使用 sync-native,使其代币数量与底层 lamport 保持一致。

多签签名

创建最多包含 11 个成员的 M-of-N Token Program 多签:

spl-token create-multisig \
  2 \
  <MEMBER_1_ADDRESS> \
  <MEMBER_2_ADDRESS> \
  <MEMBER_3_ADDRESS>

对于由该多签控制的交易,请将多签地址作为相应的权限传入,并通过重复的 --multisig-signer 值提供成员 keypair。请查看目标命令的帮助,因为其主要权限标志因操作而异。

机密余额

机密余额命令需要为机密转账配置的 Token-2022 mint,以及已配置的接收账户。

spl-token --program-2022 configure-confidential-transfer-account \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 deposit-confidential-tokens \
  <MINT_ADDRESS> \
  10 \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 apply-pending-balance \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 withdraw-confidential-tokens \
  <MINT_ADDRESS> \
  5 \
  --address <TOKEN_ACCOUNT_ADDRESS>

spl-token --program-2022 transfer \
  <MINT_ADDRESS> \
  1 \
  <RECIPIENT_ADDRESS> \
  --confidential

对于 configure-confidential-transfer-account 和 apply-pending-balance,请传入 --address <TOKEN_ACCOUNT_ADDRESS> 或位置参数 <MINT_ADDRESS>,二者不可同时使用。使用位置参数时,将采用所有者的 associated token account。存款和取款始终需要提供 mint,并可通过 --address 覆盖该默认账户。

使用 enable-confidential-credits、disable-confidential-credits、enable-non-confidential-credits 和 disable-non-confidential-credits 来控制账户接受哪些存入。这些设置会影响账户隐私和支付兼容性;更改前请先检查该账户。

完整命令索引

以下索引包含 spl-token-cli v5.6.1 中的所有顶层命令。

命令	描述
`accounts`	列出钱包拥有的 token account,可按 mint 筛选。
`address`	打印所选钱包地址或其 associated token address。
`apply-pending-balance`	将待处理的机密代币转入可用的机密余额。
`approve`	为 token account 批准委托及其支出额度。
`authorize`	变更或禁用 mint、账户或扩展的权限。
`balance`	显示 token account 余额。
`bench`	运行代币基准测试命令。
`burn`	销毁账户中的代币并减少 mint 供应量。
`close`	关闭符合条件的 token account 并回收其 lamport。
`close-mint`	关闭配置了 close-mint 扩展的 Token-2022 mint。
`configure-confidential-transfer-account`	配置账户以使用机密转账。
`create-account`	创建 associated token account 或辅助 token account。
`create-multisig`	创建 M-of-N Token Program 多签。
`create-token`	创建 mint,可选择启用 Token-2022 扩展。
`deposit-confidential-tokens`	将非机密代币转入待处理的机密余额。
`disable-confidential-credits`	拒绝账户接收机密转账。
`disable-cpi-guard`	为账户禁用 CPI Guard。
`disable-non-confidential-credits`	拒绝机密账户接收非机密转账。
`disable-required-transfer-memos`	不再要求转入的转账附带备注。
`display`	显示 mint、token account 或多签的完整详情。
`enable-confidential-credits`	允许已配置的账户接收机密转账。
`enable-cpi-guard`	在通过 CPI 调用时限制部分代币操作。
`enable-non-confidential-credits`	允许机密账户接收非机密转账。
`enable-required-transfer-memos`	要求转入的转账附带备注。
`freeze`	使用 mint 的冻结权限冻结 token account。
`gc`	关闭不必要的 token account,并尽可能合并余额。
`help`	打印根级别或命令级别的帮助。
`initialize-group`	为 mint 初始化 Token-2022 群组配置。
`initialize-member`	将 Token-2022 mint 添加为群组成员。
`initialize-metadata`	初始化 Token-2022 内嵌元数据。
`mint`	使用 mint 权限铸造新的代币单位。
`pause`	为支持暂停的 Token-2022 mint 暂停铸造、销毁和转账。
`resume`	恢复已暂停的 Token-2022 mint 的各项操作。
`revoke`	移除 token account 的委托。
`set-interest-rate`	更新计息 mint 的利率。
`set-transfer-fee`	计划设置新的转账手续费参数。
`set-transfer-hook`	更改 mint 的 transfer hook 程序 ID。
`supply`	显示 mint 的总供应量。
`sync-native`	使 wrapped SOL 账户的数量与其 lamport 同步。
`thaw`	解冻已冻结的 token account。
`transfer`	将代币转入 token account 或钱包。
`unwrap`	关闭 wrapped SOL 账户并回收全部 lamport。
`unwrap-sol`	从 wrapped SOL 账户中取出部分或全部 SOL。
`update-confidential-transfer-settings`	更新 mint 的机密转账审批或审计方设置。
`update-default-account-state`	更改 mint 为新建 token account 设定的默认状态。
`update-group-address`	更改 mint 的群组指针地址。
`update-group-max-size`	更改代币群组的最大成员数量。
`update-member-address`	更改 mint 的群组成员指针地址。
`update-metadata`	更改或移除内嵌元数据字段。
`update-metadata-address`	更改 mint 的元数据指针地址。
`update-ui-amount-multiplier`	计划设置新的缩放 UI 数量乘数。
`withdraw-confidential-tokens`	将机密代币转回非机密余额。
`withdraw-excess-lamports`	从 Token Program 账户中提取超出免租余额的 lamport。
`withdraw-withheld-tokens`	收取在 token account 或 mint 中暂扣的转账手续费。
`wrap`	将 SOL 包装到原生 mint 的 token account 中。

结构化与离线签名

请使用结构化输出,而不要解析显示文本:

spl-token accounts --output json
spl-token display <MINT_ADDRESS> --output json-compact

生成交易的命令通常支持 --sign-only、--blockhash、--signer <PUBKEY=SIGNATURE>、--nonce 和 --nonce-authority。具体的离线输入取决于命令、mint 小数位数和权限安排,因此请按照该命令的 --help 说明生成未签名消息,并在收集签名之前核实每一个地址。

Table of Contents