📘 HeatCheck manual

1. What the app does

• Dashboard shows the No bets: markets where the model thinks the temperature is less likely to land in the bucket than the market price implies.
• Today's Yes shows the opposite: the Yes-side bucket that the forecast points to, together with the live Yes price and edge.
• Auto turns the live analysis into a reviewed, sized proposal. It is intentionally proposal-only and never places an order.

2. How to read the main table

• Edge shows whether the model's win estimate is better than the current Yes price.
• Net edge is the same idea after a fee/slippage allowance.
• Fillable is the real order-book depth near the ask. A thin or empty book is a warning sign.
• Status tells you whether the day is still moving, the peak is near, or the bucket is effectively locked.

If a row is struck through with a warning marker, treat it as a phantom edge: it looks good on paper but may not be realistically fillable.

3. Safe first steps for live execution

Step A — install the dependency

Step B — set the environment variables

Step C — run a safe mini test

In test mode the code does not place a real order. It returns a simulated success response and logs it as a live row.

4. Using the live alert button

The app now has a live alert panel on the Today's Yes page. It uses the same rule gates as the Auto tab before sending anything.

• Open Today's Yes and use the Send rule-pass alert button.
• The button only sends the top proposal that clears the configured rules.
• It will send the alert to the local auto-trade server at http://127.0.0.1:8799/alert.
• If you have locked the server (see section 5), fill in the Server username / Server password fields — this is the lock on your own local server, not your Polymarket or wallet login.

4b. The Control tab (live status)

Open the 🛡️ Control tab on the Today's Yes page to see, in real time, exactly what your local engine is doing — before you ever arm it.

• Point Server at 127.0.0.1:8799 and enter the server username/password if you set one.
• A big TEST/LIVE badge and a one-line bottom line tell you whether a real order can go out right now, and why not.
• Tiles show every safety gate: key loaded, kill switch, auth scheme, per-bet and per-day caps, and money spent today.
• Recent activity streams the latest audit-log rows (alerts, login denials, lockouts, orders), newest first, auto-refreshing every 5 seconds.
• This tab only reads state — it never places an order.

5. Locking the local endpoint (username + password)

This lock only guards your own local server on localhost:8799 (both /alert and /status). It is not a Polymarket or wallet login — it just makes sure only you can tell the engine to act.

Recommended — set a hashed password:

It prompts for a username and password, stores the password as a PBKDF2 hash in .env (never the plaintext), and removes any old plaintext password. Restart the server to apply. The login is checked in constant time, and repeated failed attempts are locked out for a cooldown.

Leave the username and password unset to run without a lock (only fine on a machine only you use). python autotrade.py status shows the active auth_scheme: hash, plaintext, or off.

6. Connect your Polymarket account

Read-only market data needs no key. To trade, the engine needs your account:

• Use a dedicated wallet that only holds trading capital, with some USDC on Polygon.
• Put its private key in .env as PK. API credentials are derived automatically from it.
• One-time per wallet: approve the USDC + outcome-token allowances for the CLOB exchange, or orders are rejected.
• Verify the connection: python autotrade.py doctor, or 🔗 Check Polymarket connection in the Control tab. It shows a structured ✓/✗ readiness list and your wallet address — without placing anything.

7. Prove the plumbing with a trial buy

Before trusting strategy sizes, place one tiny real order (hard-capped ~$3) that proves signing, allowance and execution work — not a strategy bet.

• In the app: Control → 🧪 Trial buy — enter the Yes token_id, a price, a small amount, type TRIAL BUY, and place it.
• Or: python autotrade.py trial-buy <token_id> <price> <usd>.
• It runs behind the same safety gates + arming, but skips the strategy edge rules, and the result confirms the exact data used and which rules ran.

8. Going LIVE — the two-key ignition

A real order needs both keys, and arming expires on its own so nothing is ever left hot:

• Key 1 — base setup: POLYMARKET_LIVE_TEST_MODE=0, PK loaded, no STOP file.
• Key 2 — arm: in the Control tab type ARM LIVE, pick minutes, and click Arm (or python autotrade.py arm).
• Then send an alert from the Today tab. Stop instantly with Disarm, python autotrade.py disarm, or a STOP file.
• The 🛡️ Control tab documents this whole process live, and shows a “can a real order go out now — yes/no” bottom line.

9. Portfolio, P&L, selling and settlement

The 🛡️ Control tab is a command center — do most things in one place:

• 💼 Portfolio: net position per market, cost basis, a live mark-to-market for open positions, and realized P&L once settled.
• Settle a resolved market with the won/lost buttons (or Auto-settle, which only acts when the price is unambiguous) to fill its outcome and P&L.
• Sell to close part of a position early — a real SELL order behind arming + kill switch; realized P&L is logged against your average cost.
• 🚀 Send top proposal right from the command center, and see the detailed per-trade log (what/price/why) in the Auto tab.

10. See exactly what happened

• Auto tab → “Executed & logged trades”: what was bought/sold, at what price, and why (rule · win% · edge · market-agrees), PAPER vs LIVE.
• Control tab → “Recent activity”: every arm/disarm, alert, order, sell and settlement.
• Files: paper_ledger.csv (trades + settlement), audit_log.jsonl (all events), arm_state.json (current arming).

11. Important safety rules

• The browser page never signs an order — the local server does, and only when armed & LIVE.
• Do not store private keys in the repository or in the app.
• Use the kill switch (STOP file) or Disarm if the market data, rules, or execution path looks inconsistent.
• Do not treat the displayed edge as guaranteed profit; it is only the current estimate. Size up only after a proven, walk-forward edge.