使用 Dexalot Python SDK 入门指南

本指南将带你完成 Dexalot Python SDK 的安装、连接交易所，并运行你的第一笔交易。到最后，你将知道如何读取订单簿、下单与撤单、执行兑换，以及查看余额 — 全都只需用 Python。

我们会保持内容尽量实用。这里的每个示例都能让你立刻运行。

安装

你需要 Python 3.12 或更高版本。你可以从 python.org 下载并为你的平台安装。完成 Python 环境设置后，请从 PyPi 安装 Dexalot Python SDK。

pip install dexalot-sdk

或者如果你在使用 uv（我们推荐它用于更快速的依赖管理）：

uv add dexalot-sdk

接下来，在你的项目根目录创建一个 .env 文件，并填写你想连接的环境：

PARENTENV=fuji-multi

其中，fuji-multi 用于测试网（testnet），当你准备好上线主网（mainnet）时使用 production-multi。对于诸如获取订单簿和代币列表这类只读操作，这些就够了。我们很快会添加签名凭据。你可以查看 env.example 文件，了解所有可用变量的完整列表。

你的首次连接

SDK 以异步优先（async-first）构建，因此所有操作都在异步上下文中运行。下面是最简单的连接方式 — 读取可用交易对并打印前几个：

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

有几点需要注意。async with 代码块会自动替你处理 HTTP 会话的打开与关闭。initialize_client() 会加载交易所的配置 — 包括代币元数据、合约地址、链路详情 — 这样客户端才能知道如何与协议通信。并且返回结果会以 Result 对象形式呈现：访问 .data 之前先检查 .success，如果出现问题则读取 .error。

这种模式 — 先检查结果，再基于结果采取行动 — 在每一个 SDK 方法中都保持一致。对于预期的失败情况，不会有隐藏异常。

读取订单簿

一旦连接成功，获取某个交易对的订单簿只需要一行代码：

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

默认情况下，订单簿数据会缓存一秒；这意味着你进行快速的连续调用不会持续轰炸 API。如果你需要为高频策略获取更新更及时的数据，可以降低缓存 TTL 或直接禁用缓存（更多内容见下文）。

为交易配置签名者（Signer）

只读访问很有用，但要下单、执行兑换或转移资金，你需要一个签名钱包。推荐的做法是直接传入 signer 对象，这样你的原始私钥永远不会出现在配置文件中：

from eth_account import Account

signer = Account.from_key("0xYOUR_PRIVATE_KEY")

async with DexalotClient(signer=signer) as client:
    await client.initialize_client()
    # 现在你可以进行交易

在生产环境中，SDK 还提供了一个加密的密钥保险库（secrets vault）。它会将你的密钥以加密文件的形式存储在磁盘上 — 只有密钥名称是可见的，密钥值在静态时会被加密。你只需要生成一次加密密钥，把它存到密码管理器中，然后在运行时使用它来解锁保险库：

secrets-vault keygen          # 生成你的加密密钥，安全保存
secrets-vault add PRIVATE_KEY 0xabc123...

然后在运行时，将 DEXALOT_SECRETS_VAULT_KEY 设置为环境变量，或者让 SDK 提示你输入。这样可以确保你的原始密钥完全不进入 .env 文件以及代码托管（源代码控制）。

重要：切勿将私钥或保险库加密密钥提交到版本控制中。生产环境请使用密码管理器或密钥管理器，例如 AWS Secrets Manager 或 HashiCorp Vault。

下你的第一笔订单

连接上 signer 后，下一个限价买入订单如下所示：

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)

SDK 会在幕后处理所有事情：把你可读的人类数量转换为链上原子格式，管理交易的 nonce 以避免出现重复 nonce 错误，估算 gas，对交易进行签名，然后提交。你会得到一个交易哈希（transaction hash）以及一个客户端订单 ID（client order ID），之后你可以用它来取消或替换订单。

想要取消它？

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

需要取消所有订单？

result = await client.cancel_all_orders()

批量操作：一口气下多笔订单

如果你在管理多个仓位，SDK 支持批量操作：把多笔订单打包到同一笔链上交易中。这能节省 gas，并降低延迟：

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)

还支持原子“取消并替换”（cancel-and-replace）操作。它会移除你现有的订单，并在同一笔交易中下入新的订单 — 不会出现你未对冲（unhedged）的空窗期：

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

对于需要不断更新报价的做市商来说，这简直是游戏规则的改变者。

无需订单簿的快速兑换（Quick Swaps）

并不是每一笔交易都需要限价单那样的精确程度。SDK 提供了一种基于请求报价（RFQ）定价的简单兑换流程。它分为三步：先查看指示性价格，再锁定一个确定报价，最后执行交易。

