Primeros pasos con el SDK de Python de Dexalot

Esta guía te guía por la instalación del SDK de Python de Dexalot, la conexión al exchange y la ejecución de tus primeras operaciones. Al final, sabrás cómo leer libros de órdenes, colocar y cancelar órdenes, ejecutar swaps y comprobar tus saldos — todo desde Python.

Mantendremos las cosas prácticas. Cada ejemplo aquí es algo que puedes ejecutar de inmediato.

Instalación

Necesitas Python 3.12 o superior. Puedes descargarlo e instalarlo para tu plataforma desde python.org. Después de configurar el entorno de Python, instala el SDK de Python de Dexalot desde PyPi.

pip install dexalot-sdk

O si estás usando uv (que recomendamos para gestionar dependencias más rápido):

uv add dexalot-sdk

A continuación, crea un archivo .env en la raíz de tu proyecto con el entorno al que quieres conectarte:

PARENTENV=fuji-multi

Esto es fuji-multi para testnet, o production-multi cuando estés listo para mainnet. Para operaciones de solo lectura como obtener libros de órdenes y listas de tokens, con esto ya tienes suficiente. Añadiremos credenciales de firma en breve. Puedes explorar el archivo env.example para ver la lista completa de variables que puedes usar.

Tu Primera Conexión

El SDK es async-first, por lo que todas las operaciones se ejecutan dentro de un contexto asíncrono. Aquí tienes la conexión más simple posible — leer los pares de trading disponibles y mostrar los primeros:

import asyncio
from dexalot_sdk import DexalotClient

async def main():
    async with DexalotClient() as client:
        await client.initialize_client()

        pairs = await client.get_clob_pairs()
        if pairs.success:
            for pair in pairs.data[:5]:
                print(pair["pair"])
        else:
            print("Error:", pairs.error)

asyncio.run(main())

Hay algunas cosas a tener en cuenta. El bloque async with gestiona por ti la apertura y el cierre de la sesión HTTP automáticamente. La llamada initialize_client() carga la configuración del exchange — metadatos de tokens, direcciones de contratos, detalles de la cadena — para que el cliente sepa cómo hablar con el protocolo. Y el resultado se devuelve como un objeto Result: comprueba .success antes de acceder a .data y lee .error si algo salió mal.

Este patrón — comprobar el resultado y luego actuar — es consistente en cada método del SDK. No hay excepciones ocultas para fallos esperados.

Lectura del Libro de Órdenes

Una vez conectado, obtener el libro de órdenes para un par de trading es de una sola línea:

ob = await client.get_orderbook("ALOT/USDC")
if ob.success:
    book = ob.data
    print("Mejor puja:", book["bids"][0])
    print("Mejor oferta:", book["asks"][0])

Los datos del libro de órdenes se almacenan en caché durante un segundo por defecto, lo que significa que llamadas rápidas y consecutivas no saturarán la API. Si necesitas datos más frescos para estrategias de alta frecuencia, puedes reducir el TTL de la caché o desactivarla por completo (más abajo).

Configurar un Firmante para Trading

El acceso de solo lectura es útil, pero para colocar órdenes, ejecutar swaps o mover fondos, necesitas una cartera con firma. El enfoque recomendado es pasar un objeto firmante directamente para que tu clave privada sin procesar nunca quede en un archivo de configuración:

from eth_account import Account

signer = Account.from_key("0xYOUR_PRIVATE_KEY")

async with DexalotClient(signer=signer) as client:
    await client.initialize_client()
    # Ahora ya puedes operar

Para entornos de producción, el SDK también incluye un vault de secretos cifrado. Almacena tus claves en un archivo cifrado en el disco — solo se ven los nombres de las claves, los valores se cifran en reposo. Generas una clave de cifrado una sola vez, la guardas en tu gestor de contraseñas, y la usas para desbloquear el vault en tiempo de ejecución:

secrets-vault keygen          # genera tu clave de cifrado, guárdala de forma segura
secrets-vault add PRIVATE_KEY 0xabc123...

Luego, en tiempo de ejecución, configura DEXALOT_SECRETS_VAULT_KEY como variable de entorno o deja que el SDK te lo pida. Esto mantiene tu clave en bruto completamente fuera de .env y del control de versiones.

