Mirror

Copy-trade a Discord signal channel on Hyperliquid, including the trader's candle-close stops, from your own computer.

Disclaimer. This is a personal project, not financial advice. Automated trading can lose money fast, alerts can be misread, and nothing here is guaranteed. Start in paper mode, then use small amounts you can afford to lose. You are responsible for every trade your copy places.

---

Why I built this

I follow a trader who posts calls in a Discord channel. A typical alert looks like this:

Longing BTC at CMP. TPs above, dca @ 83657, 1H close under 83217 for stops.

Two things made following him by hand hard:

1. Timing. He posts whenever he posts. If I'm asleep or in class, I miss the entry.
2. His stops aren't normal stop orders. "1H close under 83217" means: exit only if an hourly candle closes below 83217. A quick wick below it doesn't count. Exchanges can't place that kind of stop, so you either watch every candle yourself or use a normal stop that gets hit by wicks he survives.

Mirror handles both. It reads the channel, enters the same trade with a size based on how much I'm willing to lose, checks every candle close against his level, and follows his follow-up messages (closes, partial profits, stop moves).

What it does

• Reads alerts from a Discord channel you already have open in Chrome, through a small read-only extension. You can also paste alerts or send them from Telegram.
• Understands the message: coin, long/short, market or limit entry, DCA levels, and the stop (candle-close or a plain price). Closes, partials, "TP hit", stop moves and "cancel the DCA" are understood too. Anything unclear goes to a review queue instead of being guessed.
• Sizes by risk, not leverage: "if his stop hits, I lose 1% of my account". It then picks the highest safe leverage.
• Places the orders on Hyperliquid: market entry, DCA limit orders, and a far backup stop on the exchange in case your computer is off.
• Checks candle closes (1H, 4H, 12H, daily…) at the exact UTC close and exits only when the close is past his level.
• Keeps itself honest: every 10 seconds it compares its records with the exchange, resizes the backup stop after fills, and notices if a stop was hit.
• Dashboard at http://127.0.0.1:8420 with a price rail for each trade, a countdown to the next candle close, history with R-multiples, and one-click pause / flatten.
• Telegram alerts (optional) with Approve / Reject buttons for anything in review.
• Paper, Testnet and Live modes. Paper uses real Hyperliquid prices with simulated fills and needs no keys at all.

How it works

flowchart LR
    D["Discord channel<br/>open in Chrome"] -->|"Mirror Bridge<br/>(read-only extension)"| API["Mirror<br/>127.0.0.1:8420"]
    T["Paste box · Telegram /signal"] --> API
    API --> P["Parser<br/>text → instruction"]
    P --> E["Engine<br/>sizing · orders · stops"]
    E -->|"API wallet<br/>(can't withdraw)"| HL[("Hyperliquid")]
    C["Candle closes<br/>Binance / Hyperliquid"] --> E
    E --> UI["Dashboard · Telegram"]

Loading

1. The bridge notices a new message in the channel and sends its text to Mirror on your own computer (never to any other server).
2. The parser turns the text into an instruction, for example open BTC long at market, DCA at 83657, exit on a 1H close below 83217. It uses plain, tested rules, not AI.
3. The engine checks the instruction against your limits, sizes it, and places the orders.
4. At every candle close it reads the close price and decides: held or exit.
5. Follow-up messages (Closing BTC here, Securing 50%, Stops to BE) are matched to the right open trade and executed.

There's a full walkthrough with the maths in docs/HOW_IT_WORKS.md.

Screenshots

Signals: everything received and how it was understood	Review: unclear messages wait for you
History: results in dollars and R	Setup: guided connection + health check

Quick start

You need Python 3.11+ and Google Chrome. A Hyperliquid account is only needed for live trading.

git clone https://github.com/Aahil-Riyaz/hyperliquid-mirror.git
cd hyperliquid-mirror

• Windows: double-click start.bat. Keep the folder in a short path such as C:\Mirror.
• macOS / Linux: ./start.sh
• Docker: docker compose up -d, then open http://127.0.0.1:8420

The first run installs everything (about a minute), then your browser opens the dashboard in paper mode. Go to Signals, paste an alert, and watch it trade with simulated money.

Running from a OneDrive folder? start.bat automatically keeps your keys, database and Python packages in %LOCALAPPDATA%\Mirror so they're never uploaded to the cloud.

Setup

1. Connect the Discord channel

The bridge is a Chrome extension in the extension/ folder. It only reads messages that are already on your screen. It never posts, clicks, or touches your Discord login or token.

1. Open chrome://extensions, turn on Developer mode, click Load unpacked, and select the extension folder.
2. In Mirror, open Setup and copy the address and bridge token into the extension popup. Click Save, then Test.
3. Open discord.com in Chrome, go to the alerts channel, and click Watch this channel in the extension.
4. Back in Setup, click Lock to channel so no other channel can ever trigger a trade.
5. Keep that tab open and scrolled to the newest message. In chrome://settings/performance, add discord.com to Always keep these sites active.

The next time an alert is posted, Setup shows Last message captured. Check that it matches Discord word for word.

Discord's terms don't allow unofficial client add-ons. The bridge only reads the page and never acts on your account, but using it is your own decision. Without it, you can paste alerts or use Telegram /signal.

2. Connect Hyperliquid (for testnet or live)

Mirror uses an API wallet: it can trade, but it can never withdraw your funds.

