PolyTrader HyperTrader - How to Run

Recommended VPS

- Ubuntu 22.04 or 24.04
- 1 to 2 CPU cores
- 2 GB RAM minimum
- Tokyo is the recommended low-latency VPS region for this bot because it is closest to Hyperliquid infrastructure in our setup.

Install on a fresh VPS

1. Unzip the customer package on your own computer.
2. Upload the bot folder to the VPS.
3. SSH into the VPS.
4. Run:

   cd /root/polytrader-hypertrader
   sudo bash install.sh

Windows upload option:

  Use WinSCP, connect with SFTP, host YOUR_VPS_IP, username root, then upload
  the bot folder contents into /root/polytrader-hypertrader on the VPS.

macOS or Linux upload option:

  cd /path/to/unzipped/customer-package
  ssh root@YOUR_VPS_IP "mkdir -p /root/polytrader-hypertrader"
  scp -r bot/* root@YOUR_VPS_IP:/root/polytrader-hypertrader/

Then SSH in:

  ssh root@YOUR_VPS_IP
  cd /root/polytrader-hypertrader
  sudo bash install.sh

5. Keep the dashboard private. Open it through an SSH tunnel:

   ssh -L 8090:127.0.0.1:8090 root@YOUR_VPS_IP

6. In your browser, open:

   http://127.0.0.1:8090

First dashboard setup

1. Open the guide first: setup-guide.html.
2. In the guide, click Open Hyperliquid and create the account from that page.
3. Deposit trading funds into Hyperliquid.
4. Create and approve a Hyperliquid API wallet.
5. Paste the public trading wallet address and API wallet key into the dashboard.
6. Click Check connection.
7. Open the Settings tab if you need to adjust sizing, arb, or referral unlock controls.
8. Choose one trading method.

Prediction Autopilot defaults

- Uses the account balance reported by Hyperliquid. There is no manual live
  balance setting.
- New installs use Balanced: at most 10% of usable balance before the dollar
  cap, a $100 starting trade cap, 10x BTC hedge leverage, and a 5% daily-loss
  pause. Existing installs keep their saved settings.
- The dashboard also provides Cautious and More trades presets. Presets are
  starting risk policies, not profitability claims or personal advice.
- New Autopilot entries use a fail-closed all-in estimated-cost gate for fees,
  executable depth, slippage, funding, and the active edge floor.
- Prediction Market Arb reads the account's current Hyperliquid spot cross rate
  and subtracts it as a conservative outcome close/settlement fee before either
  the taker or maker edge can qualify. If the fee endpoint is unavailable, it
  uses the documented tier-zero rate instead of assuming zero.
- Prediction Market Arb is a beta mode and now starts in dry run with a 10%
  balance share and a 10 bp minimum post-fee edge on new installs. Live paired
  legs count only after both fills are confirmed. Unmatched inventory is
  flattened immediately when possible and flagged for manual action if not.
- Can scale trade size as the account grows.
- "Add more to clear winners" applies only to trades opened before the
  all-in entry cost gate. Trades opened by this version keep their entry size.
- If the BTC hedge order at entry does not fill, the hedge is built on a
  later loop, up to the size the entry cost check already priced.
- Can cut a losing BTC hedge if the prediction side is already winning and the
  projected settlement profit remains positive.
- Can re-arm the hedge if BTC breaks back across the target after the hedge was
  cut.
- Counts each trade's P&L from its own fills, fees and funding, so deposits,
  withdrawals and trades in other coins are not counted.
- Needs Hyperliquid's Unified Account mode (or USDC in both the spot and perp
  balances): predictions are bought with spot USDC, which also margins the
  BTC hedge. Check connection shows the account mode.

Expiry safety net

The dashboard checks every minute for a BTC hedge that Autopilot recorded and
that is still open after its market expired while Autopilot is not running
(90 seconds after expiry), or in any case 10 minutes after expiry. It closes
that hedge with one reduce-only order no larger than the recorded hedge, and
logs it in the event list. To run the same check by hand:

  cd /opt/polytrader-hypertrader
  .venv/bin/python expiry_guard.py --once

Set DH_EXPIRY_GUARD=0 in the dashboard service environment to turn it off.

Service commands

Dashboard:

  sudo systemctl status polytrader-hypertrader-dashboard
  sudo systemctl restart polytrader-hypertrader-dashboard

Prediction Autopilot:

  sudo systemctl start polytrader-hypertrader-autopilot
  sudo systemctl stop polytrader-hypertrader-autopilot
  sudo journalctl -u polytrader-hypertrader-autopilot -f

Prediction Market Arb:

  sudo systemctl start polytrader-hypertrader-arb
  sudo systemctl stop polytrader-hypertrader-arb
  sudo journalctl -u polytrader-hypertrader-arb -f

Dry-run arb test

This scans markets without placing orders:

  cd /opt/polytrader-hypertrader
  ARB_DRY_RUN=1 ARB_RUN_SECONDS=15 ARB_MAKER_ENABLED=0 ARB_TAKER_ENABLED=1 .venv/bin/python arb_bot_v2.py

Updating the bot

Do not delete the existing install folder. The saved dashboard connection,
strategy settings, bot state, and logs live on the VPS and should stay there.

Linux VPS update:

1. Download and unzip the newest customer package on your own computer.
2. Upload the new bot folder contents over the existing VPS folder:

   scp -r bot/* root@YOUR_VPS_IP:/root/polytrader-hypertrader/

   Windows users can do the same with WinSCP by uploading the new bot folder
   contents into /root/polytrader-hypertrader and choosing overwrite when asked.

3. SSH into the VPS and run the updater:

   ssh root@YOUR_VPS_IP
   cd /root/polytrader-hypertrader
   sudo bash update.sh

You do not need to stop the bot first. The updater refreshes the program files,
dashboard files, dependencies, and systemd service files. If Prediction
Autopilot or Prediction Market Arb was already running, it restarts that
service so it uses the new code.
It does not overwrite config.json, customer-settings.conf, dh_bot_state.json,
arb_state.json, or event logs in /opt/polytrader-hypertrader.

4. Open the dashboard and confirm the bot is connected:

   http://127.0.0.1:8090

5. If a method was running before the update, confirm it is still running in
   the dashboard. If it is not, start it again from the dashboard. Only run one
   method at a time.

Windows local update:

1. Unzip the newest customer package.
2. Run install.bat again from the new bot folder.
3. It refreshes the program files inside %USERPROFILE%\PolyTraderHyperTrader
   without deleting the saved dashboard config.

macOS local update:

1. Unzip the newest customer package.
2. In Terminal, run:

   cd bot
   chmod +x install_macos.sh start_dashboard.sh
   ./install_macos.sh

3. It refreshes the program files inside ~/PolyTraderHyperTrader without
   deleting the saved dashboard config.

Emergency stop

Create an empty file named STOP-DH-BOT in the install folder and Prediction
Autopilot exits cleanly on its next loop:

  touch /opt/polytrader-hypertrader/STOP-DH-BOT

This does not close open positions. Remove the file, then start the method
again from the dashboard to resume.

Important

- Only run one trading method at a time.
- Autopilot trades only the BTC daily market. Manual positions in the ETH,
  SOL or HYPE daily markets on the same account are ignored, but any BTC
  perp position on the account is treated as the bot's hedge.
- The dashboard mode lock is there to stop two strategies from using the same balance.
- Normal strategy settings can be changed from the dashboard Settings tab.
- Do not paste seed phrases or main wallet private keys anywhere.

Running a second bot on the same VPS

Advanced users on v3.0.5 or newer can run a second HyperTrader instance on the
same VPS for a different Hyperliquid account. Do not use the same Hyperliquid
account or API wallet in both dashboards.

The second instance needs its own install name, app folder, dashboard port, and
systemd services. Example for a second AI/recycle test instance:

  cd /root/polytrader-hypertrader-ai
  sudo HYPERTRADER_INSTANCE=polytrader-hypertrader-ai HYPERARB_PORT=8091 bash install.sh

Open the second dashboard with a different local tunnel:

  ssh -L 8091:127.0.0.1:8091 root@YOUR_VPS_IP

Then open:

  http://127.0.0.1:8091

The normal first dashboard stays on:

  http://127.0.0.1:8090

Updating the second instance later uses the same instance values:

  cd /root/polytrader-hypertrader-ai
  sudo HYPERTRADER_INSTANCE=polytrader-hypertrader-ai HYPERARB_PORT=8091 bash update.sh

The two dashboards have separate saved keys, state, settings, and logs because
they install into different /opt folders.

Windows local install

1. Install Python 3.11 or newer from python.org.
2. Open the bot folder.
3. Double-click install.bat.
4. Double-click start_dashboard.bat.
5. Open http://127.0.0.1:8090.

macOS local install

1. Install Python 3.11 or newer.
2. Open Terminal.
3. Run:

   cd bot
   chmod +x install_macos.sh start_dashboard.sh
   ./install_macos.sh

4. Start later with:

   ~/PolyTraderHyperTrader/start_dashboard.sh

Local Windows/macOS installs are mainly for testing or learning. For 24/7 trading, use the Linux VPS install.
