Introducción

Un fallo de autenticación de la API del Pool de ViaBTC no constituye, por sí solo, una prueba de que una clave API haya sido revocada o comprometida. La documentación de la API de ViaBTC distingue varias causas diferentes de una solicitud autenticada fallida: una clave API inválida, un error de firma, un parámetro de marca de tiempo inválido y una dirección IP que no está en la lista blanca de la cuenta. Estas condiciones tienen códigos de error documentados distintos. Una clave API inválida y un error de firma requieren comprobaciones diferentes, pero una clave secreta incorrecta o que no coincide también puede provocar un fallo de firma. Restablecer o eliminar credenciales antes de identificar qué condición se aplica puede interrumpir una integración que funciona correctamente sin resolver el problema de configuración subyacente.

Comience por el código de error devuelto: compruebe la clave API para 12001, la pareja firma/clave secreta para 12002, la marca de tiempo para 12003 y la lista blanca de IP para 12004. Si sospecha que las credenciales han quedado expuestas, rote o elimine las credenciales afectadas de inmediato en lugar de esperar a completar la solución de problemas rutinaria.

Este artículo explica estos requisitos de autenticación, sugiere una secuencia práctica de solución de problemas y describe cuándo es apropiado sustituir el par de claves.

Las credenciales de la API no son las credenciales del worker de minería

Antes de solucionar un error de autenticación, conviene distinguir dos tipos de credenciales no relacionados que a veces se confunden en las solicitudes de soporte.

Una clave API de ViaBTC y su clave secreta asociada son utilizadas por una aplicación externa —un script de monitorización, un panel de control o una herramienta de contabilidad— para solicitar datos a nivel de cuenta, como saldos o estadísticas de hashrate (potencia de cómputo), desde la API del pool. Se introducen en la configuración de esa aplicación, no en el hardware de minería.

Los ASIC y el software de minería, en cambio, se conectan al pool mediante una URL Stratum y un nombre de worker, siguiendo el flujo estándar del protocolo de minería en el que un minero envía shares de prueba de trabajo al pool. Esta conexión no utiliza en absoluto la clave API ni la clave secreta. Si un minero ha dejado de enviar shares o un panel muestra datos de hashrate obsoletos, la primera pregunta que hay que resolver es cuál de estos dos sistemas está fallando realmente, ya que los pasos de diagnóstico de cada uno no están relacionados.

Cómo verifica ViaBTC una solicitud a la API

Según los requisitos de autenticación de la API publicados por ViaBTC, una solicitud puede rechazarse por cualquiera de cuatro razones distintas, y no todos los endpoints comprueban todas ellas de la misma manera.

La cuenta debe tener configurada una lista blanca de IP, y la dirección de origen de la solicitud debe figurar en ella; esta comprobación se aplica independientemente de si el endpoint requiere firma. El encabezado X-API-KEY debe contener un valor que pertenezca a la cuenta o subcuenta que se está consultando. Para los endpoints documentados como que requieren firma, la solicitud debe incluir un encabezado X-SIGNATURE calculado con HMAC-SHA256 usando la clave secreta asociada a esa clave API —calculado a partir de la cadena de consulta para solicitudes GET y DELETE, o a partir del cuerpo JSON de la solicitud para solicitudes POST y PUT. Las solicitudes firmadas deben incluir un parámetro tonce, definido como la marca de tiempo actual en milisegundos, generado inmediatamente antes de crear la firma.

Cada cuenta y subcuenta tiene su propia clave API y clave secreta. La documentación de ViaBTC también señala que una subcuenta utiliza la lista blanca de IP de la cuenta principal solo cuando la lista blanca propia de la subcuenta no se ha configurado; no indica que esta herencia se aplique incondicionalmente, por lo que las operaciones que gestionan varias subcuentas deben confirmar qué lista blanca está realmente vigente para la que produce el error.

Leer el código de error antes de reaccionar

Las respuestas de la API de ViaBTC se devuelven en formato JSON, con un campo code que indica éxito o fallo y un campo message que describe el resultado. Un valor de 0 indica éxito; cualquier otro valor corresponde a un error documentado. La referencia de códigos de error de la API de ViaBTC enumera cuatro códigos relevantes para la autenticación:

Use el código de error para elegir la siguiente comprobación, no para descartar cualquier otro posible problema. Para 12001, verifique la clave API que se está enviando y confirme que la integración utiliza las credenciales de la cuenta prevista. Para 12002, compruebe tanto la clave secreta asociada como la construcción de la firma. Sustituir las credenciales suele ser innecesario en los errores de marca de tiempo o de lista blanca, ya que no corrige esos ajustes.

Una lista de verificación de diagnóstico antes de restablecer las credenciales

A continuación se presenta una secuencia de solución de problemas sugerida. No describe un orden de validación documentado del lado del servidor; utilice el código de error devuelto para priorizar las comprobaciones pertinentes.

1. Registre el code y el message exactos devueltos. Capture el cuerpo de la respuesta JSON (con la clave secreta redactada antes de compartirla en cualquier lugar) en lugar de confiar en un mensaje genérico de "fallo de autenticación" proveniente de una capa de aplicación que puede estar resumiendo varias causas posibles.

2. Confirme si el endpoint requiere firma. La referencia de la API de ViaBTC marca cada endpoint indicando si requiere firma o no. Por ejemplo, el endpoint account-hashrate está documentado como una solicitud GET que solo necesita el parámetro coin y X-API-KEY, sin requerir firma. Si esta solicitud se realiza con éxito y una solicitud firmada que usa la misma clave de API y la misma IP saliente falla con 12002 o 12003, priorice la verificación del emparejamiento de la clave secreta, la construcción de la firma y la generación de la marca de tiempo. La solicitud exitosa solo confirma las condiciones de autenticación de esa solicitud concreta. Para otros códigos de error, siga el error reportado en lugar de asumir que se trata de un problema de firma o de marca de tiempo.

