Metadata-Version: 2.4
Name: algochains
Version: 1.0b2
Summary: AlgoChains - Quant backtesting library for algorithmic trading
Author: AlgoChains Team
License: MIT
Project-URL: Homepage, https://algochains.ai
Keywords: trading,backtesting,quantitative,finance,backtrader,algo trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: backtrader==1.9.78.123
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy<2
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: mplfinance==0.12.7a0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: pytz>=2024.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# AlgoChains

A Python quant backtesting library built on [Backtrader](https://www.backtrader.com/), with hosted historical data for Forex, Stocks, and Crypto.

---

## Install

```bash
python3 -m venv venv && source venv/bin/activate
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ algochains==1.0.0bX
```

Verify:
```bash
python -c "import algochains; print(algochains.__version__)"
```

Update:
```bash
pip install --upgrade algochains
```

---

## Quickstart

```python
from dotenv import load_dotenv
import os
from algochains import user_query
import backtrader as bt

load_dotenv()

class RSI_Strategy(bt.Strategy):
    params = (('symbol', 'UNKNOWN'), ('warmup', 50))

    def __init__(self):
        self.rsi   = bt.indicators.RSI(self.data.close, period=14)
        self.order = None

    def next(self):
        if self.order:
            return
        if not self.position:
            if self.rsi[0] < 30:
                size = int((self.broker.getcash() * 0.95) / self.data.close[0])
                self.order = self.buy(size=size)
        else:
            if self.rsi[0] > 70:
                self.order = self.sell(size=self.position.size)

user_query(RSI_Strategy, 10000, "BTC-USD", "2025-01-01", "2025-12-31", "Crypto", "1h",
           api_key=os.getenv("ALGOCHAINS_API_KEY"))
```

`.env` file in your project root:
```
ALGOCHAINS_API_KEY=your_key_here
```

---

## Supported markets

| database | examples | resolutions |
|---|---|---|
| `"Forex"` | `"EUR-USD"`, `"GBP-JPY"` | `1m` – `1d` |
| `"Stocks"` | `"AAPL"`, `"TSLA"` | `1m` – `1d` |
| `"Crypto"` | `"BTC-USD"`, `"ETH-USD"` | `1m` – `1d` |

---

## Documentation

Full docs live in [`docs/`](docs/README.md):

| | |
|---|---|
| [Installation](docs/installation.md) | Setup and updates |
| [Core Concepts](docs/core-concepts.md) | Warmup, asset classes, commissions, order flow |
| [Strategy API](docs/strategy-api.md) | How to write a strategy, sizing, multi-asset |
| [Backtesting](docs/backtesting.md) | `user_query`, optimization, `research_query` |
| [Data Feeds](docs/data-feeds.md) | Historical data, resampling |
| [Troubleshooting](docs/troubleshooting.md) | Common errors and fixes |
| [LLM Context](docs/llm-context.md) | Paste into your AI assistant for best results |

---

## Examples

Ready-to-run strategies in [`examples/`](examples/):

| File | Description |
|---|---|
| [`simple_sma_cross.py`](examples/simple_sma_cross.py) | SMA crossover on Stocks |
| [`rsi_strategy.py`](examples/rsi_strategy.py) | RSI mean-reversion on Forex |
| [`walkforward_optuna.py`](examples/walkforward_optuna.py) | Parameter optimization with Optuna |

---

## Using with an AI assistant

If you are using an AI assistant (Claude, ChatGPT, Copilot, Cursor, etc.), start your session with:

> "Get familiar with the AlgoChains library by reading llms.txt before we start working."

Your agent will read [`llms.txt`](llms.txt) in your conversation. It contains the full API reference in a compact format and will give your AI assistant everything it needs to write and debug AlgoChains strategies correctly without guessing.

---

## Project structure

```
algochains-core/
├── docs/            full documentation
├── examples/        runnable strategy examples
├── src/algochains/  library source
├── llms.txt         AI assistant reference
├── pyproject.toml
└── README.md
```

---

## License

MIT — see [algochains.ai](https://algochains.ai) for terms of service.
