WithdrawExcessLamports en Solana: guía de SPL Token y Token-2022
Precios y funciones verificados 3 de septiembre de 2026.
WithdrawExcessLamports es la instrucción 38 del Token Program. Resuelve un problema específico: un mint, cuenta de token o multisig puede contener más lamports de los necesarios, pero no pueden moverse mediante una transferencia de tokens normal.
¿Qué hace WithdrawExcessLamports?
WithdrawExcessLamports mueve solo el SOL por encima del mínimo exento de rent actual de una cuenta del Token Program. El origen sigue abierto y sus datos no cambian. El firmante necesario depende de si es una cuenta, mint o token multisig.
La instrucción existe en SPL Token clásico y Token-2022. Antes de la propuesta de rent de 2026 servía para recuperar lamports enviados por error. Un mínimo menor amplía su uso: las cuentas antiguas pueden conservar su saldo original y necesitar una reserva inferior.
El comportamiento y ejemplo actuales están en la documentación de Solana. El procesador también es público en el repositorio del Token Program.
¿Qué cuentas requiere la instrucción?
| Cuenta | ¿Writable? | ¿Firmante? | Función |
|---|---|---|---|
source | Sí | A veces | Cuenta, mint o multisig con lamports excedentes |
destination | Sí | No | Recibe los lamports |
authority | No | Depende del origen | Demuestra permiso |
multiSigners | No | Sí cuando se usa | Cumple el umbral multisig |
El procesador lee el tamaño del origen y el rent actual, calcula el mínimo y transfiere la diferencia. No acepta una reserva proporcionada por el caller.
¿Quién firma para cada origen?
| Origen | Authority requerida |
|---|---|
| Cuenta propiedad de una wallet | Propietario de la cuenta |
| Cuenta propiedad de token multisig | Miembros M-de-N requeridos |
| Mint con mint authority activa | Mint authority actual |
| Mint sin mint authority | La propia cuenta mint |
| Cuenta multisig de origen | Miembros M-de-N configurados |
Si se revocó la authority, un mint on-curve necesita su keypair original. Si es off-curve, su programa controlador debe invocar con las seeds de PDA correctas. Un holder o authority anterior no puede sustituir la firma.
¿Cómo se crea con el cliente de Solana?
El ejemplo oficial usa @solana-program/token y un cliente @solana/kit configurado:
import { getWithdrawExcessLamportsInstruction } from "@solana-program/token";
const instruction = getWithdrawExcessLamportsInstruction({
source,
destination,
authority,
});
await client.sendTransaction([instruction]);
authority es un TransactionSigner adecuado para el origen. Para multisig, incluye cofirmantes con multiSigners. Fija versiones de paquetes y compila con tu release exacta.
No incrustes 0.00203928 SOL como reserva. Es el mínimo heredado de una cuenta estándar de 165 bytes, no un valor actual universal. Consulta el mínimo vigente para el tamaño real justo antes de crear o previsualizar.
¿En qué difieren SPL Token y Token-2022?
El efecto es el mismo, pero Token-2022 hace más peligrosas las suposiciones de tamaño. Las extensiones aumentan los datos serializados y la reserva. Usar siempre 82 o 165 bytes puede sobrestimar el excedente.
CPI Guard también importa para wrappers. Cuando está bloqueado, un CPI puede rechazarse aunque la wallet sea una authority válida. Sol Incinerator omite esos orígenes.
Estas mismas cautelas se aplican al previsualizar Token-2022 y al construir transacciones Token-2022.
Las cuentas nativas de wrapped SOL devuelven NativeNotSupported. Desenvolver SOL usa el cierre de cuenta, no esta instrucción.
¿Cómo envuelve la instrucción la API de Sol Incinerator?
La API v2 crea la llamada mediante Assetcinerator para aplicar on-chain las comisiones de protocolo y partner opcional. Esa comisión pertenece a la capa de producto; la instrucción nativa no la impone.
Usa el preview autenticado:
curl -X POST https://v2.api.sol-incinerator.com/withdraw-excess-lamports/preview \
-H "content-type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"userPublicKey": "DESTINATION_WALLET",
"sourceAccount": "TOKEN_ACCOUNT_MINT_OR_MULTISIG"
}'
Rutas relacionadas:
POST /withdraw-excess-lamportsPOST /withdraw-excess-lamports-instructions
userPublicKey es la wallet de destino y authority predeterminada. Usa authorityPublicKey si firma otra authority y hasta 11 multisigSignerPublicKeys para un token multisig. Las claves privadas permanecen locales.
La comisión base es 200 bps. Un integrador puede añadir partnerFeeAccount y partnerFeeBps; la comisión de red sigue aparte. Usa feeLamports y los campos de recuperación devueltos.
¿Qué errores debe gestionar una integración?
- Sin excedente: el saldo ya está en la reserva.
- Owner o layout incorrecto: no es una cuenta compatible.
- Authority inválida: el firmante no coincide.
- Multisig incompleto: faltan firmantes válidos.
- Cuenta nativa: wrapped SOL usa otra operación.
- CPI Guard bloqueado: Token-2022 rechaza el wrapper.
- Estado cambiado: cambió el saldo, authority o rent tras el preview.
- Coste mayor que valor: un retiro mínimo puede no ser rentable.
Vuelve a previsualizar si el estado puede haber cambiado y no agrupes un origen inválido con trabajo válido.
Sol Incinerator
Previsualiza rent excedente o usa la API v2 para crear un retiro seguro para los firmantes.
Lecturas relacionadas
Preguntas frecuentes
¿Qué hace WithdrawExcessLamports en Solana?
WithdrawExcessLamports transfiere a una wallet de destino los lamports superiores al mínimo exento de rent de una cuenta del Token Program. El origen puede ser una cuenta de token, mint o multisig. No cambia cantidades, supply, authorities, extensiones ni otros datos serializados.
¿Qué authority firma WithdrawExcessLamports?
Una cuenta de token usa su propietario o multisig. Un mint con mint authority activa usa esa authority. Un mint sin ella debe firmar como la propia cuenta de origen mediante su keypair o una ruta CPI del programa que controla un mint off-curve.
¿WithdrawExcessLamports admite Token-2022?
Sí. La instrucción está disponible para cuentas, mints y multisigs de SPL Token clásico y Token-2022. Las integraciones deben calcular el rent con el tamaño real porque las extensiones pueden aumentarlo, y CPI Guard bloqueado puede impedir la ejecución mediante un wrapper.
¿Puede WithdrawExcessLamports dejar una cuenta por debajo de la exención?
No. El Token Program calcula el mínimo y solo transfiere la diferencia superior. Las cuentas nativas de wrapped SOL se rechazan. Las aplicaciones deben previsualizar el estado actual porque saldos, tamaños, rent y authority disponible pueden cambiar antes del envío.