api-reference.md

API Referansı

Algo Trade Bot modüllerinin public API dokümantasyonu.

📦 Modül İndeksi

• common - Ortak yardımcı modüller
• interfaces - Abstract base class'lar
• data - Veri ingestion ve feature engineering
• models - ML modelleri
• research - Training pipeline
• backtest - Backtest engine
• strategy - Sinyal ve risk yönetimi
• broker - Broker entegrasyonu
• live - Canlı trading runner

---

common

config.py

class Settings(BaseSettings)

Merkezi konfigürasyon sınıfı.

from algo_trader.common.config import Settings

settings = Settings()

Attributes:

Attribute	Type	Default	Description
DATA_DIR	str	"data/raw"	Ham veri dizini
ARTIFACTS_DIR	str	"artifacts"	Artifact çıktı dizini
REGISTRY_DIR	str	"artifacts/registry"	Model registry
DEFAULT_SYMBOL	str	"BTCUSDT"	Varsayılan sembol
DEFAULT_TIMEFRAME	str	"1h"	Varsayılan timeframe
LIVE_MIN_EDGE	float	0.02	Minimum sinyal edge'i
LIVE_MIN_PROB_LONG	float	0.55	Long için min olasılık
LIVE_MAX_PROB_SHORT	float	0.45	Short için max olasılık
MAX_POSITION_PCT	float	0.20	Max pozisyon yüzdesi
MAX_DRAWDOWN_PCT	float	0.10	Max drawdown limiti
ALPACA_API_KEY	str	None	Alpaca API key (env)
ALPACA_API_SECRET	str	None	Alpaca API secret (env)
ALPACA_BASE_URL	str	"https://paper-api.alpaca.markets"	Alpaca URL

---

logger.py

get_logger(name: str) -> Logger

Loguru logger instance döndürür.

from algo_trader.common.logger import get_logger

logger = get_logger(__name__)
logger.info("Message")

Parameters:

• name (str): Logger adı (genellikle __name__)

Returns:

• Logger: Loguru logger instance

---

storage.py

save_parquet(df: pd.DataFrame, path: str) -> None

DataFrame'i parquet olarak kaydeder.

from algo_trader.common.storage import save_parquet

save_parquet(df, "data/raw/btc_1h.parquet")

load_parquet(path: str) -> pd.DataFrame

Parquet dosyasını DataFrame olarak yükler.

from algo_trader.common.storage import load_parquet

df = load_parquet("data/raw/btc_1h.parquet")

save_csv(df: pd.DataFrame, path: str) -> None

DataFrame'i CSV olarak kaydeder.

ensure_dir(path: str) -> None

Dizin yoksa oluşturur.

---

time.py

to_utc(dt: datetime) -> datetime

Datetime'ı UTC'ye çevirir.

parse_datetime(s: str) -> datetime

String'i datetime'a parse eder.

get_bar_close_time(dt: datetime, timeframe: str) -> datetime

Bar kapanış zamanını hesaplar.

timestamp_ms(dt: datetime) -> int

Millisecond timestamp döndürür.

from_timestamp_ms(ts: int) -> datetime

Timestamp'tan datetime oluşturur.

---

secrets.py

get_alpaca_credentials() -> Tuple[str, str, str]

Alpaca API bilgilerini döndürür.

from algo_trader.common.secrets import get_alpaca_credentials

api_key, api_secret, base_url = get_alpaca_credentials()

validate_paper_mode(base_url: str) -> None

Paper trading URL'i doğrular. Live URL'de ValueError fırlatır.

---

interfaces

broker.py

class BaseBroker(ABC)

Broker implementasyonları için abstract base class.

from algo_trader.interfaces import BaseBroker

class MyBroker(BaseBroker):
    def get_account(self) -> Dict[str, Any]: ...
    def get_positions(self) -> List[Dict[str, Any]]: ...
    def get_position(self, symbol: str) -> Optional[Dict[str, Any]]: ...
    def place_order(self, symbol: str, qty: float, side: str, ...) -> Dict[str, Any]: ...
    def cancel_order(self, order_id: str) -> bool: ...
    def get_bars(self, symbol: str, timeframe: str, limit: int) -> pd.DataFrame: ...

Abstract Methods:

Method	Returns	Description
get_account()	Dict	Hesap bilgileri
get_positions()	List[Dict]	Tüm pozisyonlar
get_position(symbol)	Dict | None	Belirli pozisyon
place_order(...)	Dict	Order sonucu
cancel_order(id)	bool	İptal sonucu
get_bars(...)	DataFrame	OHLCV verisi

---

model.py

class ModelInterface(ABC)

ML model implementasyonları için abstract base class.

from algo_trader.interfaces import ModelInterface

