# aoki-h-jp/funding-rate-arbitrage architecture

> Architecture diagram of the GitHub repository aoki-h-jp/funding-rate-arbitrage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aoki-h-jp/funding-rate-arbitrage
- Repository: https://github.com/aoki-h-jp/funding-rate-arbitrage

## Overview

##### Project type and purpose
- It is an **open-source Python library** (packaged via `setup.py`) whose core function is to **fetch funding rates and commission data** from multiple CEXs, **compute divergences/revenue**, and provide display utilities.
- It is **not** a web service or database-backed app; instead it interacts with **external APIs** of exchanges.

##### File structure (mapping to logical components)
- **funding_rate_arbitrage/**
- frarb.py → contains the **FundingRateArbitrage** class: public API methods (`fetch_all_funding_rate`, `get_commission`, `fetch_funding_rate_history`, `display_*`).
- `__init__.py` → package entry point.
- **examples/**
Contains standalone Python scripts that import the library and demonstrate usage.
- **requirements.txt** / **setup.py**
Declare dependencies (e.g., `ccxt` or similar) and package metadata.
- **.github/**
CI formatting checks (not part of runtime).
- **img/**
Illustrations for README (not part of runtime).

##### README for insights
- Lists supported CEXs (binance, bybit, OKX, gate.io, CoinEx, Bitget).
- Demonstrates three types of operations:
a. Fetching raw data (funding rates & commissions)
b. Fetching historical data
c. Computing/displaying large divergences (single/multi-exchange)

##### Main components
A. **User / Example scripts**
– Entry point (e.g. `examples/fetch_funding_rate.py`)
B. **Library Core (funding_rate_arbitrage package)**
1. **API Adapter Layer**
– Adapters or wrappers for each exchange’s REST/WebSocket API (likely via `ccxt` under the hood).
2. **Data Retrieval Module**
– Methods that call adapters to fetch funding rates & commissions.
3. **Processing Module**
– Business logic: calculate divergences, revenue, sorting.
4. **Presentation / CLI Module**
– `display_large_divergence_*` and `display_one_by_one_*` methods that format & print results.
C. **External Services**
– CEXs: Binance, Bybit, OKX, Gate.io, CoinEx, Bitget.
D. **Packaging / CI**
– `setup.py`, `requirements.txt` for build & distribution; `.github/workflows` for linting/formatting.

##### Relationships & data flow
- **Example script** → invokes → **Library Core (FundingRateArbitrage)**
→ calls → **API Adapter Layer**
→ sends HTTP requests → **External Exchange APIs**
→ returns JSON responses → **Data Retrieval Module**
→ passes raw data → **Processing Module**
→ produces computed results → **Presentation Module**
→ outputs to console (or returns to user code).
- **CI Workflow** is separate: triggers `Formatter.yaml` on code pushes.

##### Architectural patterns & design principles
- **Adapter Pattern** for exchange integrations (each exchange behind the same interface).
- **Single Responsibility**: separate retrieval, processing, and display.
- **Modular Packaging**: one top-level package, clear public API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User / Example Scripts
    subgraph "User / Example Scripts"
        FS1["fetch_funding_rate.py"]:::external
        FS2["fetch_funding_rate_all_exchanges.py"]:::external
        FS3["fetch_funding_rate_history.py"]:::external
        FS4["get_commission.py"]:::external
        FS5["get_large_divergence_multi_exchange.py"]:::external
        FS6["get_large_divergence_single_exchange.py"]:::external
    end

    %% Library Core
    subgraph "Library Core" 
        EP["Package Entry (__init__.py)"]:::internal
        FR["FundingRateArbitrage Class (frarb.py)"]:::internal
        AD["API Adapter Layer"]:::internal
        DR["Data Retrieval Module"]:::internal
        PR["Processing Module"]:::internal
        PT["Presentation Module"]:::internal
    end

    %% External Exchanges
    subgraph "External Exchanges"
        BZ[("Binance API")]:::external
        BB[("Bybit API")]:::external
        OK[("OKX API")]:::external
        GI[("Gate.io API")]:::external
        CE[("CoinEx API")]:::external
        BG[("Bitget API")]:::external
    end

    %% Packaging / CI
    subgraph "Packaging / Distribution & CI"
        SP["setup.py"]:::tooling
        RQ["requirements.txt"]:::tooling
        CI["Formatter Workflow"]:::tooling
    end

    %% Connections
    FS1 -->|"import library"| EP
    FS2 -->|"import library"| EP
    FS3 -->|"import library"| EP
    FS4 -->|"import library"| EP
    FS5 -->|"import library"| EP
    FS6 -->|"import library"| EP

    EP -->|"initialize()"| FR
    FR -->|"fetch_all_funding_rate()"| AD
    AD -->|"HTTP GET /funding_rate"| BZ
    AD -->|"HTTP GET /funding_rate"| BB
    AD -->|"HTTP GET /funding_rate"| OK
    AD -->|"HTTP GET /funding_rate"| GI
    AD -->|"HTTP GET /funding_rate"| CE
    AD -->|"HTTP GET /funding_rate"| BG
    BZ -->|"JSON response"| AD
    BB -->|"JSON response"| AD
    OK -->|"JSON response"| AD
    GI -->|"JSON response"| AD
    CE -->|"JSON response"| AD
    BG -->|"JSON response"| AD

    AD -->|"raw data"| DR
    DR -->|"parsed data"| PR
    PR -->|"computed results"| PT
    PT -->|"output to console"| EP

    SP
    RQ
    CI

    %% Click Events
    click FS1 "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/examples/fetch_funding_rate.py"
    click FS2 "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/examples/fetch_funding_rate_all_exchanges.py"
    click FS3 "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/examples/fetch_funding_rate_history.py"
    click FS4 "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/examples/get_commission.py"
    click FS5 "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/examples/get_large_divergence_multi_exchange.py"
    click FS6 "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/examples/get_large_divergence_single_exchange.py"
    click EP "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/funding_rate_arbitrage/__init__.py"
    click FR "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/funding_rate_arbitrage/frarb.py"
    click SP "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/setup.py"
    click RQ "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/requirements.txt"
    click CI "https://github.com/aoki-h-jp/funding-rate-arbitrage/blob/main/.github/workflows/Formatter.yaml"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#1e88e5
    classDef external fill:#c8e6c9,stroke:#388e3c,color:#388e3c
    classDef tooling fill:#e0e0e0,stroke:#757575,color:#424242
```
