Riferimento della CLI di SPL Token

L'interfaccia a riga di comando spl-token crea e gestisce mint, token account, authority, trasferimenti ed estensioni di Token-2022.

Questo riferimento segue spl-token-cli v5.6.1, la versione inclusa in Agave v4.2.1. Esegui spl-token --version e usa <command> --help per vedere le opzioni esatte disponibili nella versione installata.

La creazione di mint, i trasferimenti, le modifiche alle authority, i burn, i freeze e la chiusura degli account inviano transazioni. Verifica cluster, Token Program, firmatario e indirizzi prima di eseguire un comando. Le modifiche su Mainnet usano asset reali.

Installazione e guida in linea

Il bundle di release della CLI di Agave include spl-token. Se non è installato, usa il crate Rust pubblicato:

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

Consulta la guida dalla radice o a livello di comando:

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

Opzioni globali

Inserisci le opzioni globali prima del comando.

Opzione	Scopo
`-u, --url <URL_OR_MONIKER>`	Seleziona un URL RPC oppure `mainnet-beta`, `testnet`, `devnet` o `localhost`.
`-C, --config <PATH>`	Usa un file di configurazione della CLI di Solana diverso.
`--fee-payer <KEYPAIR>`	Seleziona l'account che paga le commissioni di transazione.
`-p, --program-id <ADDRESS>`	Usa un ID esplicito del Token Program.
`--program-2022`	Usa Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`).
`--output <FORMAT>`	Restituisce `json` o `json-compact` dove supportato.
`--with-compute-unit-limit <UNITS>`	Imposta il limite di compute unit della transazione.
`--with-compute-unit-price <MICRO_LAMPORTS>`	Imposta il prezzo di priorità per compute unit.
`-v, --verbose`	Mostra output aggiuntivo.
`-V, --version`	Stampa la versione installata della CLI.

Il programma predefinito è il Token Program originale. Usa --program-2022 per un mint o un account Token-2022, anche in lettura. Un comando fallisce se il programma selezionato non è il proprietario dell'indirizzo fornito.

Creare e usare un token

I comandi stampano gli indirizzi creati. Salva l'indirizzo del mint restituito da create-token per i comandi successivi.

# 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

Gli importi sono importi di token in formato UI, adattati ai decimali del mint. Comandi come transfer, burn e unwrap-sol accettano ALL dove indicato nella rispettiva guida.

Creare un mint Token-2022

Le estensioni allocano stato aggiuntivo per il mint o l'account e di solito devono essere scelte quando il mint viene creato. Questo esempio crea un mint con sei decimali e supporto ai metadati incorporati:

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

Le opzioni di estensione più comuni di create-token includono:

--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 oppure --transfer-hook <PROGRAM_ID>
--interest-rate <BASIS_POINTS>
--transfer-fee-basis-points <BASIS_POINTS> con --transfer-fee-maximum-fee <AMOUNT>
--ui-amount-multiplier <MULTIPLIER>

Combina solo le estensioni che il programma Token-2022 consente di usare insieme. Consulta la guida alle estensioni di Token-2022 pertinente prima di creare una configurazione del mint irreversibile.

Gestire authority e delegati

# 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 supporta i tipi di authority mint, freeze, owner, close e quelli specifici delle estensioni. Rimuovere un'authority con --disable è permanente se nessun altro meccanismo del programma può ripristinarla.

Freeze, burn e chiusura

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 riduce sia il saldo dell'account sia la supply totale. close restituisce i lamport rimanenti dell'account al destinatario configurato; non recupera i token bruciati.

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

Usa sync-native dopo aver trasferito lamport direttamente in un token account di SOL wrapped, in modo che il suo importo in token corrisponda ai lamport sottostanti.

Firma multisig

Crea un multisig M-of-N del Token Program con fino a 11 membri:

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

Per una transazione controllata da quel multisig, passa l'indirizzo del multisig come authority pertinente e fornisci i keypair dei membri tramite valori --multisig-signer ripetuti. Controlla la guida del comando di destinazione, perché il flag dell'authority principale varia a seconda dell'operazione.

Saldi confidenziali

I comandi per i saldi confidenziali richiedono un mint Token-2022 configurato per i trasferimenti confidenziali e un account destinatario configurato.

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

Per configure-confidential-transfer-account e apply-pending-balance, passa --address <TOKEN_ACCOUNT_ADDRESS> oppure un <MINT_ADDRESS> posizionale, non entrambi. La forma posizionale usa l'associated token account del proprietario. Deposito e prelievo richiedono sempre il mint e accettano --address per sostituire quell'account predefinito.

Usa enable-confidential-credits, disable-confidential-credits, enable-non-confidential-credits e disable-non-confidential-credits per controllare quali depositi l'account accetta. Queste impostazioni influiscono sulla privacy dell'account e sulla compatibilità dei pagamenti; ispeziona l'account prima di modificarle.

Indice completo dei comandi

L'indice seguente include tutti i comandi di primo livello di spl-token-cli v5.6.1.

Comando	Descrizione
`accounts`	Elenca i token account di proprietà di un wallet, con filtro facoltativo per mint.
`address`	Stampa l'indirizzo del wallet selezionato o quello del relativo associated token account.
`apply-pending-balance`	Sposta i token confidenziali in sospeso nel saldo confidenziale disponibile.
`approve`	Approva un delegato e un limite di spesa per un token account.
`authorize`	Cambia o disabilita un'authority di mint, account o estensione.
`balance`	Mostra il saldo di un token account.
`bench`	Esegue i comandi di benchmarking dei token.
`burn`	Distrugge i token di un account e riduce la supply del mint.
`close`	Chiude un token account idoneo e ne recupera i lamport.
`close-mint`	Chiude un mint Token-2022 configurato con l'estensione close-mint.
`configure-confidential-transfer-account`	Configura un account per usare i trasferimenti confidenziali.
`create-account`	Crea un associated token account o un token account ausiliario.
`create-multisig`	Crea un multisig M-of-N del Token Program.
`create-token`	Crea un mint, facoltativamente con estensioni Token-2022.
`deposit-confidential-tokens`	Sposta i token non confidenziali in un saldo confidenziale in sospeso.
`disable-confidential-credits`	Rifiuta i trasferimenti confidenziali in entrata per un account.
`disable-cpi-guard`	Disabilita CPI Guard per un account.
`disable-non-confidential-credits`	Rifiuta i trasferimenti non confidenziali in entrata per un account confidenziale.
`disable-required-transfer-memos`	Smette di richiedere che i trasferimenti in entrata includano memo.
`display`	Mostra i dettagli completi di un mint, token account o multisig.
`enable-confidential-credits`	Accetta i trasferimenti confidenziali in entrata per un account configurato.
`enable-cpi-guard`	Limita determinate operazioni sui token quando vengono invocate tramite CPI.
`enable-non-confidential-credits`	Accetta i trasferimenti non confidenziali in entrata per un account confidenziale.
`enable-required-transfer-memos`	Richiede che i trasferimenti in entrata includano memo.
`freeze`	Congela un token account usando la freeze authority del mint.
`gc`	Chiude i token account non necessari e consolida i saldi dove possibile.
`help`	Stampa la guida generale o quella di un comando.
`initialize-group`	Inizializza la configurazione di gruppo Token-2022 per un mint.
`initialize-member`	Aggiunge un mint Token-2022 come membro di un gruppo.
`initialize-metadata`	Inizializza i metadati incorporati di Token-2022.
`mint`	Crea nuove unità di token usando la mint authority.
`pause`	Mette in pausa mint, burn e transfer per un mint Token-2022 con funzione di pausa.
`resume`	Riprende le operazioni di un mint Token-2022 in pausa.
`revoke`	Rimuove il delegato di un token account.
`set-interest-rate`	Aggiorna il tasso di un mint che matura interessi.
`set-transfer-fee`	Pianifica nuovi parametri per la commissione di trasferimento.
`set-transfer-hook`	Cambia l'ID del programma transfer hook di un mint.
`supply`	Mostra la supply totale di un mint.
`sync-native`	Sincronizza l'importo di un account SOL wrapped con i relativi lamport.
`thaw`	Scongela un token account congelato.
`transfer`	Trasferisce token a un token account o a un wallet.
`unwrap`	Chiude un account SOL wrapped e recupera tutti i lamport.
`unwrap-sol`	Rimuove una parte o la totalità dei SOL da un account SOL wrapped.
`update-confidential-transfer-settings`	Aggiorna le impostazioni di approvazione o di auditor dei trasferimenti confidenziali per un mint.
`update-default-account-state`	Cambia lo stato predefinito di un mint per i nuovi token account.
`update-group-address`	Cambia l'indirizzo del group pointer di un mint.
`update-group-max-size`	Cambia il numero massimo di membri di un gruppo di token.
`update-member-address`	Cambia l'indirizzo del group member pointer di un mint.
`update-metadata`	Modifica o rimuove i campi dei metadati incorporati.
`update-metadata-address`	Cambia l'indirizzo del metadata pointer di un mint.
`update-ui-amount-multiplier`	Pianifica un nuovo moltiplicatore per l'importo UI scalato.
`withdraw-confidential-tokens`	Riporta i token confidenziali al saldo non confidenziale.
`withdraw-excess-lamports`	Preleva da un account del Token Program i lamport eccedenti il saldo esente da rent.
`withdraw-withheld-tokens`	Raccoglie le commissioni di trasferimento trattenute nei token account o nel mint.
`wrap`	Esegue il wrap di SOL in un token account del mint nativo.

Firma strutturata e offline

Usa l'output strutturato anziché analizzare il testo visualizzato:

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

I comandi che producono transazioni supportano comunemente --sign-only, --blockhash, --signer <PUBKEY=SIGNATURE>, --nonce e --nonce-authority. Gli input offline esatti dipendono dal comando, dai decimali del mint e dalla configurazione delle authority, quindi genera il messaggio non firmato seguendo le istruzioni di --help di quel comando e verifica ogni indirizzo prima di raccogliere le firme.

Indice dei contenuti