class MyModel(ModelInterface):
    def fit(self, X: pd.DataFrame, y: pd.Series) -> "MyModel": ...
    def predict(self, X: pd.DataFrame) -> np.ndarray: ...
    def predict_proba(self, X: pd.DataFrame) -> np.ndarray: ...
    def get_feature_names(self) -> List[str]: ...
    def save(self, path: str) -> None: ...
    @classmethod
    def load(cls, path: str) -> "MyModel": ...
    def get_params(self) -> Dict[str, Any]: ...

Abstract Methods:

Method	Returns	Description
fit(X, y)	Self	Model eğitir
predict(X)	ndarray	Class labels
predict_proba(X)	ndarray	Probabilities
get_feature_names()	List[str]	Feature isimleri
save(path)	None	Diske kaydet
load(path)	Model	Diskten yükle
get_params()	Dict	Parametreler

---

data

ingest.py

fetch_binance_ohlcv(symbol, interval, start_date, end_date) -> pd.DataFrame

Binance'ten OHLCV verisi çeker.

from algo_trader.data.ingest import fetch_binance_ohlcv

df = fetch_binance_ohlcv(
    symbol="BTCUSDT",
    interval="1h",
    start_date="2024-01-01",
    end_date="2025-01-01",
)

Parameters:

• symbol (str): Trading sembolü
• interval (str): Zaman dilimi ("1h", "4h", "1d")
• start_date (str): Başlangıç tarihi
• end_date (str): Bitiş tarihi

Returns:

• pd.DataFrame: timestamp, open, high, low, close, volume

---

features.py

build_features(df: pd.DataFrame) -> pd.DataFrame

OHLCV'den 37 teknik gösterge hesaplar.

from algo_trader.data.features import build_features

features = build_features(ohlcv_df)

Parameters:

• df (pd.DataFrame): OHLCV DataFrame

Returns:

• pd.DataFrame: 37 feature column

Feature List:

• Returns: log_return_1, log_return_4, log_return_24
• MA: sma_24, ema_12, ema_26
• Momentum: rsi_14, roc_12, roc_24, macd, macd_signal, macd_hist
• Volatility: atr_14, bb_upper, bb_lower, bb_width, realized_vol_24
• Volume: volume_sma_24, volume_ratio
• Candlestick: body_size, upper_shadow, lower_shadow, candle_range, body_ratio

---

labels.py

build_labels(df: pd.DataFrame, horizons: List[int]) -> pd.DataFrame

Target label'ları oluşturur.

from algo_trader.data.labels import build_labels

labels = build_labels(ohlcv_df, horizons=[4, 8, 24])

Parameters:

• df (pd.DataFrame): OHLCV DataFrame
• horizons (List[int]): Forward horizons (bars)

Returns:

• pd.DataFrame: return_N, direction_N, vol_realized_N columns

---

models

sklearn_baseline.py

class SklearnBaseline(ModelInterface)

StandardScaler + LogisticRegression pipeline.

from algo_trader.models import SklearnBaseline

model = SklearnBaseline(C=1.0, balanced=True)
model.fit(X_train, y_train)
proba = model.predict_proba(X_test)

Constructor Parameters:

• C (float): Regularization (default: 1.0)
• balanced (bool): Class weight balancing (default: True)
• max_iter (int): Max iterations (default: 1000)
• random_state (int): Random seed (default: 42)

---

calibration.py

class Calibrator

Probability calibration wrapper.

from algo_trader.models import Calibrator

calibrator = Calibrator(method="sigmoid")
calibrator.fit(val_proba, y_val)
calibrated = calibrator.transform(test_proba)

Constructor Parameters:

• method (str): "sigmoid" (Platt) veya "isotonic"

Methods:

• fit(proba, y_true): Calibrator'ı fit et
• transform(proba): Olasılıkları kalibre et
• fit_transform(proba, y_true): Fit ve transform
• save(path) / load(path): Serialization

---

research

dataset.py

build_dataset(timeframe, target, data_dir) -> pd.DataFrame

ML-ready dataset oluşturur.

from algo_trader.research.dataset import build_dataset

df = build_dataset(timeframe="1h", target="direction_4")

Parameters:

• timeframe (str): OHLCV timeframe
• target (str): Target column name
• data_dir (str): Data directory

Returns:

• pd.DataFrame: Features + target + meta columns

---

splits.py

walk_forward_split(df, train_months, val_months, step_months) -> List[Tuple]

Walk-forward cross-validation splits.

from algo_trader.research.splits import walk_forward_split

splits = walk_forward_split(df, train_months=18, val_months=3, step_months=3)
for train_idx, val_idx in splits:
    # ...

Parameters:

• df (pd.DataFrame): Dataset
• train_months (int): Training period
• val_months (int): Validation period
• step_months (int): Step size

Returns:

