TRENCHLIGHT + BTC PREDICTION MACHINE + TRADING BOT: SETUP GUIDE FOR macOS
===========================================================================

This kit has two parts:

  1-Trenchlight   the whole Trenchlight site with the terminal. It runs on
                  your computer at http://localhost:8787/trenchlight. Tabs:
                    - Solana and Robinhood Chain: memecoin feeds;
                    - BTC Prediction Machine: the PULSE terminal with the
                      live Polymarket "Bitcoin Up or Down" 5 and 15-minute
                      rounds, the forecast and the CALLS (what to buy, at
                      what price and how much);
                    - Course: 15 lessons on the 15 / 5-minute rounds;
                    - Trading bot: this guide with pictures, and what every
                      setting means;
                    - Smart traders: Polymarket wallets that look informed
                      rather than lucky.
  2-polybot       the bot. It listens to the terminal's calls and at once
                  buys the same on YOUR Polymarket account. Without the bot
                  the site buys nothing; it only shows.

How it works: several times a second the terminal compares its forecast
with Polymarket's prices. When it sees value, it issues a call, for example
"DOWN @ 31¢ · $14". Within a fraction of a second the bot sends the same
purchase to Polymarket. When the round closes, a win lands in your balance
by itself (auto-redeem). The bot follows the rounds you tick in the CALLS
box: 5-minute, 15-minute or both (we run it on the 5-minute rounds).

What you need: a Mac or a Windows PC that can stay on, an internet
connection, Node.js (free, step 1), a MetaMask wallet and a Polymarket
account with some USDC (step 4). About 20 minutes the first time.


READ THIS BEFORE YOU START
---------------------------------------------------------------------------
- The bot bets REAL money. On paper the calls often look like easy money:
  on good days the terminal's paper balance grows several times over,
  because it counts every call as bought at the exact price on screen. With
  real money the result is much smaller, because the bot often cannot buy
  at that price:
    1) Your computer is farther from the exchange than the fastest traders.
       Polymarket's order book runs on servers in London. Market makers and
       professional bots sit right next to it and react within milliseconds;
       an order from a home computer takes 150-450 ms there and back. When
       Bitcoin jumps, the price you saw is often gone before your order
       arrives. Faster: run the terminal and the bot on a small rented
       server near London (see "FASTER FILLS" at the end).
    2) At that moment there may not be enough to buy. These rounds have
       thin order books, the 5-minute ones especially, and the bot never
       pays more than its price cap.
  On top of that, the calls you miss tend to be the better ones (the price
  runs away mostly when faster traders agree with the call), and the paper
  balance ignores Polymarket's taker fee (roughly 3-7% of the stake, about
  3.5% at 50¢).
  Put on Polymarket only money you are ready to lose completely.
- Start in test mode (no money), then with a limit of $5 per bet.
- The private key of your wallet is full access to your money. You enter it
  once and it is stored only on your computer, in 2-polybot/.env. Never send
  it to anyone: not in chats, not to AI assistants, not to "support". Never
  make a screenshot of it.
- Polymarket is closed in a number of countries, among them Russia,
  Belarus, the UK, the US, Germany and France (the full list:
  help.polymarket.com -> "Geographic restrictions"). Using a VPN to get
  around that breaks its rules.
- Everything works only while the computer is on, awake and online, with
  two windows open: the terminal and the bot.


STEP 1. Install Node.js (once)
---------------------------------------------------------------------------
1. Open https://nodejs.org and click the big LTS button.
2. Open the downloaded .pkg and click Continue until the installation
   ends. Version 24 or newer is needed; the LTS is.
Why it is needed: the terminal and the bot are programs written in
JavaScript. The Terminal app only gives them a window; Node.js is what
actually runs them, the way a video needs a player. It is free.


STEP 2. Unpack the kit (once)
---------------------------------------------------------------------------
1. Double-click Trenchlight-kit-mac.zip. A folder Trenchlight-kit-mac appears. You can move it
   wherever you like, for example to Documents.
