# ccxt/binance-python architecture

> Architecture diagram of the GitHub repository ccxt/binance-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ccxt/binance-python
- Repository: https://github.com/ccxt/binance-python

## Overview

##### Project Type and Purpose
- This is an open-source Python SDK for the Binance cryptocurrency exchange.  It provides synchronous, asynchronous, and WebSocket (“WS”) access to Binance’s REST and real-time APIs.  It vendors the CCXT library internals under `binance/ccxt`, ships build/packaging scripts, and offers example clients.

##### High-Level File-Structure Analysis
- Top-level:
- `binance/` – the main SDK package
- `build/` – TypeScript build and packaging scripts (npm config, templates)
- `examples/` – sample code demonstrating sync, async, WS usage
- `setup.py`, `requirements.txt`, `pypi-packager.ts` – packaging to PyPI
- `.github/workflows/` – CI/CD pipelines
- Under `binance/ccxt/`:
- `abstract/` – abstract base exchange definitions
- `base/` – core types, errors, throttler, ws client, order-book logic
- `async_support/` – async variants of base and ws modules
- `binance.py` in each layer – concrete adapters implementing Binance-specific endpoints
- `static_dependencies/` – vendored third-party libs (ecdsa, ethereum, lark, marshmallow, etc.) to avoid external install
- `binance/ccxt/pro/` – “pro” edition overrides
- Build artifacts and version file: `build/`, `ccxt_version`

##### Core README Insights
- Supports three usage modes (Sync, Async, WS).
- Underlying design: a unified “CCXT” interface adapted for Binance, plus direct raw endpoint calls.
- Relies on layered inheritance: abstract → base → concrete → sync/async.

1. User Application (examples or third-party app)
2. SDK Public API Layer (`binance/__init__.py`, `BinanceSync`, `BinanceAsync`, `BinanceWs`)
3. CCXT Core Layer
- Abstract exchange classes
- Base utilities (throttler, ws client, order-book cache)
- Binance-specific adapter classes
- Async subclasses under `async_support/`
4. Vendored Static Dependencies (ECDSA, Ethereum ABI, Lark parser, Marshmallow, etc.)
5. Build & Packaging Tools (`build/` TS scripts → create PyPI wheel)
6. External Services
- Binance REST API Endpoints
- Binance WebSocket Streams
- CI/CD (GitHub Actions)

- User App → SDK Public API → CCXT Core Layer → External REST/WS
- SDK Core uses Static Dependencies for crypto, parsing, serialization
- Build Scripts → Package Artifact → PyPI
- CI/CD → Build & Test → Deploy to PyPI

c. Architectural Patterns & Principles
- Layered Architecture: separation of Public API, Core CCXT logic, static deps
- Adapter/Template Method: abstract exchange definitions overridden by Binance
- Inheritance & Mix-ins: sync vs async variants sharing base code
- Vendor Isolation: bundling third-party libs in `static_dependencies/` to ensure consistent behavior

