Referência da CLI do SPL Token

A interface de linha de comando spl-token cria e gerencia mints, token accounts, autoridades, transferências e extensões do Token-2022.

Esta referência acompanha a spl-token-cli v5.6.1, versão incluída no Agave v4.2.1. Execute spl-token --version e use <command> --help para ver as opções exatas disponíveis na sua versão instalada.

A criação de mints, as transferências, as alterações de autoridade, as queimas, os congelamentos e o fechamento de contas enviam transações. Confirme o cluster, o Token Program, o signatário e os endereços antes de executar um comando. As alterações na mainnet usam ativos reais.

Instalar e obter ajuda

O pacote de lançamento da CLI do Agave inclui o spl-token. Se ele não estiver instalado, use o crate Rust publicado:

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

Consulte a ajuda na raiz ou no nível de um comando:

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

Opções globais

Coloque as opções globais antes do comando.

Opção	Finalidade
`-u, --url <URL_OR_MONIKER>`	Selecione uma URL de RPC ou `mainnet-beta`, `testnet`, `devnet` ou `localhost`.
`-C, --config <PATH>`	Use um arquivo de configuração diferente da CLI do Solana.
`--fee-payer <KEYPAIR>`	Selecione a conta que paga as taxas de transação.
`-p, --program-id <ADDRESS>`	Use um ID de Token Program explícito.
`--program-2022`	Use o Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`).
`--output <FORMAT>`	Retorne `json` ou `json-compact` onde houver suporte.
`--with-compute-unit-limit <UNITS>`	Defina o limite de unidades de computação da transação.
`--with-compute-unit-price <MICRO_LAMPORTS>`	Defina o preço de prioridade por unidade de computação.
`-v, --verbose`	Exiba saída adicional.
`-V, --version`	Exiba a versão instalada da CLI.

O programa padrão é o Token Program original. Use --program-2022 para um mint ou uma conta do Token-2022, inclusive ao fazer a leitura. Um comando falha se o programa selecionado não for o proprietário do endereço informado.

Criar e usar um token

Os comandos imprimem os endereços criados. Salve o endereço do mint retornado por create-token para os comandos seguintes.

# 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

Os valores são quantidades de token em formato de interface (UI), ajustadas conforme as casas decimais do mint. Comandos como transfer, burn e unwrap-sol aceitam ALL onde indicado na ajuda.

Criar um mint do Token-2022

As extensões alocam estado adicional ao mint ou à conta e, em geral, devem ser escolhidas quando o mint é criado. Este exemplo cria um mint com seis casas decimais e suporte a metadados incorporados:

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

As opções de extensão mais comuns de create-token incluem:

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

Combine apenas extensões que o programa Token-2022 permite usar em conjunto. Leia o guia de extensões do Token-2022 relevante antes de criar uma configuração de mint irreversível.

Gerenciar autoridades e delegados

# 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 oferece suporte a tipos de autoridade de mint, congelamento, proprietário, fechamento e específicos de extensões. Remover uma autoridade com --disable é permanente quando nenhum outro mecanismo do programa pode restaurá-la.

Congelar, queimar e fechar

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 reduz tanto o saldo da conta quanto o fornecimento total. close devolve os lamports restantes da conta ao destinatário configurado; ele não recupera os tokens queimados.

Wrap e unwrap de 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

Use sync-native depois de transferir lamports diretamente para uma token account de wrapped SOL, para que a quantidade de tokens corresponda aos lamports subjacentes.

Assinatura multisig

Crie uma multisig M-de-N do Token Program com até 11 membros:

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

Para uma transação controlada por essa multisig, informe o endereço da multisig como a autoridade relevante e forneça os keypairs dos membros por meio de valores --multisig-signer repetidos. Consulte a ajuda do comando de destino, pois a flag de autoridade principal varia conforme a operação.

Saldos confidenciais

Os comandos de saldo confidencial exigem um mint do Token-2022 configurado para transferências confidenciais e uma conta de destinatário configurada.

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

Para configure-confidential-transfer-account e apply-pending-balance, informe --address <TOKEN_ACCOUNT_ADDRESS> ou um <MINT_ADDRESS> posicional, não ambos. A forma posicional usa a associated token account do proprietário. Depósito e saque sempre recebem o mint e aceitam --address para substituir essa conta padrão.

Use enable-confidential-credits, disable-confidential-credits, enable-non-confidential-credits e disable-non-confidential-credits para controlar quais depósitos a conta aceita. Essas configurações afetam a privacidade da conta e a compatibilidade de pagamentos; inspecione a conta antes de alterá-las.

Índice completo de comandos

O índice a seguir inclui todos os comandos de nível superior da spl-token-cli v5.6.1.

Comando	Descrição
`accounts`	Listar as token accounts de uma carteira, opcionalmente filtradas por mint.
`address`	Exibir o endereço da carteira selecionada ou o respectivo endereço de associated token account.
`apply-pending-balance`	Mover tokens confidenciais pendentes para o saldo confidencial disponível.
`approve`	Aprovar um delegado e um limite de gastos para uma token account.
`authorize`	Alterar ou desativar a autoridade de um mint, de uma conta ou de uma extensão.
`balance`	Mostrar o saldo de uma token account.
`bench`	Executar comandos de benchmark de tokens.
`burn`	Destruir tokens de uma conta e reduzir o fornecimento do mint.
`close`	Fechar uma token account elegível e recuperar seus lamports.
`close-mint`	Fechar um mint do Token-2022 configurado com a extensão close-mint.
`configure-confidential-transfer-account`	Configurar uma conta para usar transferências confidenciais.
`create-account`	Criar uma associated token account ou uma token account auxiliar.
`create-multisig`	Criar uma multisig M-de-N do Token Program.
`create-token`	Criar um mint, opcionalmente com extensões do Token-2022.
`deposit-confidential-tokens`	Mover tokens não confidenciais para um saldo confidencial pendente.
`disable-confidential-credits`	Rejeitar transferências confidenciais recebidas por uma conta.
`disable-cpi-guard`	Desativar o CPI Guard de uma conta.
`disable-non-confidential-credits`	Rejeitar transferências não confidenciais recebidas por uma conta confidencial.
`disable-required-transfer-memos`	Deixar de exigir que as transferências recebidas incluam memos.
`display`	Mostrar todos os detalhes de um mint, de uma token account ou de uma multisig.
`enable-confidential-credits`	Aceitar transferências confidenciais recebidas em uma conta configurada.
`enable-cpi-guard`	Restringir determinadas operações de token quando invocadas via CPI.
`enable-non-confidential-credits`	Aceitar transferências não confidenciais recebidas em uma conta confidencial.
`enable-required-transfer-memos`	Exigir que as transferências recebidas incluam memos.
`freeze`	Congelar uma token account usando a autoridade de congelamento do mint.
`gc`	Fechar token accounts desnecessárias e consolidar saldos quando possível.
`help`	Exibir a ajuda geral ou a de um comando.
`initialize-group`	Inicializar a configuração de grupo do Token-2022 para um mint.
`initialize-member`	Adicionar um mint do Token-2022 como membro de um grupo.
`initialize-metadata`	Inicializar os metadados incorporados do Token-2022.
`mint`	Criar novas unidades de token usando a autoridade de mint.
`pause`	Pausar a emissão, a queima e a transferência de um mint pausável do Token-2022.
`resume`	Retomar as operações de um mint pausado do Token-2022.
`revoke`	Remover o delegado de uma token account.
`set-interest-rate`	Atualizar a taxa de um mint com juros.
`set-transfer-fee`	Agendar novos parâmetros de taxa de transferência.
`set-transfer-hook`	Alterar o ID do programa de transfer hook de um mint.
`supply`	Mostrar o fornecimento total de um mint.
`sync-native`	Sincronizar o valor de uma conta de wrapped SOL com seus lamports.
`thaw`	Descongelar uma token account congelada.
`transfer`	Transferir tokens para uma token account ou carteira.
`unwrap`	Fechar uma conta de wrapped SOL e recuperar todos os lamports.
`unwrap-sol`	Remover parte ou todo o SOL de uma conta de wrapped SOL.
`update-confidential-transfer-settings`	Atualizar as configurações de aprovação ou de auditor de transferências confidenciais de um mint.
`update-default-account-state`	Alterar o estado padrão de um mint para novas token accounts.
`update-group-address`	Alterar o endereço do ponteiro de grupo de um mint.
`update-group-max-size`	Alterar o número máximo de membros de um grupo de tokens.
`update-member-address`	Alterar o endereço do ponteiro de membro de grupo de um mint.
`update-metadata`	Alterar ou remover campos de metadados incorporados.
`update-metadata-address`	Alterar o endereço do ponteiro de metadados de um mint.
`update-ui-amount-multiplier`	Agendar um novo multiplicador de valor de UI escalonado.
`withdraw-confidential-tokens`	Mover tokens confidenciais de volta para o saldo não confidencial.
`withdraw-excess-lamports`	Sacar lamports acima do saldo isento de aluguel de uma conta do Token Program.
`withdraw-withheld-tokens`	Coletar taxas de transferência retidas em token accounts ou no mint.
`wrap`	Fazer wrap de SOL em uma token account de mint nativo.

Assinatura estruturada e offline

Use saída estruturada em vez de analisar o texto exibido:

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

Os comandos que produzem transações geralmente oferecem suporte a --sign-only, --blockhash, --signer <PUBKEY=SIGNATURE>, --nonce e --nonce-authority. As entradas offline exatas dependem do comando, das casas decimais do mint e da configuração de autoridade; portanto, gere a mensagem não assinada seguindo as instruções de --help desse comando e verifique todos os endereços antes de coletar as assinaturas.