3. Compare la IP de origen de la solicitud con la lista blanca. Un script que sigue funcionando correctamente después de una migración de servidor, un cambio de región en la nube o una nueva puerta de enlace NAT puede seguir fallando con 12004 si su dirección IP saliente cambió y la lista blanca no se actualizó. Esta es una causa común y fácilmente pasada por alto, ya que la clave de API y la clave secreta no se ven afectadas por un cambio de infraestructura de este tipo.

4. Verifique que la clave de API y la clave secreta pertenezcan a la misma cuenta o subcuenta. Dado que cada cuenta y subcuenta tiene su propio par de claves, una integración que supervisa varias subcuentas puede terminar emparejando la clave de API de una cuenta con la clave secreta de otra, particularmente después de un restablecimiento previo de la clave. Esto produce un error de firma aunque ambos valores sean credenciales válidas de forma individual.

5. Reconstruya la firma a partir de los datos exactos que realmente se transmiten. La firma HMAC-SHA256 debe calcularse a partir de la misma cadena de consulta o cuerpo JSON que se envía por la red. Si un middleware de solicitudes, una biblioteca de serialización o un proxy reordena los parámetros, cambia la codificación o añade campos después de que se generó la firma, el servidor calculará una firma distinta a la del cliente y devolverá 12002. La solución en este caso es verificar el flujo de construcción de la solicitud, no asumir que la clave secreta es incorrecta.

6. Compruebe la sincronización del reloj del sistema y las unidades de la marca de tiempo. tonce debe ser una marca de tiempo actual expresada en milisegundos. Un valor de diez dígitos basado en segundos, una marca de tiempo generada mucho antes de que la solicitud se envíe realmente, o un reloj del sistema desincronizado pueden provocar 12003. Ninguno de estos problemas se corrige reemplazando el par de claves.

Si no hay sospecha de exposición de credenciales, complete las verificaciones relevantes para el error reportado antes de reemplazar las credenciales. El reemplazo puede ser apropiado si 12001 persiste después de verificar la clave enviada, o si no se puede recuperar la clave secreta correcta para las solicitudes firmadas. Una sospecha de exposición justifica una rotación o eliminación inmediata sin esperar a completar esta lista de verificación.

Cuándo reemplazar el par de claves es la respuesta adecuada

La guía de configuración de API de ViaBTC documenta las opciones para restablecer un par de clave de API/clave secreta o eliminarlo; la eliminación requiere verificación por correo electrónico y un código de Google Authenticator. Restablecer o eliminar credenciales es una respuesta razonable en varias situaciones específicas:

• El error persiste como 12001 después de confirmar que la solicitud envía la clave correcta para la cuenta o subcuenta correcta.
• La clave secreta se perdió o nunca se registró, lo que hace imposible restaurar una integración firmada.
• Una integración o aplicación de terceros se ha retirado y ya no necesita acceso.
• Existe cualquier motivo para sospechar que la clave o la clave secreta se han expuesto — por ejemplo, pegadas en un repositorio público, una captura de pantalla, un registro de chat o un ticket de soporte.

En el caso específico de exposición, una rotación o eliminación inmediata es apropiada sin necesidad de una solución de problemas extensa, ya que el riesgo de continuar usando las credenciales supera el valor de diagnosticar el error original. ViaBTC recomienda mantener confidenciales tanto la clave de API como la clave secreta, y esto se aplica durante todo el proceso de solución de problemas — ninguno de los dos valores debe compartirse en una solicitud de soporte, publicación en un foro o archivo de registro. Se pueden configurar hasta 20 direcciones IP por lista blanca de cuenta, una por línea, lo cual generalmente es suficiente para cubrir un pequeño número de servidores de aplicaciones sin necesidad de relajar la lista blanca como solución alternativa.

Preguntas frecuentes

¿Es necesario introducir una clave de API en la configuración de mi ASIC?

No. La clave de API y la clave secreta autentican las solicitudes a la API del Pool de ViaBTC desde una aplicación externa. Los ASIC y el software de minería se conectan al pool mediante una URL Stratum y un nombre de worker, que es un sistema de credenciales independiente.

Mi clave de API es correcta, entonces ¿por qué la solicitud falla con "IP no permitida"?

La API de ViaBTC verifica la dirección IP de origen de la solicitud contra la lista blanca configurada de la cuenta de manera independiente de si la clave de API en sí es válida. Una clave correcta enviada desde una dirección que no está en la lista blanca sigue devolviendo el error 12004.

¿Por qué un endpoint devuelve un error de firma mientras otro funciona bien con la misma clave?

No todos los endpoints de ViaBTC requieren firma. Un endpoint sin firma puede tener éxito sin X-SIGNATURE cuando se cumplen sus demás requisitos. Si un endpoint firmado devuelve 12002 usando la misma clave de API y la misma IP saliente, verifique que la clave secreta esté emparejada con esa clave de API y que la firma se calcule a partir de los datos de solicitud transmitidos.

¿Debo restablecer mi clave de API después de recibir un error de tonce inválido?

No como primer paso. El error 12003 apunta al parámetro de marca de tiempo en lugar de a la clave. Compruebe que el reloj del sistema esté sincronizado y que tonce se envíe como una marca de tiempo actual en milisegundos en lugar de segundos antes de considerar cualquier cambio de credenciales.

Referencias

• ViaBTC Pool API, "API Authentication", wiki de GitHub.
• ViaBTC Pool API, "Error Code", wiki de GitHub.
• ViaBTC Pool API, "Acquire Account Hashrate", wiki de GitHub.
• Centro de Ayuda de ViaBTC, "What is API and How to Set Up".