binance-th 1.0.0

Production-ready Python async library for Binance Thailand API

binance-th

English · ไทย

A production-ready Python async library for the Binance Thailand API.

---

English

Features

• Type-Safe: Complete type annotations using Pydantic models
• Async-First: All I/O operations use async/await patterns
• Modern Python: Supports Python 3.12+
• Comprehensive Error Handling: Typed exception hierarchy for precise error handling
• Rate Limiting: Dual-window token bucket with x-mbx-used-weight reconciliation and automatic backoff
• WebSocket Support: Real-time market streams (depth, trades, klines, tickers), a self-syncing local order book, and an authenticated user-data stream with a self-healing order tracker

Installation

pip install binance-th

Quick Start

import asyncio

from binance_th import BinanceThClient, BinanceThConfig


async def main() -> None:
    config = BinanceThConfig(api_key="your_api_key", api_secret="your_api_secret")
    async with BinanceThClient(config) as client:
        # REST: order-book snapshot
        book = await client.market.depth("BTCTHB", limit=5)
        print("top bid/ask:", book.bids[0], book.asks[0])

        # WebSocket: a self-syncing local order book
        order_book = await client.ws.order_book("BTCTHB")
        await order_book.wait_synced()
        print("live best bid/ask:", order_book.best_bid(), order_book.best_ask())
        await order_book.aclose()

        # WebSocket: stream trades (async iterator)
        async for trade in client.ws.watch_trades("BTCTHB"):
            print("trade:", trade.price, trade.quantity)
            break


asyncio.run(main())

Project Status

This library is under active development.

• Phase 1: Foundation — Core models, exceptions, configuration
• Phase 2: Authentication & Rate Limiting — HMAC signatures, server-time offset, dual-window token bucket
• Phase 3: REST API Client — Market, account/wallet reads + orders (create/cancel/query)
• Phase 4: WebSocket Market Streams — depth/trade/aggTrade/kline/bookTicker/ticker + self-syncing local order book (live-verified)
• Phase 5: User-Data Stream — listenKey manager (dual GLOBAL/SITE keys), account/order events, self-healing order tracker (live-verified)
• Phase 6: Documentation & Release — Docs, security scanning (bandit/pip-audit), PyPI publish workflow — 1.0.0

Planning & Architecture Decisions

The full engineering blueprint — high-level design, functional requirements, the milestone→semver roadmap, and the Architecture Decision Records — lives in docs/plans/:

• HLD · FRD · WBS · ROADMAP
• Architecture Decision Records (ADR-0001…0017)

Documentation

See the API documentation for details on the Binance Thailand API.

License

Released under the MIT License.

---

ภาษาไทย

ไลบรารี Python แบบ async ระดับพร้อมใช้งานจริง (production-ready) สำหรับ Binance Thailand API

โค้ด ชื่อฟังก์ชัน/ตัวแปร และเส้นทาง endpoint ทั้งหมดคงไว้เป็นภาษาอังกฤษตามต้นฉบับ

คุณสมบัติ

• ปลอดภัยด้านชนิดข้อมูล (Type-Safe): กำกับชนิดข้อมูลครบถ้วนด้วยโมเดล Pydantic
• Async เป็นหลัก (Async-First): การทำงาน I/O ทั้งหมดใช้รูปแบบ async/await
• Python สมัยใหม่: รองรับ Python 3.12 ขึ้นไป
• การจัดการข้อผิดพลาดครบถ้วน: ลำดับชั้นของ exception ที่มีชนิดชัดเจน เพื่อการจัดการข้อผิดพลาดที่แม่นยำ
• การจำกัดอัตราการเรียก (Rate Limiting): token bucket แบบสองหน้าต่าง ปรับตามส่วนหัว x-mbx-used-weight พร้อม backoff อัตโนมัติ
• รองรับ WebSocket: สตรีมข้อมูลตลาดแบบเรียลไทม์ (depth, trades, klines, tickers), local order book ที่ซิงก์ตัวเอง และสตรีมข้อมูลผู้ใช้ (user-data) ที่ยืนยันตัวตนพร้อม order tracker ที่ซ่อมแซมตัวเอง

การติดตั้ง

pip install binance-th

เริ่มต้นใช้งาน

import asyncio

from binance_th import BinanceThClient, BinanceThConfig


async def main() -> None:
    config = BinanceThConfig(api_key="your_api_key", api_secret="your_api_secret")
    async with BinanceThClient(config) as client:
        # REST: order-book snapshot
        book = await client.market.depth("BTCTHB", limit=5)
        print("top bid/ask:", book.bids[0], book.asks[0])

        # WebSocket: a self-syncing local order book
        order_book = await client.ws.order_book("BTCTHB")
        await order_book.wait_synced()
        print("live best bid/ask:", order_book.best_bid(), order_book.best_ask())
        await order_book.aclose()

        # WebSocket: stream trades (async iterator)
        async for trade in client.ws.watch_trades("BTCTHB"):
            print("trade:", trade.price, trade.quantity)
            break


asyncio.run(main())

สถานะโปรเจกต์

ไลบรารีนี้อยู่ระหว่างการพัฒนาอย่างต่อเนื่อง

• Phase 1: รากฐาน (Foundation) — โมเดลหลัก, exceptions, การตั้งค่า
• Phase 2: การยืนยันตัวตนและการจำกัดอัตรา — ลายเซ็น HMAC, ชดเชยเวลาเซิร์ฟเวอร์, token bucket แบบสองหน้าต่าง
• Phase 3: REST API Client — market, account/wallet reads + orders (create/cancel/query)
• Phase 4: WebSocket Market Streams — depth/trade/aggTrade/kline/bookTicker/ticker + local order book ที่ซิงก์ตัวเอง (ตรวจสอบกับ feed จริงแล้ว)
• Phase 5: User-Data Stream — ตัวจัดการ listenKey (คีย์ GLOBAL/SITE คู่), เหตุการณ์บัญชี/คำสั่ง, order tracker ที่ซ่อมแซมตัวเอง (ตรวจสอบกับ feed จริงแล้ว)
• Phase 6: เอกสารและการเผยแพร่ — เอกสาร, สแกนความปลอดภัย (bandit/pip-audit), workflow เผยแพร่บน PyPI — 1.0.0

การวางแผนและการตัดสินใจเชิงสถาปัตยกรรม

พิมพ์เขียวทางวิศวกรรมทั้งหมด — การออกแบบระดับสูง (HLD), ข้อกำหนดเชิงหน้าที่ (FRD), แผนงานตาม milestone→semver และบันทึกการตัดสินใจเชิงสถาปัตยกรรม (ADR) — อยู่ในโฟลเดอร์ docs/plans/:

• HLD · FRD · WBS · ROADMAP
• บันทึกการตัดสินใจเชิงสถาปัตยกรรม (ADR-0001…0017)

เอกสารประกอบ

ดูรายละเอียด Binance Thailand API ได้ที่ เอกสาร API

สัญญาอนุญาต

เผยแพร่ภายใต้ สัญญาอนุญาต MIT