• List[Tuple[DatetimeIndex, DatetimeIndex]]: (train, val) index pairs

---

train.py

train_model(timeframe, target, model_type, ...) -> Dict

Model eğitir ve registry'ye kaydeder.

from algo_trader.research.train import train_model

result = train_model(
    timeframe="1h",
    target="direction_4",
    model_type="sklearn_baseline",
)

Returns:

• Dict: model_path, metrics, config

---

evaluate.py

compute_metrics(y_true, y_pred, y_proba) -> Dict

Performans metrikleri hesaplar.

from algo_trader.research.evaluate import compute_metrics

metrics = compute_metrics(y_true, y_pred, y_proba)

Returns:

• Dict: accuracy, precision, recall, f1, roc_auc, brier_score, log_loss

---

registry.py

save_model_to_registry(model, calibrator, model_type, metrics, config, feature_list)

Model'i registry'ye kaydeder.

get_latest_model_path(model_type) -> str

En son model path'ini döndürür.

load_model_from_registry(path) -> Tuple[Model, Calibrator, Dict]

Model, calibrator ve config yükler.

---

backtest

engine.py

run_backtest(model_path, data_path, config) -> Dict

Backtest çalıştırır.

from algo_trader.backtest.engine import run_backtest, BacktestConfig

result = run_backtest(
    model_path="artifacts/registry/sklearn_baseline/latest",
    data_path="data/raw/btc_1h.parquet",
    config=BacktestConfig(initial_capital=10000),
)

Returns:

• Dict: equity_curve, trades, metrics

class BacktestConfig

Attribute	Type	Default
initial_capital	float	10000
fee_bps	int	5
slippage_bps	int	10
execution	str	"NEXT_OPEN"
max_position_pct	float	0.20
max_drawdown_pct	float	0.10

---

metrics.py

compute_backtest_metrics(equity_curve, trades, initial_capital, risk_free_rate) -> Dict

Backtest performans metrikleri.

Returns:

• total_return, cagr, sharpe_ratio, sortino_ratio, calmar_ratio
• max_drawdown, win_rate, profit_factor, total_trades

---

strategy

signal_to_trade.py

class Signal(Enum)

class Signal(Enum):
    LONG = "long"
    SHORT = "short"
    FLAT = "flat"
    HOLD = "hold"

probability_to_signal(prob_up, current_position, min_edge, min_prob_long, max_prob_short) -> Signal

Olasılıktan sinyal üretir.

from algo_trader.strategy.signal_to_trade import probability_to_signal, Signal

signal = probability_to_signal(prob_up=0.65)  # Signal.LONG

---

position_sizing.py

compute_shares(signal, equity, price, max_position_pct) -> float

Pozisyon büyüklüğü hesaplar.

from algo_trader.strategy.position_sizing import compute_shares

shares = compute_shares(Signal.LONG, equity=10000, price=45000)

---

risk.py

pre_trade_check(signal, equity, current_drawdown, ...) -> Tuple[bool, str]

Trade öncesi risk kontrolü.

from algo_trader.strategy.risk import pre_trade_check

is_allowed, reason = pre_trade_check(
    signal=Signal.LONG,
    equity=10000,
    current_drawdown=0.05,
)

---

broker

alpaca_paper.py

class AlpacaPaperBroker(BaseBroker)

Production-ready Alpaca paper broker.

from algo_trader.broker import AlpacaPaperBroker

broker = AlpacaPaperBroker()
account = broker.get_account()
positions = broker.get_positions()
bars = broker.get_bars("BTCUSD", "1Hour", 100)
order = broker.place_order("BTCUSD", 0.01, "buy")

---

live

runner.py

class LiveRunner

Canlı trading runner.

from algo_trader.live.runner import LiveRunner

runner = LiveRunner(
    symbol="BTCUSD",
    timeframe="1h",
    model_path="artifacts/registry/sklearn_baseline/latest",
)

runner.run()       # Sürekli çalıştır
runner.run_once()  # Tek cycle
runner.get_status()
runner.flatten_and_stop()

---

decision.py

class DecisionEngine

Model prediction ve sinyal üretimi.

from algo_trader.live.decision import DecisionEngine

engine = DecisionEngine(model_path=path, broker=broker, symbol="BTCUSD")
decision = engine.make_decision(current_position=None)

---

state_store.py

class StateStore

State persistence.

from algo_trader.live.state_store import StateStore

store = StateStore(path="artifacts/live/state.json")
store.save(state)
state = store.load()

---

alerts.py

class AlertManager

Alert yönetimi.

from algo_trader.live.alerts import AlertManager, Alert, AlertLevel

manager = AlertManager(handlers=[ConsoleHandler()])
manager.send(Alert(level=AlertLevel.WARNING, title="High DD", message="..."))