feat: add Polymarket links, balance flash animation, and docs update

- Add event_slug to Market model and parse from Gamma API responses
- Add "↗ PM" links in MarketList linking to real Polymarket event pages
- Add balance flash animation (scale + purple) on cash changes after trades
- Pass refreshBalance via Outlet context so Markets page triggers updates
- Update README with web dashboard section, architecture diagram, web command
- Add API surface mapping table to CLAUDE.md

Author: qhuang20

CLAUDE.md

@@ -81,6 +81,17 @@ mcp_server.py → engine.py (trading tools, 30 MCP tools)
 - **No price/book caching**: always live from API. Market metadata cached 5 min.
 - **Multi-account**: separate SQLite databases at `~/.pm-trader/<account>/paper.db`
 
+## API surface mapping
+
+| Gamma API endpoint | api.py method | CLI    | MCP    | Web (FastAPI) |
+|---|---|---|---|---|
+| `GET /markets` (list) | `list_markets()` | `markets list` | `list_markets` | `GET /api/markets` |
+| `GET /markets` (single) | `get_market()` | `markets get` | `get_market` | `GET /api/markets/{slug}/book` |
+| `GET /public-search` | `search_markets()` | `markets search` | `search_markets` | `GET /api/markets?query=` |
+| `GET /events` | `get_markets_by_tag()` | `markets list --tag` | `get_markets_by_tag` | `GET /api/markets?tag=` |
+| `GET /tags` | `get_tags()` | `markets tags` | `get_tags` | `GET /api/tags` |
+| `GET /categories` | `get_categories()` | — | — | `GET /api/categories` |
+
 ## Testing rules
 
 - **Always run tests after changes**: `python3 -m pytest tests/ -x -q -m "not live"`

README.md

@@ -18,6 +18,7 @@ pm-trader init --balance 10000                 # $10k paper money
 pm-trader markets search "bitcoin"             # find markets
 pm-trader buy will-bitcoin-hit-100k yes 500    # buy $500 of YES
 pm-trader stats --card                         # shareable stats card
+pm-trader web                                  # or use the web dashboard
 ```
 
 That's it. Your AI agent is now trading Polymarket with zero risk.
@@ -63,6 +64,38 @@ pm-trader portfolio
 pm-trader stats
 ```
 