# Step 1: Soft quote — see what the price looks like, no commitment
soft = await client.get_swap_soft_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Step 2: Firm quote — locks in the price for 30 seconds
firm = await client.get_swap_firm_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Step 3: Execute the swap
if firm.success:
    result = await client.execute_rfq_swap(firm.data)

这非常适合那些需要直接的 "将 A 转换为 B" 界面的应用，而无需管理下单和成交过程。

检查余额并移动资金

SDK 可让你完整查看 Dexalot 组合中的各类余额，以及已连接的链上钱包：

# All portfolio balances
result = await client.get_all_portfolio_balances()
if result.success:
    for token, balance in result.data.items():
        print(token, "Total:", balance["total"], "Available:", balance["available"])

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

用于划入或划出资金：

# Deposit from a connected chain
await client.deposit(token="USDC", amount=100.0, source_chain="Avalanche")

# Withdraw back to a chain
await client.withdraw(token="USDC", amount=50.0, target_chain="Avalanche")

为你的使用场景调整缓存

SDK 会在四个层级对 API 响应进行缓存，每一层都对应该数据实际变化的速度：

• 静态数据（环境、链）：缓存 1 小时
• 半静态数据（代币、交易对）：缓存 15 分钟
• 余额：缓存 10 秒
• 订单簿：缓存 1 秒

这些默认值适用于大多数应用。但如果你正在构建高频机器人，你可能会希望订单簿的新鲜度达到亚秒级——将 cache_ttl_orderbook=0.5 设置为 500 毫秒的过期时间。

client = DexalotClient(
    cache_ttl_orderbook=0.5,   # 500 milliseconds
    cache_ttl_balance=1,       # 1 second
)

在构建不需要实时数据的仪表盘？把 TTL 调高，并大幅减少你的 API 占用。用于开发时，你可以通过 enable_cache=False 完全禁用缓存。

使用 WebSocket 获取实时市场数据

要获取实时订单簿更新，请通过在配置中设置 ws_manager_enabled=True 来启用 WebSocket 管理器，然后使用 client.subscribe_to_events() 订阅事件。传入类似 "OrderBook/ALOT/USDC" 的主题字符串，并提供一个异步回调函数，用于接收每个事件（以字典形式）。

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)  # 监听一分钟

WebSocket 连接会自动处理重连。你的回调是一个异步函数，会在事件循环（event loop）上运行，因此它能够与其余的交易逻辑自然地交互。

一览配置

所有内容都可以通过构造函数参数、环境变量，或 .env 文件进行配置。构造函数参数始终优先。以下是最常被调整的选项：

你免费获得的韧性功能

SDK 会自动处理一些值得你了解的事情：

带退避（backoff）的重试。 如果由于瞬时错误（transient error）导致 API 调用或 RPC 请求失败，SDK 会使用指数退避（exponential backoff）进行重试。默认值是合理的（少量重试并逐步增加延迟），但你可以根据容忍度进行调整。这意味着你的机器人不会因为一次断开连接就崩溃。

RPC 故障转移（failover）。 你可以为每条链配置多个 RPC 提供商 URL。如果其中一个开始持续失败，SDK 会自动切换到下一个。失败的提供商会进入冷却期（cooldown period），之后再进行重试。如果所有都不可用，则会回退到最后一个成功工作的提供商。

限流。 SDK 使用令牌桶（token-bucket）算法对 API 调用和 RPC 请求实施限流。默认值（每秒 5 次 API 请求、每秒 10 次 RPC 调用）可以让你保持在典型的服务器端限制范围内。如果你在运行多个客户端实例，请记住每个实例都有各自的限流器 — 它们不会共享全局配额。

错误清理。 当出现问题时，你在 result.error 中看到的错误信息会被清理掉 — 不包含文件路径、不包含 RPC URL、不泄露堆栈跟踪（stack traces）。在生产环境中，这可以防止意外暴露基础设施细节。用于调试时，将 log_level 设置为 DEBUG，以便在日志中查看完整上下文。

接下来去哪里

本指南涵盖了关键内容，但 SDK 的深度比我们在这里能展示的更多。要看完整内容：

• 用户指南（User Guide） — 为每个方法提供带完整示例的说明
• 架构概览（Architecture Overview） — 为贡献者解释内部设计
• 缓存指南（Caching Guide） — 针对不同应用场景的详细 TTL 调优
• API 参考（API Reference） — 从源代码自动生成的文档

该 SDK 为开源。如果你发现了 bug、想要新增功能，或有任何问题，仓库就是你该去的地方。

先在测试网（testnet）开始，上手使用 API；当你的策略准备就绪 — 通过更改一个环境变量即可切换到主网（mainnet）。

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

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

祝你构建顺利。