Bắt đầu với Dexalot Python SDK

Hướng dẫn này sẽ đưa bạn qua việc cài đặt Dexalot Python SDK, kết nối đến sàn giao dịch và thực hiện các lệnh giao dịch đầu tiên. Đến cuối bài, bạn sẽ biết cách đọc sổ lệnh, đặt và hủy lệnh, thực hiện các giao dịch hoán đổi, và kiểm tra số dư — tất cả đều từ Python.

Chúng tôi sẽ giữ mọi thứ thực tế. Mỗi ví dụ ở đây đều là thứ bạn có thể chạy ngay lập tức.

Cài đặt

Bạn cần Python 3.12 trở lên. Bạn có thể tải xuống và cài đặt cho nền tảng của mình từ python.org. Sau khi thiết lập môi trường python, hãy cài đặt Dexalot Python SDK từ PyPi.

pip install dexalot-sdk

Hoặc nếu bạn đang dùng uv (chúng tôi khuyến nghị để quản lý phụ thuộc nhanh hơn):

uv add dexalot-sdk

Tiếp theo, tạo một tệp .env trong thư mục gốc dự án của bạn với môi trường bạn muốn kết nối:

PARENTENV=fuji-multi

Tức là fuji-multi cho testnet, hoặc production-multi khi bạn sẵn sàng cho mainnet. Với các thao tác chỉ đọc như lấy sổ lệnh và danh sách token, bạn chỉ cần đến đây. Chúng tôi sẽ thêm thông tin chứng thực ký kết trong thời gian ngắn. Bạn có thể xem tệp env.example để biết đầy đủ danh sách các biến bạn có thể dùng.

Kết nối đầu tiên của bạn

SDK được thiết kế theo hướng async-first, nên mọi thao tác đều chạy bên trong một ngữ cảnh async. Đây là cách kết nối đơn giản nhất — đọc các cặp giao dịch có sẵn và in ra vài cặp đầu tiên:

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

Cần lưu ý một vài điểm. Khối async with tự động xử lý việc mở và đóng phiên HTTP cho bạn. Lệnh gọi initialize_client() tải cấu hình của sàn giao dịch — metadata token, địa chỉ contract, chi tiết chain — để client biết cách giao tiếp với giao thức. Và kết quả trả về dưới dạng đối tượng Result: hãy kiểm tra .success trước khi truy cập .data, và đọc .error nếu có điều gì đó xảy ra không như mong đợi.

Mẫu này — kiểm tra kết quả, rồi hành động theo nó — nhất quán trên mọi phương thức của SDK. Không có ngoại lệ ẩn cho các trường hợp thất bại được kỳ vọng.

Đọc sổ lệnh

Khi đã kết nối, việc lấy sổ lệnh cho một cặp giao dịch chỉ cần một dòng:

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

Dữ liệu sổ lệnh được lưu vào cache mặc định trong 1 giây, nghĩa là các lệnh gọi liên tiếp nhanh sẽ không làm “dội” API. Nếu bạn cần dữ liệu mới hơn cho các chiến lược tần suất cao, bạn có thể giảm thời gian sống cache TTL hoặc tắt hoàn toàn (xem thêm bên dưới).

Thiết lập Signer để giao dịch

Truy cập chỉ đọc là hữu ích, nhưng để đặt lệnh, thực hiện giao dịch hoán đổi, hoặc chuyển tiền, bạn cần một ví dùng để ký (signing wallet). Cách tiếp cận được khuyến nghị là truyền trực tiếp một đối tượng signer để khóa private thô của bạn không bao giờ nằm trong một tệp cấu hình:

from eth_account import Account

signer = Account.from_key("0xYOUR_PRIVATE_KEY")

async with DexalotClient(signer=signer) as client:
    await client.initialize_client()
    # Bây giờ bạn có thể giao dịch

Đối với các cấu hình triển khai thực tế, SDK cũng đi kèm một kho bí mật (secrets vault) được mã hóa. Nó lưu các khóa của bạn trong một tệp đã mã hóa trên đĩa — chỉ tên khóa là hiển thị, còn các giá trị được mã hóa khi lưu trữ. Bạn tạo một khóa mã hóa một lần, lưu nó trong trình quản lý mật khẩu của mình, và sử dụng để mở khóa vault khi chạy:

