Bien démarrer avec le SDK Python Dexalot

Ce guide vous accompagne dans l'installation du SDK Python de Dexalot, la connexion à l'exchange et l'exécution de vos premiers trades. À la fin, vous saurez lire les carnets d'ordres, passer et annuler des ordres, exécuter des swaps et vérifier vos soldes — le tout depuis Python.

Nous garderons les choses concrètes. Chaque exemple ici est quelque chose que vous pouvez exécuter immédiatement.

Installation

Vous avez besoin de Python 3.12 ou supérieur. Vous pouvez le télécharger et l'installer pour votre plateforme depuis python.org. Après la configuration de l'environnement python, installez le Dexalot Python SDK depuis PyPi.

pip install dexalot-sdk

Ou, si vous utilisez uv (que nous recommandons pour une gestion plus rapide des dépendances) :

uv add dexalot-sdk

Ensuite, créez un fichier .env à la racine de votre projet avec l'environnement auquel vous souhaitez vous connecter :

PARENTENV=fuji-multi

C'est fuji-multi pour le testnet, ou production-multi quand vous serez prêt pour le mainnet. Pour les opérations en lecture seule comme la récupération des carnets d'ordres et des listes de tokens, ceci suffit. Nous ajouterons bientôt les identifiants de signature. Vous pouvez explorer le fichier env.example pour obtenir la liste complète des variables que vous pouvez utiliser.

Votre première connexion

Le SDK est d'abord asynchrone : toutes les opérations s'exécutent dans un contexte async. Voici la connexion la plus simple possible — lire les paires de trading disponibles et afficher les premières :

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

Quelques points à noter. Le bloc async with gère l'ouverture et la fermeture de la session HTTP automatiquement pour vous. L'appel initialize_client() charge la configuration de l'exchange — métadonnées des tokens, adresses des contrats, détails de la chaîne — afin que le client sache comment parler au protocole. Et le résultat est renvoyé sous forme d'objet Result : vérifiez .success avant d'accéder à .data, et lisez .error si quelque chose s'est mal passé.

Ce modèle — vérifier le résultat, puis agir en conséquence — est identique pour chaque méthode du SDK. Aucune exception masquée pour les échecs attendus.

Lire le carnet d'ordres

Une fois connecté, récupérer le carnet d'ordres d'une paire de trading ne prend qu'une ligne :

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

Par défaut, les données du carnet d'ordres sont mises en cache pendant une seconde. Cela signifie que des appels successifs rapides ne viendront pas saturer l'API. Si vous avez besoin de données plus fraîches pour des stratégies à haute fréquence, vous pouvez réduire le TTL du cache ou le désactiver entièrement (plus d'informations ci-dessous).

Configurer un signateur pour le trading

L'accès en lecture seule est utile, mais pour passer des ordres, exécuter des swaps ou déplacer des fonds, vous avez besoin d'un portefeuille de signature. L'approche recommandée consiste à passer directement un objet signateur, afin que votre clé privée brute ne se retrouve jamais dans un fichier de configuration :

from eth_account import Account

signer = Account.from_key("0xYOUR_PRIVATE_KEY")

async with DexalotClient(signer=signer) as client:
    await client.initialize_client()
    # Maintenant, vous pouvez trader

Pour les configurations en production, le SDK inclut également un coffre-fort chiffré pour les secrets. Il stocke vos clés dans un fichier chiffré sur le disque — seuls les noms des clés sont visibles, les valeurs sont chiffrées au repos. Vous générez une clé de chiffrement une seule fois, vous la stockez dans votre gestionnaire de mots de passe, puis vous l’utilisez pour déverrouiller le coffre-fort au moment de l’exécution :

secrets-vault keygen          # génère votre clé de chiffrement, enregistrez-la en lieu sûr
secrets-vault add PRIVATE_KEY 0xabc123...

Ensuite, au moment de l’exécution, définissez DEXALOT_SECRETS_VAULT_KEY comme variable d’environnement ou laissez le SDK vous la demander. Cela permet de garder votre clé brute entièrement hors de .env et du contrôle de source.

Important : Ne commitez jamais de clés privées ni des clés de chiffrement du coffre-fort dans le contrôle de version. Utilisez un gestionnaire de mots de passe ou un gestionnaire de secrets comme AWS Secrets Manager ou HashiCorp Vault pour la production.

Passer votre première commande

Une fois un signataire connecté, passer un ordre d’achat limite ressemble à ceci :

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("Échec :", result.error)

Le SDK s’occupe de tout en coulisses : conversion de vos montants lisibles par l’humain au format atomique sur la chaîne, gestion du nonce de transaction pour éviter les erreurs de nonce dupliqué, estimation du gas, signature de la transaction et soumission. Vous récupérez un hash de transaction ainsi qu’un client order ID que vous pourrez utiliser plus tard pour annuler ou remplacer l’ordre.

Vous voulez l’annuler ?

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

Vous devez tout annuler ?

result = await client.cancel_all_orders()

Opérations par lots : plusieurs ordres en une seule fois

Si vous gérez plusieurs positions, le SDK prend en charge des opérations par lots qui regroupent plusieurs ordres dans une seule transaction on-chain. Cela permet d’économiser du gas et de réduire la latence :

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)

Il existe aussi une opération atomique d’annulation et de remplacement. Elle supprime vos ordres existants et en place de nouveaux dans la même transaction — sans aucun intervalle pendant lequel vous seriez non couverts :

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

Pour les market makers qui doivent mettre à jour les cotations en permanence, c’est un véritable changement de jeu.

Swaps rapides sans carnet d’ordres

Tous les trades n’ont pas besoin de la précision d’un ordre limite. Le SDK inclut un flux de swap simple basé sur la tarification request-for-quote (RFQ). Il fonctionne en trois étapes : vérifier le prix indicatif, verrouiller une cotation ferme et exécuter.

