# coinbase/coinbase-advanced-py architecture

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

- Interactive diagram: https://gitdiagram.com/coinbase/coinbase-advanced-py
- Repository: https://github.com/coinbase/coinbase-advanced-py

## Overview

The Coinbase Advanced API Python SDK is a library focused on enabling developers to connect easily with Coinbase’s Advanced Trade API. At its core, this is a full-featured client SDK offering both REST and WebSocket interfaces to trade endpoints, market data, and account management, while handling authentication (using JWT tokens) and connection management (including automatic reconnection logic for WebSockets).

##### Main Components
- Client Application/User Code: The developer’s code which imports and instantiates the SDK’s classes (RESTClient, WSClient, WSUserClient).
- REST API Client Module: This is encapsulated within the “coinbase/rest” directory. It handles authenticated/unauthenticated HTTP requests, rate limiting, endpoint abstraction, and the conversion/serialization of responses into custom domain objects. Modules like “api_base.py” and “rest_base.py” serve as foundational components.
- WebSocket API Client Module: Housed in “coinbase/websocket”, this part provides synchronous and asynchronous methods to handle WebSocket connections, message handling (through custom response types), subscription management, and reconnection logic.
- JWT Generator & Authentication: The “coinbase/jwt_generator.py” module manages JWT creation, ensuring that each REST or WebSocket call is properly signed with the developer’s API key and secret.
- Configuration and Build Infrastructure: Files like “setup.py”, “Makefile”, and GitHub workflow files (under “.github/workflows”) indicate integration, testing, and deployment configurations.
- Documentation & Tests: The “docs” folder and “tests” suite demonstrate that the SDK is well-tested and documented. These components illustrate usage examples and verify proper function operation.

- The WebSocket Client branch should show the connection initialization → authentication token generation → subscription to channels → message dispatch to the client code’s registered on_message handler.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different modules handle REST interactions, WebSocket communications, authentication, and response parsing.
- Modularity & Extensibility: Clearly denote individual folders (“rest”, “websocket”, “types”) that encapsulate functionalities and enable future expansion.
- Asynchronous vs Synchronous Handling: Within the WebSocket module, include notation to differentiate between async methods and threaded auto-reconnection strategies.
- Error Handling: Incorporate components (e.g., WSClientException, WSClientConnectionClosedException) that illustrate how the SDK manages failures and reconnection logic.

##### Incorporate Relevant Technologies & Libraries
- Python as the programming language.
- JWT for secure token generation.
- WebSocket protocols (and associated libraries) for real-time data subscriptions.
- HTTP/REST for interacting with endpoints.
- Testing frameworks (reflected in the “tests” directory) and documentation tools.

- “REST Client” with supporting modules like “jwt_generator” and “rest_base,” and label key endpoints (accounts, orders, etc.).
- Testing and CI/CD support (from “tests”, “.github/workflows”, and “Makefile”) as supplementary infrastructure ensuring quality and reliability.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    dev("Client Application"):::external

    subgraph "Coinbase Advanced API Python SDK"
        R("REST Client"):::sdk
        J("JWT Generator & Auth"):::sdk
        RB("REST Base & API Base"):::sdk
        W("WebSocket Client"):::sdk
        WB("WebSocket Base & Channels"):::sdk
    end

    ext("Coinbase Advanced Trade API"):::external

    subgraph "Configuration & Build"
        sp("setup.py"):::config
        mf("Makefile"):::config
        ghw("GitHub Workflows"):::config
    end

    subgraph "Documentation & Tests"
        docs_node("Docs"):::config
        tests_node("Tests"):::config
    end

    dev -->|"uses"| R
    dev -->|"uses"| W

    R -->|"calls"| J
    J -->|"generatesToken"| RB
    R -->|"HTTPScalls"| ext

    W -->|"initiates"| WB
    W -->|"WSsubscription"| ext

    ext -->|"responses"| R
    ext -->|"messages"| W

    R -.-> sp
    R -.-> ghw
    W -.-> mf
    W -.-> tests_node

    classDef sdk fill:#E0F7FA,stroke:#00838F,stroke-width:2px;
    classDef external fill:#FCE4EC,stroke:#AD1457,stroke-width:2px;
    classDef config fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;

    click R "https://github.com/coinbase/coinbase-advanced-py/tree/master/coinbase/rest/"
    click RB "https://github.com/coinbase/coinbase-advanced-py/blob/master/coinbase/rest/rest_base.py"
    click J "https://github.com/coinbase/coinbase-advanced-py/blob/master/coinbase/jwt_generator.py"
    click W "https://github.com/coinbase/coinbase-advanced-py/tree/master/coinbase/websocket/"
    click WB "https://github.com/coinbase/coinbase-advanced-py/blob/master/coinbase/websocket/websocket_base.py"
    click sp "https://github.com/coinbase/coinbase-advanced-py/blob/master/setup.py"
    click mf "https://github.com/coinbase/coinbase-advanced-py/tree/master/Makefile"
    click ghw "https://github.com/coinbase/coinbase-advanced-py/tree/master/.github/workflows/"
    click docs_node "https://github.com/coinbase/coinbase-advanced-py/tree/master/docs/"
    click tests_node "https://github.com/coinbase/coinbase-advanced-py/tree/master/tests/"
```