Importante: Nunca confirmes en el control de versiones claves privadas ni claves de cifrado del vault. Usa un gestor de contraseñas o un gestor de secretos como AWS Secrets Manager o HashiCorp Vault para producción.

Hacer tu Primer Pedido

Con un firmante conectado, un pedido de compra con límite se ve así:

result = await client.add_order(
    pair="ALOT/USDC",
    side="BUY",
    amount=100.0,
    price=0.15,
    order_type="LIMIT",
)
if result.success:
    print("Transaction:", result.data["tx_hash"])
    print("Order ID:", result.data["client_order_id"])
else:
    print("Failed:", result.error)

El SDK se encarga de todo por debajo del capó: convierte tus importes legibles por humanos al formato atómico en cadena, gestiona el nonce de la transacción para que no obtengas errores de nonce duplicado, estima el gas, firma la transacción y la envía. Obtienes un hash de transacción y un client order ID que puedes usar más tarde para cancelar o reemplazar el pedido.

¿Quieres cancelarlo?

result = await client.cancel_order(order_id="0xabc...")

¿Necesitas cancelarlo todo?

result = await client.cancel_all_orders()

Operaciones por Lotes: Varios Pedidos en un Solo Envío

Si estás gestionando múltiples posiciones, el SDK admite operaciones por lotes que agrupan varios pedidos en una sola transacción on-chain. Esto ahorra gas y reduce la latencia:

orders = [
    {"pair": "ALOT/USDC", "side": "BUY", "amount": 50.0, "price": 0.14},
    {"pair": "ALOT/USDC", "side": "BUY", "amount": 75.0, "price": 0.13},
]
result = await client.add_limit_order_list(orders)

También existe una operación atómica de cancelar y reemplazar. Elimina tus pedidos existentes y coloca los nuevos en la misma transacción — no hay un hueco en el que no estés cubierto (unhedged):

result = await client.cancel_add_list(
    replacements=[
        {
            "order_id": "0xold...",
            "pair": "ALOT/USDC",
            "side": "BUY",
            "amount": 100.0,
            "price": 0.16,
        }
    ],
)

Para market makers que necesitan actualizar constantemente las cotizaciones, esto es un antes y un después.

Swaps Rápidos sin el Libro de Órdenes

No todas las operaciones necesitan la precisión de una orden limitada. El SDK incluye un flujo de swap simple basado en precios request-for-quote (RFQ). Funciona en tres pasos: comprobar el precio indicativo, fijar una cotización firme y ejecutar.

# Paso 1: Soft quote — mira cómo se ve el precio, sin compromiso
soft = await client.get_swap_soft_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Paso 2: Firm quote — bloquea el precio durante 30 segundos
firm = await client.get_swap_firm_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Paso 3: Ejecutar el swap
if firm.success:
    result = await client.execute_rfq_swap(firm.data)

Esto es ideal para aplicaciones que necesitan una interfaz directa de "convertir A a B" sin gestionar la colocación de órdenes y los fills.

Comprobar saldos y mover fondos

El SDK te ofrece visibilidad total de tus saldos en tu portafolio de Dexalot y en las carteras de la cadena conectada:

# Todos los saldos del portafolio
result = await client.get_all_portfolio_balances()
if result.success:
    for token, balance in result.data.items():
        print(token, "Total:", balance["total"], "Disponible:", balance["available"])

# Un solo token
result = await client.get_portfolio_balance(token="USDC")

Para mover fondos dentro o fuera:

# Depositar desde una cadena conectada
await client.deposit(token="USDC", amount=100.0, source_chain="Avalanche")

# Retirar de vuelta a una cadena
await client.withdraw(token="USDC", amount=50.0, target_chain="Avalanche")

Ajustar la caché para tu caso de uso

El SDK almacena en caché las respuestas de la API en cuatro niveles, cada uno adaptado a la rapidez con la que realmente cambian esos datos:

• Datos estáticos (entornos, cadenas): en caché 1 hora
• Datos semi-estáticos (tokens, pares de trading): en caché 15 minutos
• Saldos: en caché 10 segundos
• Libro de órdenes: en caché 1 segundo