# Étape 1 : Soft quote — voyez à quoi ressemble le prix, sans engagement
soft = await client.get_swap_soft_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Étape 2 : Firm quote — verrouille le prix pendant 30 secondes
firm = await client.get_swap_firm_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Étape 3 : Exécuter le swap
if firm.success:
    result = await client.execute_rfq_swap(firm.data)

C’est idéal pour les applications qui ont besoin d’une interface simple "convertir A en B" sans gérer la passation d’ordres et les exécutions.

Vérifier les soldes et déplacer des fonds

Le SDK vous donne une visibilité complète sur vos soldes à travers votre portefeuille Dexalot et les portefeuilles de chaîne connectés :

# Tous les soldes du portefeuille
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 seul token
result = await client.get_portfolio_balance(token="USDC")

Pour déplacer des fonds, dans ou hors :

# Dépôt depuis une chaîne connectée
await client.deposit(token="USDC", amount=100.0, source_chain="Avalanche")

# Retrait vers une chaîne
await client.withdraw(token="USDC", amount=50.0, target_chain="Avalanche")

Ajuster le cache pour votre cas d’utilisation

Le SDK met en cache les réponses d’API à quatre niveaux, chacun correspondant à la rapidité à laquelle ces données changent réellement :

• Données statiques (environnements, chaînes) : mises en cache 1 heure
• Données semi-statiques (tokens, paires de trading) : mises en cache 15 minutes
• Soldes : mises en cache 10 secondes
• Carnet d’ordres : mis en cache 1 seconde

Ces valeurs par défaut fonctionnent bien pour la plupart des applications. Mais si vous construisez un bot à haute fréquence, vous voudrez peut-être une fraîcheur du carnet d’ordres inférieure à la seconde — définissez cache_ttl_orderbook=0.5 pour une expiration de 500 millisecondes.

client = DexalotClient(
    cache_ttl_orderbook=0.5,   # 500 millisecondes
    cache_ttl_balance=1,       # 1 seconde
)

Vous construisez un tableau de bord qui n’a pas besoin de données en temps réel ? Augmentez les TTL et réduisez drastiquement votre empreinte API. Pour le développement, vous pouvez désactiver complètement le cache avec enable_cache=False.

Données de marché en direct avec WebSocket

Pour les mises à jour temps réel du carnet d’ordres, activez le gestionnaire WebSocket en définissant ws_manager_enabled=True dans votre configuration, puis abonnez-vous aux événements avec client.subscribe_to_events(). Passez une chaîne de topic comme "OrderBook/ALOT/USDC" et une fonction de rappel asynchrone qui reçoit chaque événement sous forme de dictionnaire.

async def on_orderbook_update(event):
    print("Mise à jour:", 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)  # écouter pendant une minute

La connexion WebSocket gère automatiquement la reconnexion. Votre callback est une fonction asynchrone qui s'exécute sur la boucle d'événements, de sorte qu'elle peut interagir naturellement avec le reste de votre logique de trading.

Configuration en un coup d'œil

Tout est configurable via les arguments du constructeur, des variables d'environnement ou un fichier .env. Les arguments du constructeur ont toujours la priorité. Voici les options les plus souvent ajustées :

Fonctionnalités de résilience incluses (gratuitement)

Quelques points que le SDK gère automatiquement et qu'il vaut la peine de connaître :

Retry avec backoff. Si un appel API ou une requête RPC échoue à cause d'une erreur transitoire, le SDK réessaie avec un backoff exponentiel. Les valeurs par défaut sont judicieuses (quelques retries avec des délais croissants), mais vous pouvez les ajuster selon votre tolérance. Cela signifie que votre bot ne plante pas à cause d'une simple connexion interrompue.

Basculement RPC. Vous pouvez configurer plusieurs URL de fournisseurs RPC par chaîne. Si l'un commence à échouer de façon constante, le SDK bascule automatiquement vers le suivant. Les fournisseurs en échec passent par une période de refroidissement avant d'être retentés. Si tout s'arrête, il revient au dernier fournisseur qui a fonctionné.

Limitation de débit. Le SDK applique des limites de débit à la fois sur les appels API et les requêtes RPC à l'aide d'un algorithme de type token-bucket. Les valeurs par défaut (5 requêtes API par seconde, 10 appels RPC par seconde) vous maintiennent dans les limites typiques côté serveur. Si vous exécutez plusieurs instances de client, gardez à l'esprit que chacune a son propre limiteur — elles ne partagent pas un quota global.

Assainissement des erreurs. Quand quelque chose se passe mal, les messages d'erreur que vous voyez dans result.error sont nettoyés — pas de chemins de fichiers, pas d'URL RPC, pas de stack traces qui fuient. En production, cela évite l'exposition accidentelle de détails d'infrastructure. Pour le débogage, définissez log_level sur DEBUG pour voir tout le contexte dans vos logs.

Et ensuite ?

Ce guide couvre l'essentiel, mais le SDK est plus approfondi que ce que nous pouvons inclure ici. Pour avoir le tableau complet :

• Guide Utilisateur — couvre chaque méthode avec des exemples complets
• Vue d'ensemble de l'architecture — explique la conception interne pour les contributeurs
• Guide de mise en cache — ajustements détaillés du TTL pour différents profils d'application
• Référence API — documentation générée automatiquement à partir du code source

Le SDK est open source. Si vous trouvez un bug, souhaitez une fonctionnalité ou avez une question, le dépôt est l’endroit idéal.

Démarrez sur le testnet, familiarisez-vous avec l’API, et lorsque votre stratégie est prête — basculez sur le mainnet en modifiant une seule variable d’environnement.

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

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

Bon développement.