Decimales de tokens ERC-20: del saldo bruto a una cantidad legible

Para convertir un saldo bruto ERC-20 en una cantidad legible de tokens, divide el entero entre 10 elevado a los decimales verificados del token. Hazlo solo si el valor sigue en unidades base brutas. Una cartera o un explorador puede haber realizado ya la conversión.

Por ejemplo, un saldo bruto de 1234567 con 6 decimales representa 1.234567 tokens. El mismo entero bruto con 18 decimales representa 0.000000000001234567 tokens. Ningún resultado indica un valor en dólares. Son ejemplos aritméticos hipotéticos, no saldos consultados en una cartera.

Qué cambian los decimales al leer un saldo

El método balanceOf de un contrato ERC-20 devuelve un entero. La especificación ERC-20 describe decimals como la escala para presentar una cantidad de tokens al usuario. Piensa en el entero como un recuento de las unidades contables más pequeñas del token, y en los decimales como la indicación de dónde colocar el punto decimal en pantalla.

El cálculo es:

Cantidad legible de tokens = entero bruto dividido entre (10 elevado a decimals).

En este artículo todos los enteros brutos están escritos en base 10, sin separadores de miles. Un valor hexadecimal que empieza por 0x debe decodificarse primero como entero. Las letras y cifras de esa codificación no son una cantidad decimal de tokens que puedas copiar sin cambios en esta división.

Este es el mismo entero hipotético con tres escalas distintas:

Entero bruto	Decimales	Cantidad de tokens
1234567	6	1.234567
1234567	18	0.000000000001234567
1234567	0	1234567

Con 0 decimales, el divisor es 1. Con 6, un token entero corresponde a 1000000 unidades brutas. Con 18, corresponde a 1000000000000000000 unidades brutas. El tamaño del entero por sí solo no indica qué escala corresponde.

Determina la escala antes de calcular

Empieza por la red y la dirección completa del contrato del token. El símbolo es una etiqueta, no un identificador único. Si no sabes qué dirección pertenece al token y cuál al titular, consulta primero la guía de dirección de cartera y contrato del token.

Usa la información oficial de despliegue del proyecto para esa red para establecer la identidad del contrato. Después consulta su resultado de solo lectura decimals mediante un explorador o lector de contratos de confianza. Registra el resultado junto con el contrato y la red. Los metadatos de otro despliegue no determinan la escala de tu tenencia.

No sustituyas un decimals ausente por 18. ERC-20 define el método como opcional. La referencia ERC20 de OpenZeppelin documenta un valor predeterminado de 18 en su implementación, que puede sobrescribirse. Ese valor de una implementación no es una regla universal de los tokens. La misma referencia explica que los decimales sirven para el formato de visualización y no cambian la aritmética entera del contrato para saldos y transferencias.

Si falla la lectura, distingue una fuente no disponible de un contrato que no expone metadatos utilizables. Prueba una fuente de confianza para el mismo despliegue o consulta su implementación documentada. Si la escala sigue sin establecerse, conserva el entero bruto y marca la cantidad legible como sin resolver. Un número plausible no es una conversión verificada.

Comprueba si el número ya está formateado

Antes de aplicar la fórmula, lee la etiqueta del campo y la documentación de la fuente. Un resultado bruto del contrato, una cantidad normalizada de una API y una visualización redondeada de una cartera pueden describir la misma tenencia de formas distintas. Un punto decimal sugiere formato, pero su ausencia no demuestra que el valor sea bruto: una cantidad formateada puede ser exactamente 2 tokens.

Para un token hipotético de 6 decimales, el valor bruto 2500000 se convierte en 2.5 tokens. Si tu cartera ya muestra 2.5 tokens, dividir esa cifra entre 1000000 produce 0.0000025, una segunda conversión incorrecta.

Una vez obtenida la cantidad exacta de tokens, aplica por separado el redondeo de visualización. El valor bruto 1 con 6 decimales es 0.000001 tokens. Una interfaz limitada a 4 posiciones decimales puede mostrar 0.0000. Esa etiqueta redondeada no demuestra un saldo vacío. Conserva el resultado preciso al investigar una discrepancia, sin inventar más cifras significativas que las permitidas por la precisión de la fuente.

Para un script o una hoja de cálculo, conserva el entero bruto como texto o entero exacto hasta formatearlo. Los enteros grandes pueden perder precisión en un Number corriente de JavaScript, como explica la referencia de enteros seguros de MDN. La división no recupera precisión ya perdida. La documentación de ethers v6 ofrece formatUnits, que devuelve una cadena decimal. Pasa explícitamente los decimales verificados y conserva esa cadena en vez de convertirla por comodidad en un número impreciso.

Concilia dos lecturas sin mover tokens

Usa una misma tenencia para la comprobación. Leer datos públicos del contrato no requiere una transferencia, una aprobación, una frase de recuperación ni una firma de la cartera.

1. Fija la identidad. Registra la red, la dirección pública del titular y el contrato verificado del token. No sustituyas al titular por la dirección del contrato al leer su saldo.
2. Registra la observación. Guarda la hora y el número de bloque cuando esté disponible. Prioriza lecturas del mismo bloque. De lo contrario, una transferencia entre observaciones puede impedir una coincidencia exacta.
3. Etiqueta los datos. Guarda el valor original, si es bruto o formateado, y las pruebas de los decimales del contrato. Si una fuente no explica sus unidades, detén ahí la conversión.
4. Escala una vez. Convierte el entero bruto con esos decimales, conservando las cifras exactas antes del redondeo de visualización. Deja tal cual una cantidad ya proporcionada en unidades de token.
5. Compara unidades iguales. Compara esa cantidad de tokens con la de la otra pantalla con precisión compatible. Ante un cero redondeado, solicita más detalle antes de concluir que el saldo bruto es cero.
6. Trata la diferencia restante. Si coinciden identidad, instantánea y unidades, pero no las cantidades, registra ambas lecturas y sus fuentes. Si falló una fuente, marca la lectura como no disponible en vez de insertar cero. La guía de discrepancias del portafolio cubre respuestas ausentes, precios y cobertura de posiciones.

El resultado útil es un registro que otra persona pueda reproducir: qué contrato, el saldo de quién, qué observación, qué valor bruto, qué decimales y qué cantidad convertida. Una transacción no forma parte de demostrar la conversión.

Separa la cantidad de tokens de su valor

El formato te da un recuento de este token. Una estimación en dólares necesita además un precio para ese activo exacto, en una moneda indicada y en un momento indicado. Los decimales no establecen ese precio, la liquidez de negociación ni la seguridad del contrato. Un token desconocido puede devolver un valor de decimals perfectamente corriente.

Un token de recibo o un token envuelto introduce otra pregunta: ¿cuánto activo subyacente representa cada token? Convertir su saldo bruto da tokens de recibo o envueltos. Cualquier equivalente en activo subyacente necesita el método de conversión y las unidades del protocolo correspondiente. Los decimales del token no sustituyen ese tipo de cambio, y una razón del protocolo como el factor de salud necesita su propia escala documentada.

Si el número sigue pareciendo incorrecto, conserva la incógnita que importa. Los decimales desconocidos dejan sin resolver la cantidad legible. Una cantidad conocida con precio desconocido deja sin resolver la valoración. Mantener explícitas esas lagunas ofrece una siguiente comprobación útil sin cambiar la tenencia que intentas entender.