+
+
+--- 
+
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│           接入层 (Entry Points)                  │
+│                                                 │
+│   cli.py          → CLI                         │
+│   mcp_server.py   → AI Agent (MCP)              │
+│   web/app.py      → Web Dashboard (FastAPI)     │
+├─────────────────────────────────────────────────┤
+│           业务层 (Core Logic)                    │
+│                                                 │
+│   engine.py       → Trading Engine              │
+│   analytics.py    → Stats & Analytics           │
+│   orders.py       → Limit Order State Machine   │
+│   orderbook.py    → Order Book Simulation       │
+├─────────────────────────────────────────────────┤
+│           数据层 (Data)                          │
+│                                                 │
+│   db.py           → SQLite (WAL mode)           │
+│   api.py          → Polymarket API (Gamma/CLOB) │
+└─────────────────────────────────────────────────┘
+```
+
+
+
+
 ## CLI commands
 
 | Command | Description |
@@ -94,10 +127,34 @@ pm-trader stats
 | `benchmark pk STRAT_A STRAT_B` | Battle: who's the better trader? |
 | `accounts list` | List named accounts |
 | `accounts create NAME` | Create account for A/B testing |
+| `web [--port N] [--reload]` | Start web dashboard |
 | `mcp` | Start MCP server (stdio transport) |
 
 Global flags: `--data-dir PATH`, `--account NAME` (or env vars `PM_TRADER_DATA_DIR`, `PM_TRADER_ACCOUNT`).
 
+
+
+
+## Web dashboard
+
+A browser-based UI for browsing markets, placing trades, and monitoring your portfolio.
+
+```bash
+pm-trader web                    # http://127.0.0.1:8000
+pm-trader web --port 3000        # custom port
+pm-trader web --reload           # auto-reload for development
+```
+
+Features:
+- Browse and search markets with category filters
+- Place buy/sell orders (FOK/FAK)
+- Live portfolio and balance tracking
+- Direct links to Polymarket for each market
+
+
+
+
+
 ## MCP server — what your agent can do
 
 Your agent gets 26 tools via the [Model Context Protocol](https://modelcontextprotocol.io):
@@ -149,6 +206,11 @@ Add to your Claude Code config:
 | `pk_card` | Head-to-head comparison between two accounts |
 | `pk_battle` | Run two strategies head-to-head, auto-compare |
 
+
+
+---
+
+
 ## Strategy examples
 
 Three ready-to-use strategies in `examples/`:

frontend/src/api/types.ts

@@ -78,6 +78,7 @@ export interface MarketItem {
   volume: number
   liquidity: number
   end_date: string | null
+  event_slug: string
 }
 
 export interface OrderBookLevel {

frontend/src/components/Layout.tsx

@@ -1,23 +1,36 @@
-import { NavLink, Outlet } from 'react-router-dom'
-import { useEffect, useState } from 'react'
+import { NavLink, Outlet, useOutletContext } from 'react-router-dom'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import { fetchAccounts, fetchBalance, setAccount, getAccount } from '../api/client'
 import type { Balance } from '../api/types'
 
 export default function Layout() {
   const [accounts, setAccounts] = useState<string[]>([])
   const [selected, setSelected] = useState(getAccount())
   const [balance, setBalance] = useState<Balance | null>(null)
+  const [flash, setFlash] = useState(false)
+  const prevCash = useRef<number | null>(null)
+
   useEffect(() => {
     fetchAccounts().then(setAccounts).catch(() => {})
   }, [])
 
+  const refreshBalance = useCallback(() => {
+    fetchBalance().then(b => {
+      if (prevCash.current !== null && b.cash !== prevCash.current) {
+        setFlash(true)
+        setTimeout(() => setFlash(false), 800)
+      }
+      prevCash.current = b.cash
+      setBalance(b)
+    }).catch(() => {})
+  }, [])
+
   useEffect(() => {
     setAccount(selected)
-    const refresh = () => fetchBalance().then(setBalance).catch(() => {})
-    refresh()
-    const interval = setInterval(refresh, 60_000)
+    refreshBalance()
+    const interval = setInterval(refreshBalance, 60_000)
     return () => clearInterval(interval)
-  }, [selected])
+  }, [selected, refreshBalance])
 
   return (
     <div style={{ minHeight: '100vh', background: '#fafafa' }}>
@@ -38,13 +51,18 @@ export default function Layout() {
         </div>
         <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
           {balance && (
-            <div style={{ display: 'flex', gap: 12, alignItems: 'center', fontSize: '0.9em' }}>
-              <span style={{ color: '#333' }}>
-                <span style={{ color: '#888', marginRight: 4 }}>Portfolio</span>
+            <div style={{
+              display: 'flex', gap: 12, alignItems: 'center', fontSize: '0.9em',
+              transition: 'transform 0.3s, color 0.3s',
+              transform: flash ? 'scale(1.1)' : 'scale(1)',
+              color: flash ? '#4f46e5' : '#333',
+            }}>
+              <span>
+                <span style={{ color: flash ? '#4f46e5' : '#888', marginRight: 4 }}>Portfolio</span>
                 ${balance.total_value.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}
               </span>
-              <span style={{ color: '#333' }}>
-                <span style={{ color: '#888', marginRight: 4 }}>Cash</span>
+              <span>
+                <span style={{ color: flash ? '#4f46e5' : '#888', marginRight: 4 }}>Cash</span>
                 ${balance.cash.toLocaleString(undefined, { minimumFractionDigits: 2 })}
               </span>
             </div>
@@ -59,7 +77,7 @@ export default function Layout() {
         </div>
       </nav>
       <main style={{ maxWidth: 1200, margin: '0 auto', padding: '20px 24px' }}>
-        <Outlet />
+        <Outlet context={{ refreshBalance }} />
       </main>
     </div>
   )

frontend/src/components/MarketList.tsx

@@ -23,7 +23,18 @@ export default function MarketList({ markets, selected, onSelect }: Props) {
             borderLeft: selected?.condition_id === m.condition_id ? '3px solid #4f46e5' : '3px solid transparent',
           }}
         >
-          <div style={{ fontWeight: 600, fontSize: '0.9em' }}>{m.question}</div>
+          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'start', gap: 8 }}>
+            <span style={{ fontWeight: 600, fontSize: '0.9em' }}>{m.question}</span>
+            <a
+              href={`https://polymarket.com/event/${m.event_slug || m.slug}`}
+              target="_blank"
+              rel="noopener noreferrer"
+              onClick={e => e.stopPropagation()}
+              style={{ fontSize: '0.75em', color: '#4f46e5', textDecoration: 'none', whiteSpace: 'nowrap', flexShrink: 0 }}
+              onMouseEnter={e => (e.currentTarget.style.opacity = '0.7')}
+              onMouseLeave={e => (e.currentTarget.style.opacity = '1')}
+            >↗ PM</a>
+          </div>
           <div style={{ display: 'flex', justifyContent: 'space-between', marginTop: 6, fontSize: '0.8em', color: '#666' }}>
             <span>YES: <strong style={{ color: '#16a34a' }}>${m.outcome_prices[0]?.toFixed(2)}</strong></span>
             <span>NO: <strong style={{ color: '#dc2626' }}>${m.outcome_prices[1]?.toFixed(2)}</strong></span>

frontend/src/pages/Markets.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useState, useCallback } from 'react'
+import { useOutletContext } from 'react-router-dom'
 import { fetchMarkets } from '../api/client'
 import type { MarketItem } from '../api/types'
 import MarketList from '../components/MarketList'
