PyneReal

<p align="center"> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"></a> <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License: Apache-2.0"></a> </p> <p align="center"> <img src="docs/images/dashboard-desktop.png" alt="PyneReal dashboard" width="900"> </p>

Run your crypto trading strategy in real time without TradingView.

✨ Highlights

• 🤖 AI copilot — chat with your running strategies, inspect balances and positions across every exchange account, and set price alerts in plain language
• ⚡ Realtime PyneCore strategy runner — signal to exchange in under a second after candle confirmation
• 📊 Bitget, Hyperliquid, OKX, Binance, and Bybit supported
• 🔔 Webhook, Telegram, and draggable manual price alerts on the chart
• 💼 Exchange and account-level asset portfolios with reviewed internal transfers
• 📱 Full mobile dashboard

🤖 AI Copilot

<!-- TODO: record a 10-15s GIF of the AI chat setting a price trigger (red trigger line appearing on the chart), save it as docs/images/ai-chat.gif, then uncomment: <p align="center"> <img src="docs/images/ai-chat.gif" alt="PyneReal AI chat" width="900"> </p> -->

Ask the dashboard chat things like:

"Update the key events for each session"

"Set a take-profit alert on the BTC 1m session at 3% above entry"

The AI copilot can:

• inspect exchange assets and derivative positions — every configured account at once when you don't name one;
• set or remove persisted Manual Alert price triggers straight from chat;
• research and maintain a shared calendar for every active trading session;
• analyze repository files, running sessions, and public market information;
• send a finished result to Telegram when you ask for it.

And the unique part — your strategy can talk to the AI too. When an order fills, its ai instruction runs automatically:

strategy.entry(
    "Long 3",
    strategy.long,
    alert_message=f'{{"signal": "Long 3", "price": {close}}}',
    ai=f"Set the close2 and close3 manual alerts at {avgEntry * 1.003}",
)

All account tools are read-only — the AI never places or cancels orders, changes leverage, or mutates account state. See AI Setup & Details for configuration.

Requirements

• Python 3.11+ (3.14+ recommended)
• PyneCore strategy file under workdir/scripts
• Optional AI Copilot: an OpenAI account with Codex access

Supported Exchanges

Tested in realtime:

• [x] Bitget
• [x] Hyperliquid
• [x] OKX
• [x] Binance
• [x] Bybit

Supported Timeframes

• [x] 1m and higher
• [ ] Sub-minute timeframes are not supported

Install

git clone https://github.com/hackcatml/pynereal
cd pynereal
source setup.sh

Quick Start

Start the hub:

python data_service/main.py

Open the dashboard:

http://127.0.0.1:9001

The bundled fallback config creates a demo session for Bitget BTC/USDT Futures on the 1m timeframe when no sessions.json exists.

Then click Start in the session row.<br> The hub starts a dedicated runner_service subprocess for that session and writes its log under workdir/output/realtime/<session-id>/runner.log.<br> Use Logs to inspect the live runner output.<br> Use Open to view the chart.

The demo webhook server is optional:

python demo_webhook_server.py

You'll see webhook alerts when strategy.entry or strategy.close triggers.

Files and Directories