1. On app.hyperliquid.xyz/API, generate an API wallet, authorize it, and copy its private key (it's only shown once).
2. Recommended: create a sub-account just for Mirror. Hyperliquid merges positions per coin, so your manual trades would otherwise mix with Mirror's.
3. In Setup → Connect Hyperliquid, paste your main address, the API wallet key, and the sub-account address. Mirror refuses a key that belongs to your main wallet.
4. When the health check shows API wallet approved and Account has funds, switch to Live (you type GO LIVE to confirm). Start with 0.25–0.5% risk per trade.

Keys are stored only on your computer (in data/.env, or %LOCALAPPDATA%\Mirror\data from OneDrive). They never appear in the UI or logs.

3. Telegram (optional)

Create a bot with @BotFather, paste the token in Setup, and send /start to your bot to get your chat id. Commands: /status, /pause, /resume, /close BTC 50, /flatten confirm, /signal <alert text>. Live mode can't be switched on from Telegram.

How alerts are understood

Message	What Mirror does
Longing BTC at CMP … dca @ 83657, 1H close under 83217 for stops	Market entry, DCA limit at 83657, exit if a 1H candle closes below 83217
Going long AXS here at CMP … SL 12H close under 0.992	Same, checked at 00:00 and 12:00 UTC
Shorting ETH … 4H close over 4250 for stops	Short, exit if a 4H candle closes above 4250
… SL 21.4 (no timeframe)	A real stop order on the exchange
Closing BTC here, Closing the rest	Close the whole position
Securing 50%, Taking some profits, Closing half	Close that % (or your default, 33%)
TP1 hit	Take your default partial (configurable)
Moving stops to BE, SL to 1.10	Move the candle-close stop. A DCA now past the stop is cancelled
Cancel the dca	Cancel the DCA order
Stopped out on BTC	Close if still open
BTC looking strong	Nothing (commentary)
If we lose 83k I'll close, a vague close with two trades open, a 20-minute-old entry	Review queue, never a guess

Examples live in samples/alerts.md, and the tests check every one of them.

Position sizing and stops, with real numbers

Take Going long AXS here at CMP … dca @ 1.067, SL 12H close under 0.992 with price at 1.1685, a $1,000 account and 1% risk:

• Risk budget: 1% of $1,000 = $10 if his stop is hit.
• Expected exit: candle-close stops often exit a bit past the level, so Mirror assumes 0.992 − 25% of the stop distance = 0.9479.
• Size: split 50/50 between entry (1.1685) and DCA (1.067), about $66 of AXS loses $10 at 0.9479. That's roughly 28.4 AXS now and 31.1 AXS at the DCA.
• Backup stop: one stop-distance past his level → 0.8155, placed on the exchange.
• Leverage: the highest value where liquidation stays safely beyond 0.8155 in every state (entry only, entry plus DCA). For AXS that's 2x.

With the backup stop, the worst case if everything fails is about $18 (1.8× the risk budget).

Safety features

• Paper → Testnet → Live, with a typed GO LIVE confirmation.
• Pause entries (exits keep working) and Flatten (close everything) buttons.
• Auto-pause after a 5% daily loss or three exchange errors in a row.
• Limits on open trades (5) and total open risk (5%).
• Old alerts (3+ minutes) or large price moves since the alert (1.5%+) go to review.
• Unique client order ids. After a timeout, Mirror asks the exchange what happened instead of resending.
• After a restart, it checks every candle close it missed, in order, and exits late if needed.
• The dashboard only listens on 127.0.0.1, rejects requests from other websites, and can be password-protected.

Make it yours

Mirror was built around one trader's format, but it's meant to be adapted. See docs/CUSTOMIZING.md for:

• changing risk, leverage, stop and automation settings,
• following a different trader or channel,
• teaching the parser new wording, or a completely different alert format,
• sending alerts from your own bot or webhook instead of Discord,
• adding another exchange.

Project structure

mirror/
  parser.py        text → instruction (regex grammar, tested)
  sizing.py        risk-based size, backup stop, leverage/liquidation maths
  engine.py        trade lifecycle, candle-close stops, reconciliation
  exchange/        paper simulator + Hyperliquid adapter (official SDK)
  marketdata.py    prices and candle closes (Hyperliquid, Binance)
  api.py           local HTTP API used by the dashboard and the bridge
  notify.py        Telegram notifications and commands
  timeframes.py    UTC candle boundaries
  config.py        settings and local secrets
  db.py            SQLite storage
web/               dashboard (plain HTML/CSS/JS, no build step)
extension/         Mirror Bridge Chrome extension
samples/alerts.md  real alert examples the parser must understand
tests/             pytest suite: parser, sizing, engine end-to-end on paper
docs/              how it works, customizing guide, screenshots

Running the tests

python -m pip install -r requirements-dev.txt
python -m pytest

The suite covers the parser (including every line of samples/alerts.md), the sizing maths against hand-checked numbers, candle-boundary timing, and full trade lifecycles on the paper exchange: entry, DCA fill, backup-stop resize, candle-close exit, partials, edits and restarts.

FAQ

Does it need my Discord password or token? No. The extension reads the page you already have open.

What if my computer turns off? The backup stop on the exchange still protects you. When Mirror starts again it checks the candle closes it missed and exits if one was past the level.

Does it cost anything? No. You only pay Hyperliquid's trading fees and funding. No paid APIs or AI services.

Why rules instead of AI to read the messages? Money is involved. Rules behave the same way every time and can be tested line by line. When a message doesn't fit, Mirror asks you instead of guessing.

Can it run on a server 24/7? The engine can (Docker is included). The Discord bridge needs a Chrome window with Discord open, so use a machine that stays on, or send alerts from your own bot to the local API (see the customizing guide).

Can I sell this as a signal-copying service? Don't redistribute someone else's alerts without permission. Copy-trading services can also be regulated where you live.

Tech stack

Python 3.11+ · FastAPI · SQLite · hyperliquid-python-sdk · vanilla JS dashboard · Chrome extension (Manifest V3) · pytest

License

MIT. Use it, change it, learn from it. No warranty.