candle-data-manager 0.2.0

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

Candle Data Manager

암호화폐 및 주식 시장의 OHLCV 캔들 데이터를 수집, 저장, 관리하는 패키지. OHLCV candle data fetch, store, manage for cryptocurrency and stock markets.

Installation

pip install candle-data-manager

Requirements

• Python >= 3.10
• MySQL Server

.env

인증이 필요한 거래소의 API 키를 설정한다. API key is required for exchanges that need authentication.

# 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

# KRX OpenAPI (선택사항 / optional)
KRX_API_KEY=your_krx_api_key

KRX는 두 가지 provider를 지원한다: KRX supports two providers:

• KRXProvider (primary): KRX OpenAPI (openapi.krx.co.kr) 사용. KRX_API_KEY 필요. Uses KRX OpenAPI. Requires KRX_API_KEY.
• KRXFallbackProvider (fallback): FinanceDataReader 사용. API 키 불필요. Uses FinanceDataReader. No API key required.

KRX_API_KEY가 설정되지 않으면 자동으로 FinanceDataReader로 전환된다. If KRX_API_KEY is not set, automatically falls back to FinanceDataReader.

KRX OpenAPI 설정 / KRX OpenAPI Setup

KRX OpenAPI는 활성화를 위해 2단계 절차가 필요하다. KRX OpenAPI requires two separate steps to activate:

1. API 키 발급: openapi.krx.co.kr에 회원가입 후 마이페이지에서 API 키를 신청한다. Sign up at openapi.krx.co.kr, go to My Page, request an API key.

2. 서비스별 개별 승인: API 키를 받은 후, 사용할 데이터 서비스를 각각 별도로 신청해야 한다. "서비스 이용" 메뉴에서 원하는 서비스를 선택하고 하단의 "API 이용신청" 버튼을 클릭한다. After receiving the key, you must individually apply for each data service. Go to "Service Usage" menu, select the service, and click "API Usage Request" at the bottom.

필요한 서비스: Required services:

• 유가증권 일별매매정보 / Securities Daily Trading Info (sto/stk_bydd_trd) - KOSPI
• 코스닥 일별매매정보 / KOSDAQ Daily Trading Info (sto/ksq_bydd_trd) - KOSDAQ

각 서비스는 관리자 승인이 필요하다 (보통 1일 이내). 키와 서비스 모두 승인될 때까지 API 호출 시 401 Unauthorized가 반환된다. Each service requires admin approval (usually within 1 day). API calls will return 401 Unauthorized until both the key and the service are approved.

NASDAQ, NYSE는 FinanceDataReader를 통해 제공된다. API 키 불필요. NASDAQ, NYSE are provided via FinanceDataReader. No API key required.

Quick Start

from candle_data_manager import CandleDataAPI

api = CandleDataAPI()

# BTC/USDT 1d 캔들 수집 및 저장
# BTC/USDT 1d candle: fetch and store
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base="BTC",
    quote="USDT",
    timeframe="1d"
)

# DB에서 로드
# load from DB
markets = api.load(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base="BTC",
    quote="USDT",
    timeframe="1d"
)
print(markets[0].candles)  # pandas DataFrame (OHLCV)

api.close()

API Reference

CandleDataAPI(database_url=None)

# 기본값 / default: mysql+pymysql://root@localhost/candle_data_manager
api = CandleDataAPI()

# 커스텀 / custom
api = CandleDataAPI(database_url="mysql+pymysql://user:pass@host/dbname")

초기화 시 DB와 테이블이 자동 생성된다. DB and tables are auto-created on init.

---

active_update(archetype, exchange, tradetype, base, quote, timeframe)

거래소 마켓 리스트에서 새 심볼을 등록하고 전체 과거 데이터를 수집한다. Register new symbols from exchange market list and fetch all historical data.

# 모든 Binance Spot 마켓, 모든 타임프레임
# all Binance Spot markets, all timeframes
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT"
)

