Guía Completa para Utilizar el Endpoint de Solscan API en Python

python - Tkinter button with Image has borders - Stack Overflow

Solscan es una herramienta poderosa que permite a los desarrolladores y entusiastas de Solana interactuar con la blockchain de manera eficiente. Utilizando la API de Solscan, es posible acceder a información detallada sobre transacciones, cuentas y otros datos relevantes. En esta guía exhaustiva, exploraremos cómo aprovechar el endpoint https://api.solscan.io/api/v1/transaction/{signature} para obtener detalles específicos de una transacción utilizando Python.

Requisitos Previos

1. Cuenta en Solscan y Clave de API

Para acceder a funciones avanzadas y mejorar los límites de tasa, es esencial contar con una clave de API válida. Puedes obtenerla registrándote en el sitio oficial de Solscan y solicitando acceso a través de sus canales de soporte en Solscan.

2. Instalación de Bibliotecas Necesarias

La biblioteca requests es fundamental para realizar solicitudes HTTP en Python. Además, considerar el uso de librerías de terceros como pysolscan puede simplificar el proceso de interacción con la API de Solscan.

Para instalar requests, ejecuta:

pip install requests

Para instalar pysolscan, ejecuta:

pip install pysolscan

Formato del Endpoint

El endpoint que utilizaremos para obtener los detalles de una transacción específica es:

<https://api.solscan.io/api/v1/transaction/{signature}>

signature: Es el identificador único de la transacción que deseas consultar.
Es recomendable incluir encabezados que contengan la clave de API para autenticación y acceso a funcionalidades avanzadas.

Implementación en Python

1. Utilizando la Biblioteca `requests`

Este enfoque es directo y adecuado para consultas básicas a la API.


import requests

def obtener_detalles_transaccion(signature, api_key=None):
    url = f"https://api.solscan.io/api/v1/transaction/{signature}"
    headers = {
        "Accept": "application/json"
    }
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"
    
    try:
        respuesta = requests.get(url, headers=headers)
        respuesta.raise_for_status()  # Verifica si hubo errores en la respuesta HTTP
        datos_transaccion = respuesta.json()
        return datos_transaccion
    except requests.exceptions.HTTPError as http_err:
        print(f"Error HTTP: {http_err}")
    except Exception as err:
        print(f"Error: {err}")
    return None

# Ejemplo de uso
if __name__ == "__main__":
    signature = "TuFirmaDeTransaccionAquí"
    api_key = "TU_API_KEY"  # Opcional, dependiendo de la necesidad de autenticación
    detalles = obtener_detalles_transaccion(signature, api_key)
    if detalles:
        print(detalles)

En este script:

Se define una función obtener_detalles_transaccion que acepta la signature de la transacción y opcionalmente una api_key.
Se construye la URL del endpoint utilizando la signature.
Se establecen los encabezados necesarios, incluyendo la clave de API si se proporciona.
Se realiza una solicitud GET y se maneja la respuesta o los posibles errores.

2. Usando la Librería `pysolscan`

Para quienes prefieren una interfaz más sencilla, pysolscan ofrece un envoltorio minimalista alrededor de la API de Solscan.


from pysolscan import Solscan

def obtener_detalles_transaccion_pysolscan(signature, api_key=None):
    solscan = Solscan(api_key=api_key)
    try:
        transaccion = solscan.get_transaction(signature)
        return transaccion
    except Exception as e:
        print(f"Error al obtener la transacción: {e}")
    return None

# Ejemplo de uso
if __name__ == "__main__":
    signature = "TuFirmaDeTransaccionAquí"
    api_key = "TU_API_KEY"  # Opcional
    detalles = obtener_detalles_transaccion_pysolscan(signature, api_key)
    if detalles:
        print(detalles)

Este enfoque simplifica la interacción con la API, manejando internamente aspectos como la construcción de URLs y la gestión de solicitudes.

Manejo de la Respuesta

La respuesta de la API generalmente está en formato JSON y contiene información detallada sobre la transacción, como el estado, las instrucciones ejecutadas, las direcciones involucradas, y los balances resultantes.

Estructura de la Respuesta

Campo	Descripción
status	Estado de la transacción (ej. "success")
blockTime	Timestamp de la transacción
fee	Tarifa pagada por la transacción
instructions	Lista de instrucciones ejecutadas en la transacción
signatures	Firmas asociadas a la transacción

