Metadata-Version: 2.4
Name: zipfinam
Version: 0.2026.2.25
Summary: Ziplime data source add-on for Russian market (Finam/MOEX) via gRPC
Project-URL: Homepage, https://github.com/arbuzovv/zipfinam
Project-URL: Repository, https://github.com/arbuzovv/zipfinam
License: MIT
Keywords: algotrading,backtesting,finam,grpc,moex,russia,trading,ziplime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: <4.0,>=3.12
Requires-Dist: aiocache>=0.12.0
Requires-Dist: asyncclick>=8.0.0
Requires-Dist: googleapis-common-protos<2.0.0,>=1.65.0
Requires-Dist: grpcio<2.0.0,>=1.67.0
Requires-Dist: polars>=1.0.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: ziplime<2.0.0,>=1.11.11
Description-Content-Type: text/markdown

# zipFinam

**zipFinam** — дополнение к библиотеке [ziplime](https://github.com/Limex-com/ziplime) для работы с российским рынком (MOEX) через gRPC API.

## Установка

```bash
pip install zipfinam
```

---

## Первый бэктест: пошаговое руководство

Все готовые файлы находятся в папке [`quickstart/`](quickstart/).

```
quickstart/
├── .env.example            # шаблон конфигурации
├── step1_ingest_assets.py  # загрузка списка инструментов
├── step2_ingest_data.py    # загрузка исторических данных
├── algo.py                 # торговый алгоритм (можно редактировать)
└── step3_run_backtest.py   # запуск бэктеста
```

### Шаг 0. Настройте доступ к API

Скопируйте шаблон и заполните ваши данные:

```bash
cd quickstart
cp .env.example .env
```

Откройте `.env` и укажите токен и адрес сервера:

```
GRPC_TOKEN=ваш_токен_здесь
GRPC_SERVER_URL=api.finam.ru:443
```

Загрузите переменные в окружение:

```bash
export $(cat .env | xargs)
```

---

### Шаг 1. Загрузите список инструментов

> Выполняется один раз. Повторять только при обновлении списка доступных инструментов.

```bash
python step1_ingest_assets.py
```

---

### Шаг 2. Загрузите исторические данные

По умолчанию загружаются **SBER, LKOH, GAZP** за **2024 год** с дневной частотой.

```bash
python step2_ingest_data.py
```

Данные сохранятся в `~/.ziplime/data/`. Отредактируйте `step2_ingest_data.py` чтобы изменить символы или период.

---

### Шаг 3. Запустите бэктест

```bash
python step3_run_backtest.py
```

Алгоритм из [`algo.py`](quickstart/algo.py) — равновзвешенный портфель: каждой из трёх акций выделяется по 1/3 капитала, ребалансировка ежедневно.

Результат выводится в виде таблицы с метриками по дням.

---

### Что менять, чтобы адаптировать под себя

| Что хочу изменить              | Где менять                    |
|--------------------------------|-------------------------------|
| Список акций                   | `SYMBOLS` в `step2_ingest_data.py` и `algo.py` |
| Период бэктеста                | `start_date` / `end_date` в `step2_ingest_data.py` и `step3_run_backtest.py` |
| Стартовый капитал              | `total_cash` в `step3_run_backtest.py` |
| Логику торговли                | `algo.py`                     |

---

## Конфигурация

| Переменная окружения   | Описание                           | Обязательная |
|------------------------|------------------------------------|:------------:|
| `GRPC_TOKEN`           | Токен авторизации gRPC API         | Да           |
| `GRPC_SERVER_URL`      | Адрес gRPC сервера (`host:port`)   | Да           |
| `GRPC_MAXIMUM_THREADS` | Макс. число параллельных запросов  | Нет          |

## Поддерживаемые таймфреймы

| Частота  | Передавайте в `data_frequency`    |
|----------|-----------------------------------|
| 1 минута | `datetime.timedelta(minutes=1)`   |
| 5 минут  | `datetime.timedelta(minutes=5)`   |
| 1 час    | `datetime.timedelta(hours=1)`     |
| 1 день   | `datetime.timedelta(days=1)`      |
| 1 неделя | `datetime.timedelta(weeks=1)`     |

## Требования

- Python >= 3.12
- [ziplime](https://github.com/Limex-com/ziplime) >= 1.11.11

## Лицензия

MIT