# 필터: 특정 base/quote/timeframe
# filtered: specific base/quote/timeframe
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base=["BTC", "ETH"],
    quote="USDT",
    timeframe=["1h", "1d"]
)

# KRX 주식
# KRX stocks
result = api.active_update(
    archetype="STOCK",
    exchange="KRX",
    tradetype="SPOT",
    base="005930",
    timeframe="1d"
)

Parameters:

• archetype (str): "CRYPTO" 또는 "STOCK" / "CRYPTO" or "STOCK"
• exchange (str): "BINANCE", "UPBIT", "KRX", "NASDAQ", "NYSE"
• tradetype (str): "SPOT" 또는 "FUTURES" / "SPOT" or "FUTURES"
• base (str | list[str], optional): base 자산으로 필터 / filter by base asset
• quote (str | list[str], optional): quote 자산으로 필터 / filter by quote asset
• timeframe (str | list[str], optional): 타임프레임으로 필터. None = 지원하는 전체 / filter by timeframe. None = all supported

Returns: UpdateResult(success_symbols, failed_symbols, total_rows)

---

passive_update(archetype, exchange, tradetype, base, quote, timeframe, buffer_size)

등록된 심볼의 증분 업데이트. 마지막 저장 시점부터 현재까지 수집한다. Incremental update for registered symbols. Fetches from last stored timestamp (inclusive) to now.

# 등록된 모든 Binance 심볼 업데이트
# update all registered Binance symbols
result = api.passive_update(
    exchange="BINANCE"
)

# 특정 조건으로 업데이트
# update specific conditions
result = api.passive_update(
    archetype="CRYPTO",
    exchange="UPBIT",
    tradetype="SPOT"
)

모든 파라미터는 선택사항. None = 필터 없음 (조건에 맞는 모든 등록 심볼 업데이트). All parameters are optional. None = no filter (updates all registered symbols matching conditions).

Returns: UpdateResult(success_symbols, failed_symbols, total_rows)

---

load(archetype, exchange, tradetype, base, quote, timeframe, start_at, end_at, limit)

DB에서 캔들 데이터를 Market 객체로 로드한다. Load candle data from DB as Market objects.

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

for market in markets:
    print(market.symbol.to_string())  # "CRYPTO-BINANCE-SPOT-BTC-USDT-1h"
    print(market.candles)             # pandas DataFrame
    #    timestamp       open       high        low      close     volume
    # 0  1609459200  29000.50   29100.00   28900.00  29050.00   1234.56

모든 파라미터는 선택사항. list[Market]을 반환한다. All parameters are optional. Returns list[Market].

---

get_symbol(symbol_str)

symbol = api.get_symbol("CRYPTO-BINANCE-SPOT-BTC-USDT-1h")
# Symbol 객체 또는 None 반환
# Returns Symbol object or None

---

close()

api.close()

Supported Providers

지원하는 Provider 목록. List of supported providers.

Provider	archetype	exchange	tradetype	timeframes
Binance Spot	CRYPTO	BINANCE	SPOT	1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
Binance Futures	CRYPTO	BINANCE	FUTURES	1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
Upbit	CRYPTO	UPBIT	SPOT	1m, 3m, 5m, 10m, 30m, 1h, 4h, 1d, 1w, 1M
KRX	STOCK	KRX	SPOT	1d
NASDAQ	STOCK	NASDAQ	SPOT	1d
NYSE	STOCK	NYSE	SPOT	1d

Symbol Format

심볼 문자열 형식. Symbol string format.

ARCHETYPE-EXCHANGE-TRADETYPE-BASE-QUOTE-TIMEFRAME

CRYPTO-BINANCE-SPOT-BTC-USDT-1h
CRYPTO-UPBIT-SPOT-BTC-KRW-1d
STOCK-KRX-SPOT-005930-KRW-1d
STOCK-NASDAQ-SPOT-AAPL-USD-1d

License

MIT License