Manejo de Errores

Es crucial implementar un manejo adecuado de errores para gestionar situaciones como tasas de respuesta no exitosas, problemas de red, o respuestas inesperadas de la API.


try:
    respuesta = requests.get(url, headers=headers)
    respuesta.raise_for_status()
    datos_transaccion = respuesta.json()
    # Procesar datos_transaccion según sea necesario
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except requests.exceptions.ConnectionError as conn_err:
    print(f"Error de conexión: {conn_err}")
except requests.exceptions.Timeout as timeout_err:
    print(f"Tiempo de espera excedido: {timeout_err}")
except requests.exceptions.RequestException as req_err:
    print(f"Error en la solicitud: {req_err}")
except ValueError as json_err:
    print(f"Error al parsear JSON: {json_err}")

Este bloque de código maneja diferentes tipos de excepciones que pueden ocurrir durante la solicitud y el procesamiento de la respuesta.

Consideraciones Adicionales

1. Límites de Tasa y Uso Responsable

La API de Solscan impone límites de tasa para prevenir el abuso y garantizar un rendimiento óptimo. Es recomendable espaciar las solicitudes y manejar adecuadamente los errores relacionados con límites de tasa.

2. Seguridad de la Clave de API

Si estás utilizando una clave de API, asegúrate de mantenerla segura. No la expongas en repositorios públicos y considera el uso de variables de entorno para gestionarla de manera segura.

3. Migración a la Versión v2.0

Solscan ha comenzado a migrar sus endpoints a la versión v2.0. Es esencial verificar que el endpoint v1 siga siendo funcional o considerar actualizar a la versión más reciente consultando la documentación oficial.

Ejemplos Prácticos

Ejemplo 1: Consulta Básica sin Clave de API


import requests

def obtener_transaccion_simple(signature):
    url = f"https://api.solscan.io/api/v1/transaction/{signature}"
    headers = {
        "Accept": "application/json"
    }
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}")
        return None

# Uso del ejemplo
signature = "EjemploDeFirma1234567890abcdef"
detalles = obtener_transaccion_simple(signature)
if detalles:
    print(detalles)

Ejemplo 2: Consulta Avanzada con Manejo de Errores


import requests

def obtener_detalles_avanzados(signature, api_key=None):
    url = f"https://api.solscan.io/api/v1/transaction/{signature}"
    headers = {
        "Accept": "application/json"
    }
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"
    
    try:
        response = requests.get(url, headers=headers, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error: {http_err}")
    except requests.exceptions.Timeout:
        print("La solicitud excedió el tiempo de espera.")
    except requests.exceptions.RequestException as req_err:
        print(f"Error en la solicitud: {req_err}")
    return None

# Uso del ejemplo avanzado
if __name__ == "__main__":
    signature = "OtraFirmaEjemploABCDEF123456"
    api_key = "TU_API_KEY_AQUI"  # Opcional
    detalles = obtener_detalles_avanzados(signature, api_key)
    if detalles:
        print(detalles)

Ejemplo 3: Utilizando `pysolscan` para Simplificar


from pysolscan import Solscan

def consultar_con_pysolscan(signature, api_key=None):
    solscan = Solscan(api_key=api_key)
    try:
        resultado = solscan.get_transaction(signature)
        return resultado
    except Exception as e:
        print(f"Error al consultar con pysolscan: {e}")
    return None

# Uso del ejemplo con pysolscan
if __name__ == "__main__":
    signature = "FirmaEjemploConPysolscan12345"
    api_key = "TU_API_KEY_AQUI"  # Opcional
    detalles = consultar_con_pysolscan(signature, api_key)
    if detalles:
        print(detalles)

Recursos Adicionales

Conclusión

Interactuar con la API de Solscan utilizando Python es una tarea accesible que permite acceder a información valiosa sobre transacciones en la blockchain de Solana. Ya sea mediante la biblioteca requests para una aproximación directa o utilizando librerías especializadas como pysolscan para simplificar el proceso, las herramientas disponibles facilitan la integración eficiente con Solscan. Asegúrate de manejar adecuadamente las claves de API y los posibles errores para garantizar una experiencia de desarrollo fluida y segura.