# Comparative Learning Agent — Build Spec > **For the coding agent reading this file:** this is a complete build brief. > Implement the system described below as a **single self-contained HTML file** > the user can open in a browser. Do the §0 discovery pass first, then build to > the spec. Everything the user configures (tracked wallet, wake-up interval) is > entered in the page itself — no rebuild needed to change them. Keep it to one > file with no backend unless §6 forces it. --- ## What we're building, in one paragraph A small tool that helps a Polymarket trading bot get better by **watching a trader who's already winning at the same thing**. The user pastes in a tracked trader's wallet address and picks how often the agent should wake up (e.g. every 20 minutes). On each wake-up, the agent pulls the recent trades from **both** the user's own bot and the tracked trader, runs a short multi-step analysis comparing the two, and writes out **one to three concrete recommendations** for that interval. The user reads them and decides what to change. Nothing is ever applied to the bot automatically. The output is a single HTML page the user opens locally: a config panel at the top (wallet + interval + their own trade-log source), a live status line showing when the agent last woke and when it wakes next, and a running feed of interval-by-interval analyses with their recommendations. --- ## The one rule that makes this work The tracked trader **must be running the same strategy on the same market type as the user's bot, just better.** Same markets, same approach, higher skill. Comparing a market-maker against a directional gambler, or a crypto up/down bot against sports, produces confident, useless advice. Surface this rule in the UI near the wallet input, and have the analysis flag it when the tracked trader's markets don't overlap the user's. --- ## §0 — Discovery pass (do this before writing code) Two things live in the user's codebase. Find them and confirm back before building: 1. **Where the user's bot logs its own fills.** Find the file/format the bot already writes trades to (likely line-delimited JSON). You need per fill: timestamp, market id, side (buy/sell), outcome, price, size. If the bot doesn't log durably yet, that's prerequisite #1 — say so. 2. **How the page will read both trade sources at runtime.** The tracked trader's trades come from Polymarket (see §3). The user's own trades come from the log in (1). Decide the simplest wiring that lets the HTML page read both (see §6 — usually the page reads two local JSON/JSONL files, or a tiny local endpoint serves them). Also confirm the user's **market type** (e.g. 5-minute crypto up/down, an event market, etc.) so the analysis compares like for like. --- ## §1 — How the system behaves ``` user opens the HTML page │ ├─ pastes tracked wallet address ├─ sets wake-up interval (e.g. 20 min) └─ points it at their own bot's trade log │ ▼ ┌─────────────────────────────────────────────┐ │ every , the agent wakes up and: │ │ 1. pulls recent trades — BOTH sides │ │ 2. runs the multi-step analysis (§4) │ │ 3. writes 1–3 recommendations │ │ 4. appends the result to the feed │ └─────────────────────────────────────────────┘ │ ▼ user reads the recommendations, decides what to change (nothing is auto-applied) ``` The page should keep running on a timer. Each wake-up is one self-contained analysis covering a recent lookback window (default: the last 30 minutes of trades). Consecutive intervals can overlap — that's fine and smooths out noise. --- ## §2 — What the user configures (all in the page) | Field | Meaning | Default | |---|---|---| | **Tracked wallet** | The trader to learn from — their Polymarket `proxyWallet` address (§3) | (none — required) | | **Wake-up interval** | How often the agent re-runs the analysis | 20 minutes | | **Lookback window** | How much recent history each analysis covers | 30 minutes | | **Own trade log** | Where the user's bot writes its fills | (from §0) | Optionally allow **multiple tracked wallets** — a small list rather than one field. If several are given, the analysis picks the strongest performer for that interval as the one to compare against (see §4, step 3). Put the "same strategy, same market" rule as helper text right under the wallet field. --- ## §3 — Getting the tracked trader's trades (Polymarket) Use Polymarket's official real-time data client: **https://github.com/Polymarket/real-time-data-client** Key facts the agent needs: - On Polymarket, every trade is indexed under the user's **proxy wallet**, not their sign-in wallet. The address the user pastes is the `proxyWallet`, and it's the address on the trader's profile URL (`polymarket.com/profile/
`). - The client streams **all** platform trades over a websocket (`wss://ws-live-data.polymarket.com`), topic `activity`, type `trades`. Subscribe with an **empty filter** and filter **client-side** by `proxyWallet` — the server-side filters don't reliably work for this feed. - Each trade event carries: `proxyWallet`, `timestamp`, `slug`/`conditionId` (market), `outcome`, `outcomeIndex` (0/1), `side` (BUY/SELL), `price`, `size`, `transactionHash` (use as the dedup key). - For a simpler pull without a live socket, the public REST data API works too: `GET https://data-api.polymarket.com/trades?user=&limit=200` — no auth. For a tool that wakes every 20 minutes, this REST pull per interval is often all you need; reach for the websocket only if the user wants lower latency. Dedup by `transactionHash` so reconnects/re-pulls never double-count. --- ## §4 — The multi-step analysis (the core) On each wake-up, the agent runs these steps in order. The whole point of making it multi-step is so the recommendations are reasoned, not pattern-matched. **Step 1 — Pull both sides.** Load the user's own fills and the tracked trader's trades over the lookback window. Normalize both to the same simple shape (timestamp, market, side, outcome, price, size) so they're directly comparable. **Step 2 — Summarize each side the same way.** Reduce each side's trades to the same handful of numbers, using identical logic for both — this is what keeps it honest. A good minimal set: - how many trades and how much volume - average entry price (are they getting in cheaper?) - how often positions get fully closed/hedged vs left one-sided (completion) - how much unhedged/one-sided risk they're carrying - how early in the market window they enter **Step 3 — Pick who to compare against.** If tracking several wallets, choose the strongest performer this interval (reward locked-in profit, penalize naked risk). If one wallet, that's the comparison. Confirm its markets actually overlap the user's — if not, flag the mismatch and skip the interval rather than give bad advice. **Step 4 — Find the gaps.** Compare the user's summary to the tracked trader's, metric by metric. For each metric where the trader is clearly ahead, note the gap in plain language with the actual numbers ("they enter ~18s earlier", "they pay ~2¢ less per position", "they close 85% of positions vs your 50%"). **Step 5 — Turn the biggest gaps into recommendations.** Rank the gaps by how much they matter and how confident the agent is. Write **one to three** concrete recommendations — never more. Each recommendation should name the behavior to change, why (the gap and numbers behind it), and a rough confidence. Drop weak or low-confidence gaps; it's better to give one strong recommendation than three mushy ones. **Step 6 — Write it to the feed.** Append a timestamped entry: the interval's summary numbers for both sides, the gaps found, and the 1-3 recommendations. If nothing cleared the bar this interval, say so plainly ("no strong gaps this interval — your bot tracked the reference closely") rather than inventing advice. --- ## §5 — Output format (per interval) Each wake-up appends one block to the page's feed: ``` ▸ 5:40 PM · last 30 min ────────────────────────── Compared against: you them trades 12 15 avg entry 0.48 0.46 completion 50% 85% naked $ 40 5 entry timing +70s +30s Recommendations (2): 1. Close more pairs. They complete 85% of positions; you complete 50%, leaving ~$40 one-sided. Turn on / tighten your position-completion logic. confidence: high 2. Enter earlier. They're in ~40s sooner on average. Shorten your entry cadence so you're not late to the window. confidence: medium ────────────────────────────────────────────────── ``` Keep it scannable. The numbers table + a short ranked list of recommendations is the whole payload. No walls of prose. --- ## §6 — Wiring notes (keep it as simple as the codebase allows) The deliverable is **one HTML file**. The only wrinkle is that a browser page can't read arbitrary local files or hold a websocket to Polymarket forever without help. Pick the simplest option that fits the user's setup: - **Simplest (REST, no backend):** on each wake-up the page fetches the tracked trader's recent trades from the public REST data API (§3), and reads the user's own trades from a local file the page is allowed to load (or that the user pastes/exports). Good enough for 20-minute intervals. - **If a live socket is wanted:** a tiny local helper process holds the Polymarket websocket and writes matching trades to a local file the page polls. Only add this if the user explicitly wants sub-second freshness. Either way: the **page** owns the timer, the analysis, and the feed. Keep the recommendation engine in the page so the user can open the file and just use it. Never auto-apply anything to the bot. The page only ever reads and recommends. --- ## §7 — Build checklist for the agent - [ ] Did the §0 discovery pass; confirmed the user's own fill-log path/format and market type - [ ] Single HTML file, opens locally, no build step to change wallet or interval - [ ] Config panel: tracked wallet(s), wake-up interval, lookback, own-log source - [ ] "Same strategy, same market" helper text by the wallet field - [ ] Pulls tracked trades from Polymarket by `proxyWallet`, dedup by `transactionHash` - [ ] Reads the user's own trades over the same lookback window - [ ] Summarizes both sides with identical logic (same metrics, both sides) - [ ] Runs the multi-step analysis (§4) on every wake-up - [ ] Produces 1–3 ranked recommendations per interval, with the numbers behind each - [ ] Says so plainly when there's nothing strong to recommend - [ ] Running feed of timestamped interval results - [ ] Status line: last wake-up + next wake-up countdown - [ ] Never auto-applies; read-and-recommend only