d. Key Technologies & Frameworks
- Python 3.x
- CCXT library internals (vendored)
- AsyncIO for non-blocking calls
- WebSocket client abstraction
- TypeScript & Node.js for build/packager
- GitHub Actions for CI/CD
- setuptools / pip / PyPI

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Application (Examples)"
        EX_SYNC[/Sync Example/]:::userApp
        EX_ASYNC[/Async Example/]:::userApp
        EX_WS[/WS Example/]:::userApp
    end

    subgraph "SDK Public API Layer"
        SDK["SDK Public API"]:::api
    end

    subgraph "CCXT Core Layer"
        subgraph "Abstract Exchange"
            ABSTRACT["Abstract Exchange"]:::core
        end
        subgraph "Base Utilities"
            BASE_EX["Exchange"]:::core
            BASE_DP["Decimal to Precision"]:::core
            BASE_ERR["Errors"]:::core
            BASE_PR["Precise"]:::core
            BASE_TYPES["Types"]:::core
        end
        subgraph "Binance Adapters"
            ADAPTER_SYNC["Sync Binance Adapter"]:::core
            ADAPTER_ASYNC["Async Binance Adapter"]:::core
            ADAPTER_PRO["Pro Binance Adapter"]:::core
        end
        subgraph "Async Support"
            ASYNC_EX["Async Exchange"]:::core
            ASYNC_THROTTLER["Async Throttler"]:::core
            subgraph "WebSocket Support"
                WS_CLIENT["WS Client"]:::core
                WS_CACHE["WS Cache"]:::core
                WS_FUNC["WS Functions"]:::core
                WS_FUTURE["WS Future"]:::core
                WS_ORDER_BOOK["Order Book"]:::core
                WS_OB_SIDE["Order Book Side"]:::core
            end
        end
    end

    VENDOR["Vendored Static Dependencies"]:::vendor

    subgraph "Build & Packaging Tools"
        BUILD_TS["build.ts"]:::build
        PACK_TS["pypi-packager.ts"]:::build
        UTILS_TS["utils.ts"]:::build
        NPM_CONF["package.json"]:::build
        TEMPL_TS["pyproject.toml"]:::build
        TEMPL_EX["Example Templates"]:::build
        SETUP["setup.py"]:::build
        REQ["requirements.txt"]:::build
        CCXT_VER["ccxt_version"]:::build
    end

    subgraph "CI/CD (GitHub Actions)"
        CI["Build Workflow"]:::ci
    end

    subgraph "External Services"
        REST[(Binance REST API)]:::external
        WS_STREAM[(Binance WS Streams)]:::external
        PYPI[(PyPI Repository)]:::external
    end

    EX_SYNC --> SDK
    EX_ASYNC --> SDK
    EX_WS --> SDK

    SDK --> ABSTRACT
    SDK --> BASE_EX
    SDK --> VENDOR
    SDK --> ADAPTER_SYNC
    SDK --> ASYNC_EX

    ABSTRACT --> ADAPTER_SYNC
    ABSTRACT --> ADAPTER_ASYNC
    BASE_EX --> ADAPTER_SYNC
    BASE_EX --> ASYNC_EX

    VENDOR --> BASE_EX

    ADAPTER_SYNC -.-> REST
    ASYNC_EX -.-> REST
    WS_CLIENT -.-> WS_STREAM
    WS_FUNC --> WS_STREAM

    BUILD_TS --> PACK_TS
    PACK_TS --> PYPI
    SETUP --> PYPI
    CI --> BUILD_TS
    CI --> PYPI

    classDef userApp fill:#fdf,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px
    classDef vendor fill:#fbc,stroke:#333,stroke-width:1px
    classDef build fill:#eee,stroke:#333,stroke-width:1px
    classDef ci fill:#ccc,stroke:#333,stroke-width:1px
    classDef external fill:#dcd,stroke:#333,stroke-width:1px

    click SDK "https://github.com/ccxt/binance-python/blob/main/binance/__init__.py"
    click EX_SYNC "https://github.com/ccxt/binance-python/blob/main/examples/sync.py"
    click EX_ASYNC "https://github.com/ccxt/binance-python/blob/main/examples/async.py"
    click EX_WS "https://github.com/ccxt/binance-python/blob/main/examples/websockets.py"
    click ABSTRACT "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/abstract/binance.py"
    click BASE_EX "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/base/exchange.py"
    click BASE_DP "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/base/decimal_to_precision.py"
    click BASE_ERR "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/base/errors.py"
    click BASE_PR "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/base/precise.py"
    click BASE_TYPES "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/base/types.py"
    click ADAPTER_SYNC "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/binance.py"
    click ADAPTER_ASYNC "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/binance.py"
    click ADAPTER_PRO "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/pro/binance.py"
    click ASYNC_EX "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/exchange.py"
    click ASYNC_THROTTLER "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/throttler.py"
    click WS_CLIENT "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/ws/client.py"
    click WS_CACHE "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/ws/cache.py"
    click WS_FUNC "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/ws/functions.py"
    click WS_FUTURE "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/ws/future.py"
    click WS_ORDER_BOOK "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/ws/order_book.py"
    click WS_OB_SIDE "https://github.com/ccxt/binance-python/blob/main/binance/ccxt/async_support/base/ws/order_book_side.py"
    click VENDOR "https://github.com/ccxt/binance-python/tree/main/binance/ccxt/static_dependencies"
    click BUILD_TS "https://github.com/ccxt/binance-python/blob/main/build/build.ts"
    click PACK_TS "https://github.com/ccxt/binance-python/blob/main/build/pypi-packager.ts"
    click UTILS_TS "https://github.com/ccxt/binance-python/blob/main/build/utils.ts"
    click NPM_CONF "https://github.com/ccxt/binance-python/blob/main/build/package.json"
    click TEMPL_TS "https://github.com/ccxt/binance-python/blob/main/build/templates/pyproject.toml"
    click TEMPL_EX "https://github.com/ccxt/binance-python/tree/main/build/templates/examples/"
    click SETUP "https://github.com/ccxt/binance-python/blob/main/setup.py"
    click REQ "https://github.com/ccxt/binance-python/blob/main/requirements.txt"
    click CCXT_VER "https://github.com/ccxt/binance-python/tree/main/ccxt_version"
    click CI "https://github.com/ccxt/binance-python/tree/main/.github/workflows/"
```
