Referencia de la CLI de SPL Token

La interfaz de línea de comandos spl-token crea y administra mints, token accounts, autoridades, transferencias y extensiones de Token-2022.

Esta referencia sigue spl-token-cli v5.6.1, la versión incluida con Agave v4.2.1. Ejecuta spl-token --version y usa <command> --help para ver las opciones exactas disponibles en tu versión instalada.

La creación de mints, las transferencias, los cambios de autoridad, las quemas, los congelamientos y el cierre de cuentas envían transacciones. Confirma el clúster, el Token Program, el firmante y las direcciones antes de ejecutar un comando. Los cambios en Mainnet usan activos reales.

Instalación y ayuda

El paquete de versión de Agave CLI incluye spl-token. Si no está instalado, usa el crate de Rust publicado:

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

Consulta la ayuda en la raíz o a nivel de comando:

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

Opciones globales

Coloca las opciones globales antes del comando.

Opción	Propósito
`-u, --url <URL_OR_MONIKER>`	Selecciona una URL de RPC o `mainnet-beta`, `testnet`, `devnet` o `localhost`.
`-C, --config <PATH>`	Usa un archivo de configuración de Solana CLI diferente.
`--fee-payer <KEYPAIR>`	Selecciona la cuenta que paga las comisiones de transacción.
`-p, --program-id <ADDRESS>`	Usa un ID de Token Program explícito.
`--program-2022`	Usa Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`).
`--output <FORMAT>`	Devuelve `json` o `json-compact` donde sea compatible.
`--with-compute-unit-limit <UNITS>`	Establece el límite de unidades de cómputo de la transacción.
`--with-compute-unit-price <MICRO_LAMPORTS>`	Establece el precio de prioridad por unidad de cómputo.
`-v, --verbose`	Muestra salida adicional.
`-V, --version`	Imprime la versión instalada de la CLI.

El programa predeterminado es el Token Program original. Usa --program-2022 para un mint o una cuenta de Token-2022, incluso al leerlos. Un comando falla si el programa seleccionado no es el propietario de la dirección proporcionada.

Crear y usar un token

Los comandos imprimen las direcciones creadas. Guarda la dirección del mint devuelta por create-token para los comandos siguientes.

# 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

Los importes son importes de token en la interfaz, ajustados a los decimales del mint. Comandos como transfer, burn y unwrap-sol aceptan ALL donde se indica en su ayuda.

Crear un mint de Token-2022

Las extensiones asignan estado adicional al mint o a la cuenta y, por lo general, deben elegirse cuando se crea el mint. Este ejemplo crea un mint de seis decimales con compatibilidad de metadatos integrados:

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

Las opciones de extensión más comunes de create-token incluyen:

--enable-close
--enable-confidential-transfers auto|manual
--enable-freeze
--enable-group y --enable-member
--enable-metadata
--enable-non-transferable
--enable-pause
--enable-permanent-delegate
--enable-permissioned-burn
--enable-transfer-hook o --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 las extensiones que el programa Token-2022 permita usar juntas. Revisa la guía de extensiones de Token-2022 correspondiente antes de crear una configuración de mint irreversible.

Administrar autoridades y 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 admite los tipos de autoridad mint, freeze, owner, close y específicos de extensiones. Eliminar una autoridad con --disable es permanente cuando ningún otro mecanismo del programa puede restablecerla.

Congelar, quemar y cerrar

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 reduce tanto el saldo de la cuenta como el suministro total. close devuelve los lamports restantes de la cuenta al destinatario configurado; no recupera los tokens quemados.

Envolver y desenvolver 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 después de transferir lamports directamente a una token account de SOL envuelto para que su importe de tokens coincida con los lamports subyacentes.

Firma multisig

Crea una multisig de Token Program M de N con hasta 11 miembros:

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

Para una transacción controlada por esa multisig, pasa la dirección de la multisig como la autoridad correspondiente y proporciona los keypairs de los miembros mediante valores --multisig-signer repetidos. Consulta la ayuda del comando de destino, porque su indicador de autoridad principal varía según la operación.

Saldos confidenciales

Los comandos de saldo confidencial requieren un mint de Token-2022 configurado para transferencias confidenciales y una cuenta de destinatario 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 y apply-pending-balance, pasa --address <TOKEN_ACCOUNT_ADDRESS> o un <MINT_ADDRESS> posicional, pero no ambos. La forma posicional usa la associated token account del propietario. Los depósitos y retiros siempre toman el mint y aceptan --address para reemplazar esa cuenta predeterminada.

Usa enable-confidential-credits, disable-confidential-credits, enable-non-confidential-credits y disable-non-confidential-credits para controlar qué depósitos acepta la cuenta. Estos ajustes afectan la privacidad de la cuenta y la compatibilidad de pagos; inspecciona la cuenta antes de cambiarlos.

Índice completo de comandos

El siguiente índice incluye todos los comandos de nivel superior de spl-token-cli v5.6.1.

Comando	Descripción
`accounts`	Lista las token accounts que pertenecen a una billetera, con filtro opcional por mint.
`address`	Imprime la dirección de la billetera seleccionada o su dirección de token asociada.
`apply-pending-balance`	Mueve los tokens confidenciales pendientes al saldo confidencial disponible.
`approve`	Aprueba un delegado y un límite de gasto para una token account.
`authorize`	Cambia o desactiva la autoridad de un mint, una cuenta o una extensión.
`balance`	Muestra el saldo de una token account.
`bench`	Ejecuta comandos de evaluación comparativa de tokens.
`burn`	Destruye tokens de una cuenta y reduce el suministro del mint.
`close`	Cierra una token account elegible y recupera sus lamports.
`close-mint`	Cierra un mint de Token-2022 configurado con la extensión close-mint.
`configure-confidential-transfer-account`	Configura una cuenta para usar transferencias confidenciales.
`create-account`	Crea una token account asociada o auxiliar.
`create-multisig`	Crea una multisig de Token Program M de N.
`create-token`	Crea un mint, opcionalmente con extensiones de Token-2022.
`deposit-confidential-tokens`	Mueve tokens no confidenciales a un saldo confidencial pendiente.
`disable-confidential-credits`	Rechaza las transferencias confidenciales entrantes de una cuenta.
`disable-cpi-guard`	Desactiva CPI Guard para una cuenta.
`disable-non-confidential-credits`	Rechaza las transferencias no confidenciales entrantes de una cuenta confidencial.
`disable-required-transfer-memos`	Deja de exigir que las transferencias entrantes incluyan memos.
`display`	Muestra los detalles completos de un mint, una token account o una multisig.
`enable-confidential-credits`	Acepta transferencias confidenciales entrantes para una cuenta configurada.
`enable-cpi-guard`	Restringe determinadas operaciones de token cuando se invocan mediante CPI.
`enable-non-confidential-credits`	Acepta transferencias no confidenciales entrantes para una cuenta confidencial.
`enable-required-transfer-memos`	Exige que las transferencias entrantes incluyan memos.
`freeze`	Congela una token account usando la autoridad de congelación del mint.
`gc`	Cierra las token accounts innecesarias y consolida los saldos cuando es posible.
`help`	Imprime la ayuda raíz o la de un comando.
`initialize-group`	Inicializa la configuración de grupo de Token-2022 para un mint.
`initialize-member`	Agrega un mint de Token-2022 como miembro de un grupo.
`initialize-metadata`	Inicializa los metadatos integrados de Token-2022.
`mint`	Crea nuevas unidades de token usando la autoridad del mint.
`pause`	Pausa la emisión, la quema y la transferencia de un mint de Token-2022 pausable.
`resume`	Reanuda las operaciones de un mint de Token-2022 en pausa.
`revoke`	Elimina el delegado de una token account.
`set-interest-rate`	Actualiza la tasa de un mint que genera intereses.
`set-transfer-fee`	Programa nuevos parámetros de comisión de transferencia.
`set-transfer-hook`	Cambia el ID del programa de transfer hook de un mint.
`supply`	Muestra el suministro total de un mint.
`sync-native`	Sincroniza el importe de una cuenta de SOL envuelto con sus lamports.
`thaw`	Descongela una token account congelada.
`transfer`	Transfiere tokens a una token account o a una billetera.
`unwrap`	Cierra una cuenta de SOL envuelto y recupera todos los lamports.
`unwrap-sol`	Retira una parte o la totalidad del SOL de una cuenta de SOL envuelto.
`update-confidential-transfer-settings`	Actualiza la aprobación de transferencias confidenciales o la configuración de auditor de un mint.
`update-default-account-state`	Cambia el estado predeterminado de un mint para las nuevas token accounts.
`update-group-address`	Cambia la dirección del puntero de grupo de un mint.
`update-group-max-size`	Cambia el número máximo de miembros de un grupo de tokens.
`update-member-address`	Cambia la dirección del puntero de miembro de grupo de un mint.
`update-metadata`	Cambia o elimina campos de metadatos integrados.
`update-metadata-address`	Cambia la dirección del puntero de metadatos de un mint.
`update-ui-amount-multiplier`	Programa un nuevo multiplicador de importe de UI escalado.
`withdraw-confidential-tokens`	Devuelve tokens confidenciales al saldo no confidencial.
`withdraw-excess-lamports`	Retira los lamports que superan el saldo exento de renta de una cuenta del Token Program.
`withdraw-withheld-tokens`	Recoge las comisiones de transferencia retenidas en token accounts o en el mint.
`wrap`	Envuelve SOL en una token account del mint nativo.

Firma estructurada y sin conexión

Usa la salida estructurada en lugar de analizar el texto mostrado:

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

Los comandos que producen transacciones suelen admitir --sign-only, --blockhash, --signer <PUBKEY=SIGNATURE>, --nonce y --nonce-authority. Las entradas exactas para firmar sin conexión dependen del comando, de los decimales del mint y de la disposición de autoridades, así que genera el mensaje sin firmar siguiendo las instrucciones de --help de ese comando y verifica cada dirección antes de recopilar firmas.

Tabla de Contenidos