pynereal/
|-- data_service/                    Dashboard, chart API, session registry
|-- runner_service/                  Per-session strategy runner process
|-- pynecore/                        Bundled PyneCore runtime package
|-- modules/                         Optional helper modules for strategies
|-- docs/images/                     README screenshots
|-- workdir/
|   |-- scripts/                     Strategy scripts and helper modules
|   |   `-- demo/demo_1m.py          Runnable demo strategy
|   |-- config/
|   |   |-- realtime_trade.toml      Hub defaults and legacy config fallback
|   |   |-- sessions.json            Runtime session state saved by dashboard
|   |   `-- providers.toml           Provider credentials, e.g. ccxt API keys
|   |-- data/                        OHLCV files and per-symbol metadata
|   |   `-- cache/                   SQLite OHLCV cache
|   `-- output/realtime/             Per-session logs, plots, script hashes
|-- demo_webhook_server.py           Optional local webhook receiver
`-- setup.sh                         Local environment setup helper

Strategy Scripts

Place pynecore strategy files anywhere under workdir/scripts.<br> Subdirectories are supported, and the dashboard keeps the relative path:

workdir/scripts/demo/demo_1m.py -> demo/demo_1m.py
workdir/scripts/okx_mu/my_strategy_5m.py  -> okx_mu/my_strategy_5m.py

Only Python files that declare script.strategy(...) are shown in the script selector. Helper modules, lib, hidden directories, and __pycache__ are excluded.

Session Configuration

The dashboard is the recommended way to manage sessions. It persists them to:

workdir/config/sessions.json

On startup, session loading order is:

1. workdir/config/sessions.json
2. [[session]] entries in workdir/config/realtime_trade.toml
3. Legacy single [realtime] section in realtime_trade.toml

Example [[session]] fallback:

[hub]
host = "0.0.0.0"
port = 9001

[[session]]
provider = "ccxt"
exchange = "bitget"
symbol = "BTC/USDT:USDT"
timeframe = "1m"
history_since = "2026-06-10"
script_name = "demo/demo_1m.py"

[session.webhook]
enabled = false
url = ""
telegram_notification = false
telegram_token = ""
telegram_chat_id = ""

If [hub] is absent, the hub falls back to legacy [realtime].data_service_addr.

Historical Data

When a feed starts, PyneReal prepares an OHLCV file under workdir/data.

• If history_since is set, PyneReal backfills from that date.
• If history_since is empty and there is no existing cache/file, the default window is one month for 1m, and two months for other timeframes.
• If the SQLite cache already contains older bars, regenerated .ohlcv files may include the cached range.
• Recent closed candles are refreshed from the exchange before runner calculation so the strategy uses exchange-confirmed OHLCV where available.

Supported exchange behavior is handled per exchange.<br> For example, OKX, Binance, and Bybit zero-volume candles are hidden to match TradingView, while Bitget and Hyperliquid zero-volume candles remain visible.

Re-sync Historical Data

Open a session's Data settings to change its Data start (UTC) value after the session has been created. Saving a new date or datetime re-syncs the cached market data and regenerated OHLCV file from that boundary. Sessions that share the same exchange, symbol, and timeframe use the same feed, so the new boundary applies to all of them.

Running strategies on the affected feed are stopped before the data file is updated and restarted after it is ready. They then replay the new historical window to rebuild chart plots and strategy state. Webhook, Telegram, and AI notifications are suppressed during this re-sync replay so historical signals are not delivered as new alerts.

Running a Strategy

Prepare a PyneCore strategy file first. PyneReal runs PyneCore strategy scripts in realtime, so the file should declare script.strategy(...) and be valid in PyneCore before you start the runner.

1. Put the strategy under workdir/scripts.
2. Start the hub with python data_service/main.py.
3. Add or select the session in the dashboard.
4. Click Start.
5. Open the chart with Open.
6. Check runner output with Logs.

The runner can be started before opening a chart, or the chart can be opened before the runner starts. Source code, script title, and alert toggles are still available from the chart page.

Strategy Calculation Timing

When a new candle is confirmed, the runner updates the latest OHLCV data and then executes the strategy for that confirmed bar.<br> Strategy execution itself is normally fast; even complex strategies usually finish in less than 100 ms on a typical local machine.

If webhook alerts are configured, strategy.entry and strategy.close alerts are emitted immediately after the strategy calculation produces the signal.<br> End-to-end order arrival depends on webhook server latency, network latency, and the target exchange API, but in a normal low-latency setup the order usually reaches the exchange in less than one second after candle confirmation.

Webhook and Telegram

Webhook and Telegram settings are per session.

• Toggle Webhook or Telegram from the dashboard row or chart page.
• Use the gear button on the dashboard to set the webhook URL or Telegram token/chat id.
• Settings are persisted in sessions.json.
• Strategy alert_message is sent as the alert message payload.
• Realtime strategy alerts are currently emitted for strategy.entry and strategy.close. strategy.exit alerts are not supported yet.

Example:

strategy.entry(
    "Long 1",
    strategy.long,
    alert_message=f'{{"signal": "Long 1", "price": {close}}}',
)

If a session-specific Telegram token or chat id is empty, PyneReal falls back to the root .env values below. These values are used only when Telegram sending is enabled for strategy alerts, or when a manual alert is sent and the session does not define its own Telegram credentials.

BOT_TOKEN=your_bot_token
CHAT_ID=your_chat_id

Manual Alerts

Manual alerts let you send one-off webhook messages directly from the chart. They are useful when you want discretionary control in