> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ziplime.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Установка и запуск

> Установка движка, загрузка данных Мосбиржи и запуск бэктеста из командной строки или Python

## Установка

Для Ziplime нужен **Python 3.12+**. Российский рынок подключается библиотекой [zipfinam](https://github.com/arbuzovv/zipFinam): она ставит движок как зависимость и добавляет провайдер данных `finam`, календари Мосбиржи и исполнение заявок через Финам.

```bash theme={null}
pip install "zipfinam[all]"
```

Базовая установка движка — только ядро. Дополнительные возможности ставятся как pip extras:

| Extra | Что добавляет |
| - | - |
| `ziplime[mcp]` | Локальный MCP-сервер (`ziplime mcp`) |
| `ziplime[huggingface]` | Наборы данных на момент публикации с Hugging Face Hub (`hf://`) |
| `ziplime[options]` | Оценка опционов и греки |
| `ziplime[numba]` | Компилируемое векторное ядро |
| `ziplime[all]` | Всё перечисленное |
| `zipfinam[algopack]` | Клиент MOEX AlgoPack |
| `zipfinam[live]` | Исполнение заявок через Финам |

```bash theme={null}
pip install "ziplime[all]" "zipfinam[all]"
```

Для данных Финама нужен токен Finam Trade API из личного кабинета. Положите его в переменную окружения или в файл `.env` в рабочей папке:

```bash theme={null}
export GRPC_TOKEN=...      # токен Finam Trade API: котировки, справочник, лоты
```

## Быстрый старт

Порядок всегда один: сначала справочник инструментов, затем бары, затем запуск.

```bash theme={null}
ziplime providers                           # какие провайдеры данных доступны и настроены
ziplime ingest-assets -p finam              # один раз: справочник инструментов из Финама
ziplime ingest -p finam -c XMOS -b moex -s SBER@MISX,GAZP@MISX \
  --start-date 2019-01-01 --end-date 2025-12-31
```

```python theme={null}
# sma.py
from ziplime.domain.bar_data import BarData
from ziplime.finance.execution import MarketOrder
from ziplime.trading.trading_algorithm import TradingAlgorithm


async def initialize(context: TradingAlgorithm):
    context.stocks = [await context.symbol("SBER@MISX"), await context.symbol("GAZP@MISX")]
    context.fast, context.slow = 20, 50


async def handle_data(context: TradingAlgorithm, data: BarData):
    for stock in context.stocks:
        bars = await data.history(assets=[stock], fields=["close"], bar_count=context.slow)
        if len(bars) < context.slow:
            continue
        closes = bars["close"]
        target = 0.5 if closes[-context.fast:].mean() > closes.mean() else 0.0
        await context.order_target_percent(asset=stock, style=MarketOrder(), target=target)
```

```bash theme={null}
ziplime run -f sma.py -b moex -s SBER@MISX,GAZP@MISX -c XMOS --capital-base 1000000 \
  --start-date 2020-01-01 --end-date 2025-12-31
```

<Tip>
  Тикеры Мосбиржи пишите с кодом площадки: `SBER@MISX` для акций, `RTSX` — для срочного рынка. Для акций Мосбиржи передавайте календарь `-c XMOS`: по умолчанию CLI использует американский `XNYS`. Не называйте свои переменные `context.assets` — это имя занято движком.
</Tip>

## Командная строка

| Команда | Что делает |
| - | - |
| `ziplime providers` | Показывает провайдеры данных этой установки и какие из них настроены |
| `ziplime ingest-assets` | Загружает справочные данные в базу инструментов. Без этого ничего не работает |
| `ziplime ingest` | Загружает бары в именованный бандл |
| `ziplime bundles` | Показывает сохранённые бандлы и их версии |
| `ziplime clean` | Удаляет старые версии бандла |
| `ziplime run` | Запускает бэктест на бандле |
| `ziplime mcp` | Запускает локальный MCP-сервер — см. [«Работа с ИИ»](/language/introduction/local-mcp) |

Ошибки выводятся в stderr с подсказкой, что делать, а код возврата отражает результат. Параметры любой команды — по ключу `-h`.

### Значения `ziplime run` по умолчанию

| Параметр | По умолчанию | Значение |
| - | - | - |
| `--emission-rate` | `1d` | Как часто вызывается `handle_data`: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, … |
| `-c, --trading-calendar` | `XNYS` | Календарь, по которому идут часы симуляции. Для Мосбиржи — `XMOS` |
| `--capital-base` | `100000` | Начальный капитал в валюте портфеля |
| `--same-bar-execution / --next-bar-execution` | следующий бар | Исполнение на том же баре использует цену, которой рынок ещё не показал, поэтому включается явно |
| `--fill-price` | `close` | Поле бара, по которому исполняется заявка: `open`, `close`, `high`, `low` |
| `--commission-per-share` | `0.0` | Комиссия по акциям за одну бумагу |
| `--slippage-bps` | `5.0` | Фиксированное проскальзывание; исполнение также ограничено десятой частью объёма бара |
| `--max-leverage` | `1.0` | Ограничение плеча счёта |
| `--benchmark-symbol` | нет | Без бенчмарка доходность бенчмарка считается нулевой. Для Мосбиржи — например, `IMOEX@MISX` |
| `-o, --output` | нет | Куда записать таблицу результатов: `.csv` — в CSV, любое другое расширение — в pickle |

<Warning>
  CLI **не берёт комиссию**, пока вы не передадите `--commission-per-share`. Брокерская комиссия на Мосбирже обычно считается в процентах от оборота, поэтому для реалистичного результата задайте её через Python API: `equity_commission=PerDollar(cost=0.0004)`. Подробнее — в разделе [«Расходы и комиссии»](/language/writing-strategies/costs-and-commissions).
</Warning>

## Python API

`ziplime.core.run_simulation.run_simulation` — то, что вызывает CLI. Используйте его, когда нужны собственные источники данных, модели комиссий или файл конфигурации.

```python theme={null}
import asyncio
import datetime
from zoneinfo import ZoneInfo

from ziplime.assets.domain.asset_type import AssetType
from ziplime.assets.entities.asset_symbol import AssetSymbol
from ziplime.core.ingest_data import get_asset_service
from ziplime.core.run_simulation import run_simulation
from ziplime.finance.commission import PerDollar
from ziplime.utils.bundle_utils import get_bundle_service


async def main():
    tz = ZoneInfo("Europe/Moscow")
    start = datetime.datetime(2024, 1, 3, tzinfo=tz)
    end = datetime.datetime(2025, 12, 30, 23, 59, tzinfo=tz)

    asset_service = get_asset_service(clear_asset_db=False)
    assets = await asset_service.get_exchange_assets_by_symbols(
        symbols=[AssetSymbol(symbol=s, mic="MISX") for s in ["SBER", "GAZP"]],
        asset_type=AssetType.EQUITY,
    )
    market_data, missing = await get_bundle_service().load_bundle(
        bundle_name="moex", bundle_version=None,
        frequency=datetime.timedelta(days=1),
        start_date=start, end_date=end, assets=assets,
    )

    result = await run_simulation(
        start_date=start,
        end_date=end,
        trading_calendar="XMOS",
        emission_rate=datetime.timedelta(days=1),
        total_cash=1_000_000.0,
        market_data_source=market_data,
        custom_data_sources=[],
        algorithm_file="sma.py",
        stop_on_error=True,
        asset_service=asset_service,
        same_bar_execution=False,
        equity_commission=PerDollar(cost=0.0004),   # порядка 0,04% от оборота
    )
    print(result.perf.tail())


asyncio.run(main())
```

<Note>
  `run_simulation` по умолчанию использует `same_bar_execution=True` ради обратной совместимости — в отличие от CLI и MCP-сервера. Передайте `same_bar_execution=False`, чтобы заявки исполнялись на следующем баре.
</Note>

Полезные параметры:

| Параметр | По умолчанию | Значение |
| - | - | - |
| `config_file` | `None` | JSON-файл для класса конфигурации стратегии |
| `benchmark_asset_symbol` / `benchmark_returns` | `None` | Бенчмарк по тикеру (например, `"IMOEX@MISX"`) или ряд доходностей |
| `equity_commission`, `future_commission`, `bond_commission`, `option_commission` | см. [«Расходы и комиссии»](/language/writing-strategies/costs-and-commissions) | Модели комиссий по классам активов |
| `equity_slippage`, `future_slippage`, `bond_slippage`, `option_slippage` | значения движка | Модели проскальзывания по классам активов |
| `max_leverage` | `1.0` | Регистрирует ограничение плеча |
| `price_used_in_order_execution` | `"close"` | Поле цены для исполнения |
| `intraday_metrics` | `False` | Считать полный набор метрик на каждом внутридневном баре. Дорого; нужно только коду, который читает внутридневные пакеты |

`result.perf` — DataFrame pandas с одной строкой на сессию, включая всё, что записано через `context.record(...)`.

Готовые скрипты загрузки, бэктеста и реальной торговли для Мосбиржи лежат в [`examples`](https://github.com/arbuzovv/zipFinam/tree/main/examples) репозитория zipfinam.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.