2. macOS blocks scripts downloaded from the internet ("Apple could not
   verify..."). Lift the block from the whole folder at once:
     - Open Terminal: Cmd+Space, type "Terminal", press Enter.
     - Type exactly this, WITH A SPACE AT THE END, and do not press
       Enter yet:
           xattr -dr com.apple.quarantine
     - Drag the Trenchlight-kit-mac folder from Finder into the Terminal window: its
       path is added by itself.
     - Press Enter. If nothing is printed, it worked.
   If the "Apple could not verify" window already appeared, click
   "Done" (NOT "Move to Bin") and do this point.


STEP 3. Start the Trenchlight site (the terminal starts with it)
---------------------------------------------------------------------------
1. Open the 1-Trenchlight folder and double-click trenchlight.command.
2. A Terminal window opens. That is the server: do NOT close it while
   you use the site. The browser opens
   http://localhost:8787/trenchlight by itself as soon as it is ready.
3. The first start downloads BTC candle history and takes a few minutes.
   Later starts are faster.
4. Addresses, if you want to open something on its own:
     the whole site      http://localhost:8787/trenchlight
     the terminal only   http://localhost:8787
     the course          http://localhost:8787/course
     Smart traders       http://localhost:8787/smart
   The "Trading bot" tab explains everything in this guide with pictures.


STEP 4. Prepare Polymarket (once)
---------------------------------------------------------------------------
1. MetaMask. Install the MetaMask extension in your browser (metamask.io)
   and create a wallet. Write the 12-word secret phrase on paper and hide
   it. It is never needed here: the bot does not ask for it, and you never
   type it anywhere. Best: a separate MetaMask account just for Polymarket,
   holding only the money you trade with.
2. Go to polymarket.com -> Log in -> MetaMask and confirm.
3. Deposit USDC in any way the site offers.
4. Turn on automatic collection of winnings: Settings -> Trading ->
   "Auto-redeem wins" -> ON. Otherwise you have to claim every win by hand.
5. Place one small bet by hand ($1) on any market. On the first bet
   Polymarket asks you to "Enable trading" and sign it in MetaMask. After
   that the bot can trade too.
6. Copy your POLYMARKET WALLET ADDRESS: click the avatar at the top right
   -> profile; under the name there is an address 0x... with a copy button.
   It is NOT your MetaMask address and NOT one of the deposit addresses for
   other networks from the Deposit window.
7. Get the PRIVATE KEY of the MetaMask account you log in to Polymarket
   with: MetaMask -> the three dots next to the account -> "Account
   details" -> "Show private key" -> enter the MetaMask password -> copy.
   It is 64 characters (digits and letters a-f), NOT 12 words.


STEP 5. Put YOUR address and key into the bot (once)
---------------------------------------------------------------------------
The 2-polybot folder has a file called .env. It is a TEMPLATE with nobody's
data: instead of an address and a key it says "PASTE_...". Replace them
with your own in one of two ways.

Way A (easier, recommended): the script.
1. Open the 2-polybot folder and double-click 1-setup-bot.command.
2. It installs the libraries (1-2 minutes) and then asks for:
     - the Polymarket wallet address: paste it (Cmd+V), press Enter;
     - the private key: paste it (Cmd+V), press Enter. The characters
       are NOT shown; that is normal. The 0x at the start is added for
       you.
3. "Saved to .../.env" means the template now holds your data and all is
   set. Made a typo? Run 1-setup-bot.command again and answer "y".

Way B (by hand).
1. Run 1-setup-bot.command once anyway, so that it installs the libraries. When it
   asks for the address, just close the window.
2. Open the 2-polybot folder in Finder and press Cmd+Shift+. (period).
   Hidden files appear, among them .env.
3. Right-click .env -> Open With -> TextEdit.
4. Replace:
     0xPASTE_YOUR_POLYMARKET_WALLET_ADDRESS_HERE  -> your address (0x...)
     0xPASTE_YOUR_PRIVATE_KEY_HERE                -> your key (64 characters)
   Do not touch the = sign and the names on the left, add no spaces.
5. Save (Cmd+S) and close. Press Cmd+Shift+. again to hide the hidden
   files. Forgot the 0x before the key? No problem: the start script
   adds it.

The .env file with your data stays only on your computer.


STEP 6. Set up the calls in the terminal
---------------------------------------------------------------------------
In the terminal (the BTC Prediction Machine tab), in the right column at
the bottom of the FORECAST card, there is the CALLS box. Set:
  - Budget $: how much money you have on Polymarket (Cash).
  - size: auto (Kelly × edge · time · history)
  - after a loss: same stake (no chasing). Do not choose "recover" or "×2":
    they sharply raise the stakes after losses.
  - can't cover: write off, restart
  - edge ≥ 5 %
  - price ≤ 55 ¢
  - the 5M box ticked (that is what we run). Tick 15M too if you want the
    bot to follow the 15-minute calls as well.
Press "OK — start". ON lights up at the top, and from then on the terminal
issues calls by itself. You see them there and in CALL HISTORY. A call does
not come every round, only when there is value.


STEP 7. Test without money
---------------------------------------------------------------------------
1. The terminal is running (step 3), the calls are on (step 6).
2. In the 2-polybot folder double-click 2-start-bot.command and choose 1.
3. What should appear in the window:
     connected · dry-run: true · max stake $5 · ... · v7
     stream connected
     prewarmed btc-updown-5m-... · 300 ms
   When the terminal issues a call, a line like this appears:
     ... call #3 5m DOWN @ 0.31 (model 38%) → market buy $5.00, cap 0.36 ...
   In test mode the bot only prints this line and buys nothing.
4. Watch for 20-30 minutes. The call numbers in the bot window should match
   the calls in the terminal. Then stop the bot: Ctrl+C.


STEP 8. Run with real money
---------------------------------------------------------------------------
1. Double-click 2-start-bot.command again and choose 2.
2. The most per bet: to begin with, just press Enter, that is $5. You can
   raise it later (the bot never bets more than this, even if a call asks
   for more).
3. Type YES and press Enter. The bot is running. That is all: there is no
   command to type, the script starts the bot with real orders for you.
How to read the bot window:
  order placed ... "status":"matched"
      bought: the bet is placed.
  attempt 1: no orders found to match ... gave up after N attempts
      the price ran above the cap before the order reached the exchange.
      The call is skipped and NO money is spent. This is normal and common.
  trading is disabled
      Polymarket has paused trading for everyone. Wait; the bot carries on
      by itself.
  stream error: ... / stream connected
      the terminal restarted; the bot reconnects by itself.
Between calls the bot is quiet; that is normal.


EVERY DAY
---------------------------------------------------------------------------
- Once a day press "restart with new budget" in CALLS (two clicks) and put
  your real Polymarket Cash into Budget. The stakes are sized from the
  terminal's budget, so it should match your real money.
- The computer must not sleep. While the bot window is open, sleep is
  blocked by itself, but keep the charger plugged in and the lid OPEN.
  With the lid closed a MacBook sleeps anyway. You can dim the screen
  with F1.
- Compare your real Cash on Polymarket with the terminal's paper balance.
  The difference is missed calls and fees.


HOW TO STOP AND HOW TO START AGAIN
---------------------------------------------------------------------------
Stop the bot:      Ctrl+C in its window (press again if needed), or close it.
Stop the site:     Ctrl+C in the server window, or just close that window.
Start again:       trenchlight.command -> wait for the browser ->
                   2-start-bot.command -> 2 -> limit -> YES.
The call session and the history are kept; there is no need to set them up
again.


BOT SETTINGS (optional)
---------------------------------------------------------------------------
The start script sets the two main ones: DRY_RUN (1 = test, 0 = real) and
MAX_STAKE (the most per bet, in dollars). The others have tested defaults.
To change one, add a line to 2-polybot/.env and restart the bot:
  SLIP_LOW=0.09    calls under 20¢: pay up to 9¢ more than the call price
  SLIP_MID=0.05    calls at 20-39¢: up to 5¢ more
  SLIP_HIGH=0.02   calls at 40¢ and above: up to 2¢ more
  RETRY_MS=3000    nothing on offer at the cap: keep trying this long (ms)
  RETRY_GAP=250    the pause between tries (ms)
More slippage buys more calls, but at worse prices: on a call at 51¢ the
whole edge is often a few cents.
Prefer typing the command yourself? In the 2-polybot folder:
  DRY_RUN=0 MAX_STAKE=20 node bot.mjs            (in Terminal)
The start script runs exactly this after "2 -> limit -> YES", and on top
keeps the computer awake and restarts the bot if it crashes.


FASTER FILLS: RUN IT ON A SERVER NEAR LONDON (optional, advanced)
---------------------------------------------------------------------------
Most misses come from distance. A small rented Linux server (a VPS, about
$5 a month, 1 GB of memory is enough) close to London cuts an order's trip
from 150-450 ms to about 15-35 ms, so the bot catches noticeably more calls.
- Where: close to London, in a country Polymarket does not restrict, for
  example Sweden (Stockholm), Spain (Madrid) or Switzerland (Zurich). Not
  London, Dublin, Amsterdam, Frankfurt or Paris: the UK, Ireland, the
  Netherlands, Germany and France are on Polymarket's restricted list.
- How: install Node.js 24+ on the server, copy 1-Trenchlight and 2-polybot
  there (with your filled-in .env), start the terminal with "npm start" in
  1-Trenchlight and the bot with "DRY_RUN=0 MAX_STAKE=20 node bot.mjs" in
  2-polybot, each in its own tmux window. Open the site from your computer
  through an SSH tunnel: ssh -L 8787:localhost:8787 user@server, then
  http://localhost:8787/trenchlight
- It does not make the bot as fast as the market makers next to the
  exchange: it catches more calls, not all. And a server does not change
  where you may trade: Polymarket's rules follow where you live.


IF SOMETHING GOES WRONG
---------------------------------------------------------------------------
"Apple could not verify ..." when you double-click
    -> step 2, point 2.
"port 8787 is already in use"
    -> the terminal is already running. Just open
       http://localhost:8787/trenchlight
".env still holds the template"
    -> you did not replace "PASTE_...". Do step 5 (way A or B).
"The terminal is not running" when you start the bot
    -> start trenchlight.command first and wait until the browser opens.
"Node.js not found" or "needs Node.js 24 or newer"
    -> step 1: install the LTS again.
"Expected a hex-encoded 32-byte private key" or "something is wrong in .env"
    -> the key was entered wrongly (or the 12 words were pasted). Run
       1-setup-bot.command again.
"not enough balance / allowance"
    -> no money on Polymarket, or trading is not enabled yet: deposit, or
       place one bet by hand (step 4, point 5).
"invalid signature", "unauthorized", "401"
    -> the address and the key are from different accounts. The address
       must belong to the Polymarket account you log in to with this same
       MetaMask account. Run 1-setup-bot.command and enter them again.
"The bot stopped right after starting"
    -> the reason is in the error line right above that message; find it
       in this list.
The bot buys nothing although there are calls
    -> the bot window must show "call #..." lines. If there are none, close
       the bot window and start 2-start-bot.command again. If they are there and are
       followed by "gave up", that is a miss, not a fault (see step 8).


SECURITY, ONCE MORE
---------------------------------------------------------------------------
- The key lives only in the file 2-polybot/.env on your computer.
- After step 5 the .env holds YOUR key and address. If you pass the kit on
  to someone, send the original zip: it holds only the template. Never
  share your set-up 2-polybot folder.
- Never type the 12-word secret phrase anywhere except MetaMask itself.
- Not financial advice. Prediction-market shares can lose the whole stake.
