candle-data-manager 0.1.1

Fetch, store, and manage OHLCV candle data from cryptocurrency exchanges (Binance, Upbit) with MySQL storage

Candle Data Manager

Candle data management tool for cryptocurrency and stock markets.

Installation

pip install candle-data-manager

Requirements

• Python >= 3.10
• MySQL Server
• .env file with API keys:

# Binance
BINANCE_API_KEY=your_binance_api_key
BINANCE_API_SECRET=your_binance_api_secret

# Upbit
UPBIT_API_KEY=your_upbit_api_key
UPBIT_API_SECRET=your_upbit_api_secret

Overview

Initialize

from candle_data_manager import CandleDataAPI

# Default: mysql+pymysql://root@localhost/candle_data_manager
api = CandleDataAPI()

# Or with custom database URL
api = CandleDataAPI(database_url="mysql+pymysql://user:password@host/dbname")

Active Update

Fetch and store all historical data for symbols.

# Update all Binance Futures PERPETUAL markets
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="FUTURES"
)

# Update specific symbol with filters
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base="BTC",
    quote="USDT",
    timeframe="1d"
)

print(f"Success: {result.success_count}, Failed: {result.fail_count}, Rows: {result.total_rows}")

Passive Update

Incremental update for registered symbols.

result = api.passive_update(
    archetype="CRYPTO",
    exchange="BINANCE"
)

Load Data

Load candle data as Market objects.

markets = api.load(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base="BTC",
    quote="USDT",
    timeframe="1h",
    start_at=1609459200,
    end_at=1609545600
)

for market in markets:
    print(market.symbol)
    print(market.candles)  # pandas DataFrame

API Reference

CandleDataAPI

Method	Description
__init__(database_url=None)	Initialize API with MySQL connection. Creates database schema and tables if not exists. Default: mysql+pymysql://root@localhost/candle_data_manager
active_update(archetype, exchange, tradetype, base, quote, timeframe)	Register new symbols from exchange market list and fetch all historical candle data from the earliest available timestamp. Filters can be string or list (e.g., base=["BTC", "ETH"]). Returns UpdateResult with success/fail counts and total rows.
passive_update(archetype, exchange, tradetype, base, quote, timeframe, buffer_size)	Incremental update for registered symbols. Fetches candles from the last stored timestamp to current time, updating the last candle and appending new candles. Returns UpdateResult.
load(archetype, exchange, tradetype, base, quote, timeframe, start_at, end_at)	Load candle data from database as Market objects. Each Market contains symbol and candles (pandas DataFrame with OHLCV columns). Auto-fetches missing data if not in database.
get_symbol(symbol_str)	Get Symbol object by string identifier. Format: "ARCHETYPE-EXCHANGE-TRADETYPE-BASE-QUOTE-TIMEFRAME" (e.g., "CRYPTO-BINANCE-SPOT-BTC-USDT-1h"). Returns None if not found.
close()	Close all database connections and release resources.

Supported Providers

Provider	Archetype	Exchange	TradeType
Binance Spot	CRYPTO	BINANCE	SPOT
Binance Futures	CRYPTO	BINANCE	FUTURES
Upbit	CRYPTO	UPBIT	SPOT

License

MIT License