Metadata-Version: 2.4
Name: trading-matrix-dashboard
Version: 2.0.1
Summary: Streamlit dashboard: live bid/ask, volume-spike radar, Telegram alerts and auto-trade
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: streamlit>=1.36
Requires-Dist: ccxt>=4.4
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: plotly
Requires-Dist: requests
Requires-Dist: streamlit-autorefresh
Requires-Dist: yfinance

# trading-matrix-dashboard

A Streamlit dashboard for BTC, ETH, Gold, Silver and Crude Oil with live bid/ask, market direction,
a volume-spike radar, support/resistance zones built from volume spikes, Telegram alerts and
optional webhook / broker auto-trading.

> **Not financial advice.** The dashboard shows reference levels and signals. It does not place
> stop-losses or take-profits for you. Always test in Paper mode first.

## Install and run

    pip install -U trading-matrix-dashboard
    trading-matrix

Extra options are passed to Streamlit, for example `trading-matrix --server.port 8502`.
You can also run `python -m trading_matrix`.

## Where to book a trade

Everything you need to decide *when* and *where* to trade is on the first tab, **Live Market Matrix**.

| What you need | Where to look | What it tells you |
|---|---|---|
| **Direction (trade bias)** | **Market View** at the very top | Overall direction plus the 15m and 1h direction. Trade with the bias, or be extra careful against it. |
| **Entry trigger** | **Strategy Signal** box, Telegram `BUY` / `SELL` alerts, webhook `action` | Support bounce, trendline breakout or resistance rejection, confirmed by the 10-candle delta. |
| **Price area to watch** | Banner under Market View and the **Spike Zone Tracker** table (`Range` column) | Where large volume traded before. Price near or inside a zone is where a reaction or a break is expected. |
| **Where it may go next / profit area** | **🎯 NEXT TARGET** row and the **If broken -> next zone** column | If the zone in front of price breaks, this is the next volume zone, a common place to book profit or re-evaluate. |
| **Confirmation that a zone broke** | **💥 BROKEN** status, red or green banner, Telegram `ZONE BROKEN` alert | Price has moved through the zone. The next zone becomes the target. |
| **Levels for the opposite scenario** | **Volume Spike Radar** -> `Next move` with the Resistance and Support levels | The nearest seller zone above and buyer zone below, useful for placing your own stop or exit. |
| **Execution details** | **Execution (Webhook / Broker)** tab, Trade log | Symbol, lot, price and signal reason for every order or paper order. |

### How to read the zone table

- In a **BEARISH** market the dashboard tracks **BUYER (support) zones below price**.
- In a **BULLISH** market it tracks **SELLER (resistance) zones above price**.
- In a **NEUTRAL** market it shows the nearest zones on both sides and sends no zone alerts.

| Status | Meaning |
|---|---|
| ⏳ AHEAD | Zone is further away than the near-zone distance. |
| 🎯 NEXT TARGET | The nearest zone price has not reached yet. |
| 🟠 NEAR | Price is within the near-zone distance (sidebar slider, default 0.30%). |
| 🔶 INSIDE | Price is inside the zone range. |
| 💥 BROKEN | Price has gone through the zone (below a buyer zone, or above a seller zone). |

### Example (bearish)

Buyer zones were logged at **99.00 - 99.80** and **97.00 - 97.60**, and the market is bearish.

1. Price at 100.00: status **NEAR**. Telegram: *"PRICE NEAR ZONE ... If it breaks, next zone 97.00 - 97.60"*.
2. Price at 99.40: status **INSIDE**. This is the area where buyers reacted before, so a bounce or a break can happen here.
3. Price at 98.80: status **BROKEN**. The next zone **97.00 - 97.60** is now the **NEXT TARGET**, a level where a short trade may be booked or reviewed.

A bullish market works the same way, mirrored: seller zones above price, a break upward, and the next seller zone as the target.

## Dashboard sections

- **Market View**: overall, last 15m and last 1h direction, with the reasons behind each score.
- **Live Bid / Ask**: bid, ask, mid, spread, order-book share and market direction.
- **Volume Spike Radar**: spikes above 2X, 3X, 4X or 5X the average of the last 200 candles (dropdown in the sidebar). Red candle = `seller`, green candle = `buyer`. Shows the top 10 and the "Next move" view.
- **Spike Zone Tracker**: support and resistance zones, status and next zone (see above).
- **KPIs and chart**: support, resistance, trendline, 20 and 50 EMA, spike markers, zone bands, bid/ask lines.

## Telegram alerts

Open the **Telegram Alerts Config** tab, enter the bot token and chat ID, and press the test button.
Alerts are sent for: new volume spikes, market direction changes, zone near / inside / broken,
volume crash, strategy BUY / SELL signals, and every trade or paper trade.
Each alert fires once per change, not on every refresh.

## Webhook and broker trading

Open the **Execution (Webhook / Broker)** tab.

1. Choose **Webhook**, **Direct broker API (ccxt)** or **Both**.
2. Set the **lot size** (saved separately for each asset) and the symbol.
3. For webhooks, paste the URL and, if needed, a secret (sent as `{secret}` and as the `X-Webhook-Secret` header).
4. Keep **Paper mode** on until you have tested. Paper mode logs what would be sent and sends nothing.
5. Press **Send test webhook** to check your receiver, then switch on **Enable Auto-Trade**.

Default payload (editable):

    {"action": "{action}", "symbol": "{symbol}", "lot": {lot}, "price": {price}, "timeframe": "{timeframe}", "signal": "{signal}", "time": "{time}"}

Placeholders: `{action}` `{symbol}` `{asset}` `{lot}` `{price}` `{bid}` `{ask}` `{timeframe}` `{signal}` `{time}` `{secret}`.
Valid JSON is sent as JSON, anything else as plain text. MT5 and Shark Exchange can be reached through a webhook bridge.

Each signal fires **once per candle, per side, per mode**, and is remembered across restarts.

## Files and settings

- Volume-spike log: `~/.trading_matrix/volume_spikes.json`
- Fired-signal memory: `~/.trading_matrix/executed_signals.json`
- Change the folder with the environment variable `TRADING_MATRIX_DATA`.
- Pre-fill the webhook fields with `TRADING_MATRIX_WEBHOOK_URL` and `TRADING_MATRIX_WEBHOOK_SECRET`.
- Telegram token, webhook secret and broker keys are kept in the browser session only and are not saved to disk.

## Good to know

- Spike scans, zones and alerts only run **while the dashboard is open** in a browser tab.
- Auto-trade only watches the **asset selected in the sidebar**.
- Yahoo Finance data (fallback for commodities) can be delayed and may have no bid/ask.
- "Broken" is judged on the live mid price at each refresh, not on a confirmed candle close.
- If the `trading-matrix` command is not found, run `python3 -m trading_matrix` or install with `pipx`.
