Erste Schritte mit dem Dexalot Python SDK

Dieser Leitfaden führt dich durch die Installation des Dexalot Python SDK, die Verbindung mit der Börse und das Ausführen deiner ersten Trades. Am Ende weißt du, wie man Orderbücher liest, Orders platziert und storniert, Swaps ausführt und deine Guthaben überprüft — alles direkt aus Python.

Wir halten es praxisnah. Jedes Beispiel hier ist etwas, das du sofort ausführen kannst.

Installation

Du brauchst Python 3.12 oder höher. Du kannst es für deine Plattform von python.org herunterladen und installieren. Nachdem die Python-Umgebung eingerichtet ist, installierst du das Dexalot Python SDK über PyPi.

pip install dexalot-sdk

Oder, wenn du uv verwendest (das wir für die schnellere Verwaltung von Abhängigkeiten empfehlen):

uv add dexalot-sdk

Als Nächstes erstelle eine .env-Datei im Root-Verzeichnis deines Projekts mit der Umgebung, mit der du dich verbinden willst:

PARENTENV=fuji-multi

Das ist fuji-multi für das Testnet oder production-multi, wenn du bereit für Mainnet bist. Für schreibgeschützte Operationen wie das Abrufen von Orderbüchern und Token-Listen brauchst du das alles. Wir fügen gleich Signing-Zugangsdaten hinzu. Du kannst die Datei env.example durchsuchen, um eine vollständige Liste der Variablen zu sehen, die du verwenden kannst.

Deine erste Verbindung

Das SDK ist asynchron-first, daher laufen alle Operationen innerhalb eines asynchronen Kontexts. Hier ist die einfachste mögliche Verbindung — lies die verfügbaren Trading-Paare aus und gib die ersten paar aus:

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())

Ein paar Dinge, die du beachten solltest. Der async with-Block übernimmt automatisch das Öffnen und Schließen der HTTP-Session. Der Aufruf initialize_client() lädt die Konfiguration der Börse — Token-Metadaten, Contract-Adressen, Chain-Details — sodass der Client weiß, wie er mit dem Protokoll spricht. Und das Ergebnis kommt als Result-Objekt zurück: Prüfe .success, bevor du auf .data zugreifst, und lies .error, falls etwas schiefgelaufen ist.

Dieses Muster — Ergebnis prüfen, dann entsprechend handeln — ist in jeder SDK-Methode identisch. Keine versteckten Exceptions für erwartete Fehler.

Das Orderbuch lesen

Sobald du verbunden bist, ist das Abrufen des Orderbuchs für ein Trading-Paar nur eine Zeile:

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

Orderbuchdaten werden standardmäßig für eine Sekunde gecached. Das bedeutet, dass schnelle aufeinanderfolgende Aufrufe nicht die API mit Anfragen überladen. Wenn du für Strategien mit hoher Frequenz aktuellere Daten brauchst, kannst du den Cache-TTL senken oder ihn ganz deaktivieren (mehr dazu unten).

Einrichten eines Signers für Trading

Schreibgeschützter Zugriff ist nützlich, aber um Orders zu platzieren, Swaps auszuführen oder Gelder zu verschieben, brauchst du eine signierende Wallet. Der empfohlene Ansatz ist, direkt ein Signer-Objekt zu übergeben, sodass dein privater Rohschlüssel niemals in einer Konfigurationsdatei landet:

from eth_account import Account

signer = Account.from_key("0xYOUR_PRIVATE_KEY")

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

Para configuraciones de producción, el SDK también incluye un llavero de secretos cifrado. Almacena tus claves en un archivo cifrado en el disco — solo los nombres de las claves son visibles; los valores están cifrados en reposo. Generas una clave de cifrado una vez, la guardas en tu gestor de contraseñas y la usas para desbloquear el llavero 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 solicite. Esto mantiene tu clave en bruto completamente fuera de .env y del control de versiones.

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

Colocar tu primer pedido

Con un firmante conectado, colocar una orden de compra limitada 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 para humanos al formato atómico en cadena, gestiona el nonce de la transacción para que no obtengas errores por nonce duplicado, estima el gas, firma la transacción y la envía. Recibes un hash de transacción y un ID de pedido del cliente que puedes usar más tarde para cancelar o reemplazar la orden.

¿Quieres cancelarla?

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

¿Necesitas cancelarlo todo?

result = await client.cancel_all_orders()

Operaciones por lotes: múltiples pedidos en un solo movimiento

Si estás gestionando varias 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 nuevos en la misma transacción — sin una brecha en la que estés sin cobertura:

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 cambio de juego.

Intercambios rápidos sin el libro de órdenes

Nicht jeder Trade braucht die Präzision eines Limit Orders. Das SDK enthält einen einfachen Swap-Flow auf Basis von Request-for-Quote (RFQ)-Preisen. Er funktioniert in drei Schritten: den Richtpreis prüfen, eine verbindliche Quote sichern und ausführen.

# Schritt 1: Soft Quote — sieh dir an, wie der Preis aussieht, ohne Verpflichtung
soft = await client.get_swap_soft_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Schritt 2: Firm Quote — sperrt den Preis für 30 Sekunden
firm = await client.get_swap_firm_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Schritt 3: Swap ausführen
if firm.success:
    result = await client.execute_rfq_swap(firm.data)

Das ist ideal für Anwendungen, die eine unkomplizierte "A in B umwandeln"-Schnittstelle benötigen, ohne Order-Placement und Fills verwalten zu müssen.

Kontostände prüfen und Gelder verschieben

