# Candle Management Reference

This reference covers candle import and management operations in Jesse.

## Data Requirements

Historical candle data is required for backtesting strategies. Import data for all route exchanges, symbols, and timeframes before running backtests.

## Import Process

DO NOT pre-check candle availability before running a backtest. Run the
backtest first and only import on a missing-data error. Pre-checking with
`get_existing_candles()` wastes time and tokens, and the backtest engine
itself is the authoritative source of whether the required data is present
for a given route, timeframe, and date range.

Correct flow:

1. Run the backtest (see `jesse://backtest_management`).
2. If — and only if — it fails with a missing-candle error, call
   `import_candles()` starting ~2 months before the user's `start_date`.
3. Poll `get_candle_import_status(import_id)` until `"finished"`, then
   retry the backtest.
4. Use `get_existing_candles()` only for explicit user-driven inspection
   (e.g. "what data do I have?"), never as a pre-flight gate.

## Tool Reference

### get_existing_candles()

Checks what candle data is currently available in the database.

**Returns:** List of available candle datasets with exchange, symbol, timeframe, and date ranges.

### import_candles()

Imports historical candle data from exchanges.

**Parameters:**
- `exchange`: Exchange name (e.g., "Binance Perpetual Futures")
- `symbol`: Trading pair (e.g., "BTC-USDT")
- `start_date`: Start date in YYYY-MM-DD format
- `import_id` (optional): Import ID for retrying failed imports

**Supported Timeframes:**
1m, 3m, 5m, 15m, 30m, 45m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 1D, 3D, 1W, 1M

**Returns:** Import result with status and import ID

## Usage Examples

### Basic Import
```python
result = import_candles(
    exchange="Binance Spot",
    symbol="BTC-USDT",
    start_date="2024-01-01"
)
```

### Retry Failed Import
```python
# First attempt
result = import_candles(
    exchange="Binance Spot",
    symbol="ETH-USDT",
    start_date="2024-01-01"
)

# If failed, retry with same import_id
if result.get("status") != "success":
    import_id = result.get("import_id")
    retry_result = import_candles(
        exchange="Binance Spot",
        symbol="ETH-USDT",
        start_date="2024-01-01",
        import_id=import_id
    )
```

## Retry Behavior

When retrying imports with the same `import_id`:

- Previous events are automatically cleared
- Import resumes from the failure point
- Already-imported candles are skipped
- Progress monitoring starts fresh but continues efficiently
- WebSocket events are isolated per retry

## Success Response Format

```
"Successfully imported candles since '2024-01-01' until today (2.1 days imported, 1.2 days already existed in the database)."
```

The message shows both newly imported data and pre-existing data that was skipped.