# Candle Reader - Testing Instructions

## Overview

`read_candles.py` is a test script that reads 1m candle data from the PostgreSQL database running in Docker on the Synology NAS (`20.20.20.20`).

## Prerequisites

1. **Python 3.11+** with `psycopg2-binary` installed:
   ```bash
   pip install psycopg2-binary
   ```

2. **Network access** to the NAS at `20.20.20.20` on port `5433`.

3. **Docker containers running** on the NAS:
   ```bash
   docker-compose up -d
   ```

## Configuration

Connection parameters are loaded from `testing/.env` (git-ignored). Copy from the example if needed:

```bash
cp testing/.env.example testing/.env
```

Edit `testing/.env` to match your NAS setup:

| Variable | Default | Description |
|----------|---------|-------------|
| `PG_HOST` | `20.20.20.20` | NAS IP address |
| `PG_PORT` | `5433` | PostgreSQL port (host) |
| `PG_DB` | `hyper` | Database name |
| `PG_USER` | `hyper` | Database user |
| `PG_PASSWORD` | `kaqpaaoi0` | Database password |
| `PG_TIMEOUT` | `10` | Connection timeout (seconds) |

## Usage

```bash
python testing/read_candles.py [OPTIONS] [--SYMBOL ...]
```

### Options

| Flag | Description |
|------|-------------|
| `--all` | List last candles for **all** symbols (411+ tables) |
| `--timestamp DD-MM-YY` | List nearest candle to the given date (start of day) |
| `--timestamp "DD-MM-YY HH:mm"` | List nearest candle to the given date and time |
| `-h, --help` | Show help message |

### Dynamic Symbol Flags

Any `--SYMBOL` flag filters to that specific symbol(s). Multiple symbols can be combined.

| Flag | Description |
|------|-------------|
| `--BTC` | Only BTC candles |
| `--BTC --ETH` | BTC and ETH candles only |
| `--xyz:GOLD` | Only xyz:GOLD candles (colon symbols supported) |
| `--xyz:BRENTOIL` | Only xyz:BRENTOIL candles |

### Default Behavior

With no flags, the script reads the last 1m candle for 12 default symbols:
`BNB`, `ETH`, `xyz:GOLD`, `xyz:SILVER`, `SUI`, `xyz:BRENTOIL`, `mkts:USTECH`, `xyz:CL`, `xyz:XYZ100`, `HYPE`, `SOL`, `BTC`

Symbols containing colons (e.g., `xyz:GOLD`) are automatically sanitized to PostgreSQL-safe table names (e.g., `xyz_GOLD_1m`).

## Examples

### 1. Last candles for 12 default symbols
```bash
python testing/read_candles.py
```

### 2. Last candles for all symbols
```bash
python testing/read_candles.py --all
```

### 3. Last candle for a single symbol
```bash
python testing/read_candles.py --BTC
```

### 4. Last candles for multiple symbols
```bash
python testing/read_candles.py --BTC --ETH --SOL
```

### 5. Last candles for colon-containing symbols
```bash
python testing/read_candles.py --xyz:GOLD --xyz:BRENTOIL
```

### 5. Nearest candle to a date (start of day)
```bash
python testing/read_candles.py --BTC --timestamp 05-08-26
```

### 6. Nearest candle to a date and time
```bash
python testing/read_candles.py --BTC --timestamp "05-08-26 13:30"
```

### 7. Combine --all with --timestamp
```bash
python testing/read_candles.py --all --timestamp "05-08-26 13:15"
```

## Output Format

```
======================================================================
Last 1m Candles - default 12 symbols
======================================================================
  BTC             | 2026-08-05 13:15:00 | 1785935700000 | O=64116.00 H=64116.00 L=64096.00 C=64104.00 | Vol=2.19
  ETH             | 2026-08-05 13:15:00 | 1785935700000 | O=1868.00 H=1868.00 L=1867.50 C=1867.60 | Vol=32.26
  ...
======================================================================
```

Columns: `Symbol | datetime_utc | timestamp_ms | O(open) H(high) L(low) C(close) | Vol(volume)`

## Troubleshooting

### Connection refused
- Ensure Docker containers are running: `docker-compose up -d`
- Check NAS firewall allows port 5433
- Verify `PG_HOST` in `testing/.env`

### No data for a symbol
- The symbol may not have a table (e.g., `MATIC_1m` may not exist)
- Use `--all` to see which tables are available
- Ensure the symbol name matches exactly (case-sensitive, colons included)

### Invalid timestamp format
- Use `DD-MM-YY` (e.g., `05-08-26`)
- Or `"DD-MM-YY HH:mm"` (e.g., `"05-08-26 13:30"`)