@@ -17,6 +18,7 @@ const CATEGORIES = [
 ]
 
 export default function Markets() {
+  const { refreshBalance } = useOutletContext<{ refreshBalance: () => void }>()
   const [markets, setMarkets] = useState<MarketItem[]>([])
   const [selected, setSelected] = useState<MarketItem | null>(null)
   const [query, setQuery] = useState('')
@@ -83,7 +85,7 @@ export default function Markets() {
       <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
         <MarketList markets={markets} selected={selected} onSelect={setSelected} />
         {selected ? (
-          <TradePanel market={selected} onTradeComplete={() => doSearch(query || undefined, activeTag || undefined)} />
+          <TradePanel market={selected} onTradeComplete={() => { doSearch(query || undefined, activeTag || undefined); refreshBalance() }} />
         ) : (
           <div style={{ background: 'white', borderRadius: 8, padding: 40, textAlign: 'center', color: '#888', boxShadow: '0 1px 3px rgba(0,0,0,0.08)' }}>
             Select a market to trade

pm_trader/api.py

@@ -184,10 +184,14 @@ def search_markets(self, query: str, *, limit: int = 10) -> list[Market]:
             return []
         markets: list[Market] = []
         for event in data.get("events", []):
+            event_slug = event.get("slug", "")
             for m in event.get("markets", []):
                 if _has_condition_id(m):
                     try:
-                        markets.append(_parse_market(m))
+                        mkt = _parse_market(m)
+                        if not mkt.event_slug:
+                            mkt.event_slug = event_slug
+                        markets.append(mkt)
                     except (KeyError, TypeError):
                         continue
         return markets[:limit]
@@ -241,11 +245,16 @@ def get_markets_by_tag(
         if not isinstance(events, list):
             return []
         # Each event embeds a list of markets — flatten them
-        all_markets: list[dict] = []
+        all_markets: list[Market] = []
         for event in events:
+            event_slug = event.get("slug", "")
             for m in event.get("markets", []):
-                all_markets.append(m)
-        return self._parse_market_list(all_markets)[:limit]
+                if _has_condition_id(m):
+                    mkt = _parse_market(m)
+                    if not mkt.event_slug:
+                        mkt.event_slug = event_slug
+                    all_markets.append(mkt)
+        return all_markets[:limit]
 
     def get_event(self, slug: str) -> dict:
         """Fetch event details (group of related markets).  Cached 5 min."""
@@ -410,6 +419,13 @@ def _parse_market(data: dict) -> Market:
                              data.get("minimum_tick_size", 0.01))
     tick_size = float(tick_size_raw) if tick_size_raw else 0.01
 
+    # event slug: extract from nested events list (Gamma API)
+    event_slug = data.get("event_slug", "")
+    if not event_slug:
+        events = data.get("events", [])
+        if isinstance(events, list) and events:
+            event_slug = events[0].get("slug", "")
+
     return Market(
         condition_id=condition_id,
         slug=data.get("slug", ""),
@@ -425,6 +441,7 @@ def _parse_market(data: dict) -> Market:
         end_date=data.get("endDateIso", data.get("end_date_iso", data.get("end_date", ""))),
         fee_rate_bps=int(data.get("fee_rate_bps", 0) or 0),
         tick_size=tick_size,
+        event_slug=event_slug,
     )
 
 

pm_trader/models.py

@@ -135,6 +135,7 @@ class Market:
     end_date: str = ""
     fee_rate_bps: int = 0
     tick_size: float = 0.01
+    event_slug: str = ""
 
     def get_token_id(self, outcome: str) -> str:
         """Token ID for any outcome (case-insensitive)."""

pm_trader/web/routes/markets.py

@@ -12,6 +12,7 @@ def _market_to_dict(m) -> dict:
         "outcomes": m.outcomes, "outcome_prices": m.outcome_prices,
         "active": m.active, "closed": m.closed, "volume": m.volume,
         "liquidity": m.liquidity, "end_date": m.end_date,
+        "event_slug": m.event_slug,
     }
 
 def _book_to_dict(book) -> dict:

tests/test_api.py

@@ -128,6 +128,20 @@ def test_null_volume_liquidity(self):
         assert market.volume == 0.0
         assert market.liquidity == 0.0
 
+    def test_event_slug_from_nested_events(self):
+        data = {**SAMPLE_GAMMA_MARKET, "events": [{"slug": "parent-event"}]}
+        market = _parse_market(data)
+        assert market.event_slug == "parent-event"
+
+    def test_event_slug_direct(self):
+        data = {**SAMPLE_GAMMA_MARKET, "event_slug": "direct-slug"}
+        market = _parse_market(data)
+        assert market.event_slug == "direct-slug"
+
+    def test_event_slug_default_empty(self):
+        market = _parse_market(SAMPLE_GAMMA_MARKET)
+        assert market.event_slug == ""
+
 
 # ---------------------------------------------------------------------------
 # _parse_order_book tests