secrets-vault keygen          # tạo khóa mã hóa của bạn, lưu an toàn
secrets-vault add PRIVATE_KEY 0xabc123...

Rồi khi chạy, hãy đặt DEXALOT_SECRETS_VAULT_KEY như một biến môi trường hoặc để SDK nhắc bạn nhập. Cách này giúp giữ khóa thô của bạn hoàn toàn khỏi .env và hệ thống quản lý mã nguồn.

Lưu ý quan trọng: Không bao giờ commit khóa riêng tư hoặc khóa mã hóa vault vào hệ thống quản lý phiên bản. Hãy sử dụng trình quản lý mật khẩu hoặc một secrets manager như AWS Secrets Manager hoặc HashiCorp Vault cho môi trường triển khai thực tế.

Đặt Lệnh Đầu Tiên Của Bạn

Khi đã kết nối signer, việc đặt một lệnh mua giới hạn (limit buy) sẽ trông như sau:

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 sẽ lo tất cả mọi thứ ở hậu trường: chuyển đổi các số tiền bạn nhập theo cách dễ hiểu sang định dạng nguyên tử trên chuỗi, quản lý nonce giao dịch để bạn không gặp lỗi nonce trùng lặp, ước tính gas, ký giao dịch và gửi đi. Bạn nhận lại một mã băm giao dịch (transaction hash) và một client order ID mà bạn có thể dùng sau này để hủy hoặc thay thế lệnh.

Muốn hủy nó?

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

Cần hủy tất cả?

result = await client.cancel_all_orders()

Thao Tác Theo Lô: Nhiều Lệnh Trong Một Lần

Nếu bạn đang quản lý nhiều vị thế, SDK hỗ trợ các thao tác theo lô (batch operations) để gộp nhiều lệnh vào một giao dịch on-chain duy nhất. Điều này giúp tiết kiệm gas và giảm độ trễ:

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)

Cũng có một thao tác hủy và thay thế theo kiểu nguyên tử (atomic cancel-and-replace). Nó xóa các lệnh hiện có của bạn và đặt các lệnh mới trong cùng một giao dịch — không có khoảng trống khiến bạn bị unhedged:

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

Dành cho market maker cần liên tục cập nhật báo giá, đây là một bước ngoặt.

Quick Swaps Không Cần Order Book

Không phải giao dịch nào cũng cần độ chính xác của lệnh giới hạn. SDK bao gồm một luồng swap đơn giản dựa trên định giá request-for-quote (RFQ). Luồng này hoạt động trong ba bước: kiểm tra giá tham chiếu, khóa một báo giá chắc chắn, và thực thi.

# Step 1: Soft quote — xem giá trông như thế nào, không cam kết
soft = await client.get_swap_soft_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Step 2: Firm quote — khóa giá trong 30 giây
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)

Cách này phù hợp lý tưởng cho các ứng dụng cần một giao diện "chuyển đổi A sang B" đơn giản mà không phải quản lý việc đặt lệnh và khớp lệnh.

Kiểm tra Số dư và Di chuyển Quỹ

SDK cung cấp cho bạn toàn bộ khả năng hiển thị đối với số dư của bạn trên danh mục Dexalot và các ví chuỗi được kết nối:

# 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")

Để chuyển quỹ vào hoặc ra:

# 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")

Tinh chỉnh Bộ nhớ đệm cho Tình huống sử dụng của bạn

SDK cache phản hồi API ở bốn mức, mỗi mức tương ứng với tốc độ thay đổi thực tế của dữ liệu đó:

• Dữ liệu tĩnh (môi trường, chuỗi): cache 1 giờ
• Dữ liệu bán tĩnh (token, cặp giao dịch): cache 15 phút
• Số dư: cache 10 giây
• Sổ lệnh: cache 1 giây

Những giá trị mặc định này hoạt động tốt cho hầu hết các ứng dụng. Nhưng nếu bạn đang xây dựng một bot tần suất cao, bạn có thể muốn độ tươi của sổ lệnh dưới một giây — đặt cache_ttl_orderbook=0.5 cho thời hạn hết hạn 500-millisecond.

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

Đang xây dựng một dashboard không cần dữ liệu thời gian thực? Tăng TTL lên và giảm đáng kể footprint API của bạn. Để phát triển, bạn có thể tắt caching hoàn toàn với enable_cache=False.

Dữ liệu Thị trường Trực tiếp với WebSocket

