hyper/testing/README.md

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:

   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:

   docker-compose up -d
   

Configuration

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

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

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

python testing/read_candles.py

2. Last candles for all symbols

python testing/read_candles.py --all

3. Last candle for a single symbol

python testing/read_candles.py --BTC

4. Last candles for multiple symbols

python testing/read_candles.py --BTC --ETH --SOL

5. Last candles for colon-containing symbols

python testing/read_candles.py --xyz:GOLD --xyz:BRENTOIL

5. Nearest candle to a date (start of day)

python testing/read_candles.py --BTC --timestamp 05-08-26

6. Nearest candle to a date and time

python testing/read_candles.py --BTC --timestamp "05-08-26 13:30"

7. Combine --all with --timestamp

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")