Estos valores predeterminados funcionan bien para la mayoría de las aplicaciones. Pero si estás construyendo un bot de alta frecuencia, es posible que quieras una frescura del libro de órdenes de menos de un segundo — configura cache_ttl_orderbook=0.5 para un vencimiento de 500 milisegundos.

client = DexalotClient(
    cache_ttl_orderbook=0.5,   # 500 milisegundos
    cache_ttl_balance=1,       # 1 segundo
)

¿Construyendo un panel que no necesita datos en tiempo real? Sube los TTL y reduce tu huella de API de forma drástica. Para desarrollo, puedes desactivar la caché por completo con enable_cache=False.

Datos de mercado en vivo con WebSocket

Para actualizaciones en tiempo real del libro de órdenes, habilita el gestor de WebSocket configurando ws_manager_enabled=True en tu configuración, y luego suscríbete a eventos con client.subscribe_to_events(). Pasa una cadena de tema como "OrderBook/ALOT/USDC" y una función de callback asíncrona que reciba cada evento como un diccionario.

async def on_orderbook_update(event):
    print("Update:", event)

config = DexalotConfig(ws_manager_enabled=True)

async with DexalotClient(config=config, signer=signer) as client:
    await client.initialize_client()
    await client.subscribe_to_events(
        topic="OrderBook/ALOT/USDC",
        callback=on_orderbook_update,
    )
    await asyncio.sleep(60)  # listen for a minute

La conexión WebSocket gestiona la reconexión automáticamente. Tu callback es una función async que se ejecuta en el event loop, así que puede interactuar con el resto de tu lógica de trading de forma natural.

Configuración de un Vistazo

Todo se puede configurar mediante argumentos del constructor, variables de entorno o un archivo .env. Los argumentos del constructor siempre tienen prioridad. Estas son las opciones que se ajustan con más frecuencia:

Funciones de Resiliencia que Obtienes Gratis

Unas pocas cosas que el SDK gestiona automáticamente y que vale la pena conocer:

Reintento con backoff. Si una llamada a la API o una solicitud RPC falla debido a un error transitorio, el SDK reintenta con backoff exponencial. Los valores predeterminados son razonables (algunos reintentos con retrasos crecientes), pero puedes ajustarlos para que se adapten a tu tolerancia. Esto significa que tu bot no se cae por una sola conexión perdida.

Conmutación por error RPC. Puedes configurar varias URLs de proveedores RPC por cadena. Si una empieza a fallar de manera constante, el SDK cambia automáticamente a la siguiente. Los proveedores fallidos entran en un periodo de enfriamiento antes de reintentarse. Si todo se cae, vuelve al último proveedor que funcionó.

Limitación de tasa. El SDK impone límites de tasa tanto en llamadas a la API como en solicitudes RPC usando un algoritmo de cubeta de tokens. Los valores predeterminados (5 solicitudes de API por segundo, 10 llamadas RPC por segundo) te mantienen dentro de los límites típicos del lado del servidor. Si ejecutas varias instancias de cliente, ten en cuenta que cada una tiene su propio limitador — no comparten una cuota global.

Saneamiento de errores. Cuando algo sale mal, los mensajes de error que ves en result.error se limpian — sin rutas de archivo, sin URLs RPC, sin stack traces que se filtren. En producción, esto evita la exposición accidental de detalles de infraestructura. Para depurar, configura log_level en DEBUG para ver el contexto completo en tus logs.

Hacia Dónde Ir Desde Aquí

Esta guía cubre lo esencial, pero el SDK tiene más profundidad de la que podríamos incluir aquí. Para tener la imagen completa:

• Guía del Usuario — cubre cada método con ejemplos completos
• Resumen de la Arquitectura — explica el diseño interno para colaboradores
• Guía de Caché — ajustes detallados de TTL para diferentes perfiles de aplicación
• Referencia de API — documentación generada automáticamente desde el código fuente

El SDK es de código abierto. Si encuentras un error, quieres una función o tienes una pregunta, el repositorio es el lugar al que acudir.

Empieza en testnet, familiarízate con la API y, cuando tu estrategia esté lista — cambia a mainnet modificando una sola variable de entorno.

Python SDK | GitHub: github.com/Dexalot/dexalot-sdk-python ⧉

Python SDK | PyPi: pypi.org/project/dexalot-sdk ⧉

¡Feliz desarrollo!