Để cập nhật sổ lệnh theo thời gian thực, hãy bật trình quản lý WebSocket bằng cách đặt ws_manager_enabled=True trong cấu hình của bạn, sau đó subscribe tới các sự kiện bằng client.subscribe_to_events(). Truyền một chuỗi topic như "OrderBook/ALOT/USDC" và một hàm callback bất đồng bộ nhận mỗi sự kiện dưới dạng từ điển.

async def on_orderbook_update(event):
    print("Cập nhật:", 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)  # lắng nghe trong một phút

Kết nối WebSocket tự động xử lý việc ngắt kết nối và kết nối lại. Hàm callback của bạn là một hàm async chạy trên event loop, vì vậy nó có thể tương tác với phần còn lại của logic giao dịch của bạn một cách tự nhiên.

Cấu hình nhanh

Mọi thứ đều có thể cấu hình thông qua tham số truyền vào hàm khởi tạo, biến môi trường hoặc tệp .env. Tham số truyền vào hàm khởi tạo luôn được ưu tiên hơn. Dưới đây là các tùy chọn thường được tinh chỉnh nhất:

Tính năng chịu lỗi bạn nhận được miễn phí

Một vài hạng mục SDK tự động xử lý mà bạn nên biết:

Thử lại kèm tăng dần (backoff). Nếu một lệnh gọi API hoặc yêu cầu RPC thất bại do lỗi thoáng qua, SDK sẽ thử lại với thời gian chờ tăng theo cấp số mũ. Các giá trị mặc định là hợp lý (một vài lần thử lại với thời gian chờ tăng dần), nhưng bạn có thể tinh chỉnh để phù hợp với mức độ chịu đựng của mình. Điều này có nghĩa là bot của bạn không bị crash chỉ vì một kết nối bị rớt.

Chuyển đổi RPC dự phòng. Bạn có thể cấu hình nhiều URL nhà cung cấp RPC cho mỗi chain. Nếu một nhà cung cấp bắt đầu thất bại một cách nhất quán, SDK sẽ tự động chuyển sang nhà cung cấp tiếp theo. Các nhà cung cấp lỗi sẽ vào giai đoạn cooldown trước khi được thử lại. Nếu mọi thứ đều ngừng hoạt động, nó sẽ quay lại nhà cung cấp cuối cùng đã hoạt động.

Giới hạn tốc độ. SDK áp dụng giới hạn tốc độ cho cả lệnh gọi API và yêu cầu RPC bằng thuật toán token-bucket. Các giá trị mặc định (5 lệnh gọi API mỗi giây, 10 lệnh gọi RPC mỗi giây) giúp bạn nằm trong các giới hạn thông thường phía máy chủ. Nếu bạn đang chạy nhiều instance client, hãy nhớ rằng mỗi instance có bộ giới hạn riêng — chúng không dùng chung hạn mức toàn cục.

Làm sạch lỗi. Khi có chuyện gì đó không ổn xảy ra, các thông báo lỗi mà bạn thấy trong result.error được dọn sạch — không có đường dẫn tệp, không có URL RPC, không có stack trace bị rò rỉ. Trong môi trường production, điều này giúp ngăn việc vô tình lộ ra các chi tiết hạ tầng. Để debug, hãy đặt log_level thành DEBUG để xem đầy đủ ngữ cảnh trong log của bạn.

Đi tiếp từ đây ở đâu

Tài liệu này bao phủ những phần cốt lõi, nhưng SDK còn nhiều chiều sâu hơn mức chúng ta có thể trình bày ở đây. Để có cái nhìn đầy đủ:

• User Guide — trình bày mọi phương thức kèm ví dụ đầy đủ
• Tổng quan kiến trúc — giải thích thiết kế nội bộ cho những người đóng góp
• Hướng dẫn về caching — tinh chỉnh chi tiết TTL cho các cấu hình ứng dụng khác nhau
• Tài liệu tham khảo API — tài liệu được tự động tạo từ mã nguồn

SDK là mã nguồn mở. Nếu bạn tìm thấy lỗi, muốn có một tính năng hoặc có câu hỏi, thì kho lưu trữ chính là nơi để đến.

Bắt đầu trên testnet, làm quen với API, và khi chiến lược của bạn đã sẵn sàng — chuyển sang mainnet bằng cách thay đổi một biến môi trường.

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

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

Chúc bạn xây dựng vui vẻ.