Metadata-Version: 2.4
Name: candlecraft
Version: 0.2.0
Summary: Unified OHLCV fetching for crypto, forex, and equities with multi-provider support and technical indicators
Author: AlfredAlpino
Maintainer: AlfredAlpino
License: MIT
Project-URL: Homepage, https://github.com/alfredalpino/Candlecraft
Project-URL: Documentation, https://github.com/alfredalpino/Candlecraft/blob/main/ARCHITECTURE.md
Project-URL: Repository, https://github.com/alfredalpino/Candlecraft
Project-URL: Issues, https://github.com/alfredalpino/Candlecraft/issues
Keywords: ohlcv,crypto,forex,equity,trading,binance,twelvedata,financial-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-binance>=1.0.0
Requires-Dist: websocket-client>=1.6.0
Requires-Dist: twelvedata>=1.0.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# Candlecraft

[![PyPI](https://img.shields.io/pypi/v/candlecraft)](https://pypi.org/project/candlecraft/)
[![CI](https://github.com/alfredalpino/Candlecraft/actions/workflows/ci.yml/badge.svg)](https://github.com/alfredalpino/Candlecraft/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Unified OHLCV fetching for **crypto**, **forex**, and **equities** — one Python API, multiple data providers, packaged technical indicators.

> **Stable beta** — used in production market-making workflows at 3poch Labs. Powers data for [MarketMakingMegaMachine](https://github.com/alfredalpino/MarketMakingMegaMachine).

## Install

```bash
pip install candlecraft
```

## 30-second example

```python
from candlecraft import fetch_ohlcv, load_indicator

candles = fetch_ohlcv("BTCUSDT", "1h", limit=24)
rsi = load_indicator("rsi")(candles)

print(f"Latest close: {candles[-1].close}")
print(f"Latest RSI: {rsi[-1]['rsi']}")
```

## Features

- Single `fetch_ohlcv()` for crypto, forex, and equities
- Auto provider selection (Binance for crypto, Twelve Data for forex/equity)
- Typed `OHLCV` dataclass with validation
- Rate-limit handling (`raise` or `sleep` strategies)
- 10 technical indicators included in the package (`pip install` works)

## Providers

| Provider | Asset classes | API keys |
|----------|---------------|----------|
| Binance | Crypto | Optional (public API supported) |
| Twelve Data | Crypto, Forex, Equity | `TWELVEDATA_SECRET` required |

```python
from candlecraft import Provider, fetch_ohlcv

candles = fetch_ohlcv("EUR/USD", "1d", provider=Provider.TWELVEDATA, limit=30)
```

## Indicators

```python
from candlecraft import list_indicators, load_indicator

print(list_indicators())
# ['adx', 'atr', 'bollinger', 'ema', 'macd', 'obv', 'rsi', 'sma', 'stochastic', 'vwap']

macd = load_indicator("macd")
result = macd(candles)
```

## CLI

```bash
git clone https://github.com/alfredalpino/Candlecraft.git
cd Candlecraft
pip install -e ".[dev]"

python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --limit 10 --indicator rsi
```

## Development

```bash
pip install -e ".[dev]"
pytest -m "not integration"    # unit tests (no API keys)
pytest -m integration          # live API tests (keys required)
ruff check candlecraft tests
```

## Documentation

- [Architecture](ARCHITECTURE.md)
- [API reference](docs/api.md)
- [CLI guide](docs/cli.md)
- [Indicators](INDICATORS_README.md)
- [Changelog](CHANGELOG.md)

## Related projects

- [MarketMakingMegaMachine](https://github.com/alfredalpino/MarketMakingMegaMachine) — Hyperliquid market-making platform ($58.9K live volume at 3poch Labs)

## License

MIT — see [LICENSE](LICENSE).