Das SDK gibt dir volle Transparenz über deine Guthaben über dein Dexalot-Portfolio hinweg und über verbundene Chain-Wallets:

# Alle Portfolio-Guthaben
result = await client.get_all_portfolio_balances()
if result.success:
    for token, balance in result.data.items():
        print(token, "Total:", balance["total"], "Verfügbar:", balance["available"])

# Einzel-Token
result = await client.get_portfolio_balance(token="USDC")

So bewegst du Gelder hinein oder hinaus:

# Einzahlung von einer verbundenen Chain
await client.deposit(token="USDC", amount=100.0, source_chain="Avalanche")

# Rückzahlung auf eine Chain
await client.withdraw(token="USDC", amount=50.0, target_chain="Avalanche")

Den Cache für deinen Use Case anpassen

Das SDK cached API-Antworten auf vier Ebenen, wobei jede Ebene dazu passt, wie schnell sich diese Daten tatsächlich ändern:

• Statische Daten (Umgebungen, Chains): cached 1 Stunde
• Semi-statische Daten (Tokens, Trading Pairs): cached 15 Minuten
• Guthaben: cached 10 Sekunden
• Order Book: cached 1 Sekunde

Diese Standardwerte funktionieren gut für die meisten Anwendungen. Aber wenn du einen High-Frequency-Bot baust, möchtest du vielleicht eine Frische des Order Books unter einer Sekunde — setze cache_ttl_orderbook=0.5 für ein Ablaufintervall von 500 Millisekunden.

client = DexalotClient(
    cache_ttl_orderbook=0.5,   # 500 Millisekunden
    cache_ttl_balance=1,       # 1 Sekunde
)

Bau dir ein Dashboard, das keine Echtzeitdaten benötigt? Dreh die TTLs hoch und reduziere deinen API-Footprint drastisch. Für die Entwicklung kannst du Caching komplett deaktivieren mit enable_cache=False.

Live-Marktdaten mit WebSocket

Für Echtzeit-Updates des Order Books aktiviere den WebSocket-Manager, indem du ws_manager_enabled=True in deiner Konfiguration setzt, und abonniere dann Events mit client.subscribe_to_events(). Übergib eine Topic-String wie "OrderBook/ALOT/USDC" sowie eine asynchrone Callback-Funktion, die jedes Event als Dictionary erhält.

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

Die WebSocket-Verbindung übernimmt das automatische Reconnect. Dein Callback ist eine asynchrone Funktion, die in der Event-Loop läuft, sodass sie sich auf natürliche Weise mit dem Rest deiner Trading-Logik verbinden kann.

Konfiguration auf einen Blick

Alles ist über Konstruktor-Argumente, Umgebungsvariablen oder eine .env-Datei konfigurierbar. Konstruktor-Argumente haben immer Vorrang. Hier sind die am häufigsten angepassten Optionen:

Resilienzfunktionen, die du kostenlos bekommst

Ein paar Dinge, die das SDK automatisch übernimmt und die du kennen solltest:

Retry mit Backoff. Wenn ein API-Call oder ein RPC-Request aufgrund eines vorübergehenden Fehlers fehlschlägt, versucht das SDK erneut mit exponentiellem Backoff. Die Standardwerte sind sinnvoll (ein paar Retries mit zunehmenden Verzögerungen), aber du kannst sie an deine Toleranz anpassen. Das bedeutet: Dein Bot crasht nicht wegen einer einzelnen abgebrochenen Verbindung.

RPC-Failover. Du kannst mehrere RPC-Provider-URLs pro Chain konfigurieren. Wenn einer konsistent zu scheitern beginnt, wechselt das SDK automatisch zum nächsten. Fehlgeschlagene Provider gehen in eine Cooldown-Phase, bevor sie erneut versucht werden. Wenn alles ausfällt, greift es auf den zuletzt funktionierenden Provider zurück.

Rate Limiting. Das SDK erzwingt Rate Limits sowohl für API-Calls als auch für RPC-Requests mithilfe eines Token-Bucket-Algorithmus. Die Defaults (5 API-Requests pro Sekunde, 10 RPC-Calls pro Sekunde) halten dich innerhalb typischer serverseitiger Limits. Wenn du mehrere Client-Instanzen betreibst, denke daran, dass jede Instanz ihren eigenen Limiter hat — sie teilen sich kein globales Kontingent.

Error-Sanitization. Wenn etwas schiefgeht, werden die Fehlermeldungen, die du in result.error siehst, aufgeräumt — keine Dateipfade, keine RPC-URLs, keine Stacktraces, die durchrutschen. In der Produktion verhindert das, dass versehentlich Infrastrukturdetails offengelegt werden. Für Debugging setze log_level auf DEBUG, um den vollständigen Kontext in deinen Logs zu sehen.

Wohin du als Nächstes gehen solltest

Dieser Leitfaden behandelt das Wesentliche, aber das SDK bietet mehr Tiefe, als wir hier abdecken können. Für das vollständige Bild:

• User Guide — deckt jede Methode mit vollständigen Beispielen ab
• Architecture Overview — erklärt das interne Design für Contributors
• Caching Guide — detailliertes TTL-Tuning für unterschiedliche Anwendungsprofile
• API Reference — automatisch generierte Doks aus dem Quellcode

Das SDK ist Open Source. Wenn du einen Fehler findest, eine Funktion vorschlagen möchtest oder eine Frage hast, ist das Repository der richtige Ort.

Starte im Testnet, mache dich mit der API vertraut und wenn deine Strategie bereit ist — wechsle ins Mainnet, indem du eine Umgebungsvariable änderst.

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

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

Viel Spaß beim Bauen.