Add StockEx trading integration for player agents

- New API endpoints: /stockex/market, /stockex/leaderboard,
/stockex/portfolio/{id}, /stockex/order
- Player agents can browse market data, view portfolios, and place
buy/sell orders on StockEx clearing house
- Orders recorded as life events and memories for the agent
- Web UI: StockEx button in player panel opens trading modal with
live market data, portfolio view, and order form

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/soci/api/routes.py

@@ -834,3 +834,106 @@ async def save_state(name: str = "manual_save"):
     from soci.persistence.snapshots import save_simulation
     await save_simulation(sim, db, name)
     return {"status": "saved", "name": name, "tick": sim.clock.total_ticks}
+
+
+# ── StockEx integration ──────────────────────────────────────────────────────
+
+import os
+import httpx
+
+STOCKEX_URL = os.getenv("STOCKEX_URL", "https://raymelius-stockex.hf.space")
+STOCKEX_API_KEY = os.getenv("STOCKEX_API_KEY", "soci-stockex-2024")
+
+
+class StockExOrderRequest(BaseModel):
+    token: str          # Soci player token
+    member_id: str      # StockEx member ID (e.g. USR02)
+    symbol: str
+    side: str           # BUY or SELL
+    quantity: int
+    price: float
+
+
+@router.get("/stockex/market")
+async def stockex_market():
+    """Get current market data (best bid/offer) from StockEx."""
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        resp = await client.get(f"{STOCKEX_URL}/ch/api/market")
+        if resp.status_code != 200:
+            raise HTTPException(status_code=502, detail="StockEx market unavailable")
+        return resp.json()
+
+
+@router.get("/stockex/leaderboard")
+async def stockex_leaderboard():
+    """Get StockEx clearing house leaderboard."""
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        resp = await client.get(f"{STOCKEX_URL}/ch/api/leaderboard")
+        if resp.status_code != 200:
+            raise HTTPException(status_code=502, detail="StockEx unavailable")
+        return resp.json()
+
+
+@router.get("/stockex/portfolio/{member_id}")
+async def stockex_portfolio(member_id: str):
+    """Get a StockEx member's portfolio."""
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        resp = await client.get(f"{STOCKEX_URL}/ch/api/member/{member_id}")
+        if resp.status_code != 200:
+            raise HTTPException(status_code=502, detail="StockEx member not found")
+        return resp.json()
+
+
+@router.post("/stockex/order")
+async def stockex_order(req: StockExOrderRequest):
+    """Place a trade on StockEx on behalf of a Soci player agent."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+
+    # Verify Soci player token
+    from soci.persistence.database import Database
+    db = Database()
+    user = await db.get_user_by_token(req.token)
+    if not user or not user.get("agent_id"):
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+    agent = sim.agents.get(user["agent_id"])
+    if not agent:
+        raise HTTPException(status_code=404, detail="Player agent not found")
+
+    # Place order on StockEx via API key
+    order_data = {
+        "api_key": STOCKEX_API_KEY,
+        "member_id": req.member_id,
+        "symbol": req.symbol.upper(),
+        "side": req.side.upper(),
+        "quantity": req.quantity,
+        "price": req.price,
+    }
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        resp = await client.post(f"{STOCKEX_URL}/ch/api/order", json=order_data)
+        result = resp.json()
+
+    if resp.status_code != 200:
+        raise HTTPException(status_code=resp.status_code, detail=result.get("error", "Order failed"))
+
+    # Record as life event for the agent
+    side_str = req.side.upper()
+    agent.add_life_event(
+        day=sim.clock.day, tick=sim.clock.total_ticks,
+        event_type="achievement",
+        description=f"Traded on StockEx: {side_str} {req.quantity} {req.symbol.upper()} @ €{req.price:.2f}",
+    )
+    agent.add_observation(
+        tick=sim.clock.total_ticks, day=sim.clock.day,
+        time_str=sim.clock.time_str,
+        content=f"I placed a {side_str} order for {req.quantity} shares of {req.symbol.upper()} at €{req.price:.2f} on StockEx.",
+        importance=7,
+    )
+
+    return {
+        "status": "ok",
+        "cl_ord_id": result.get("cl_ord_id"),
+        "detail": f"{side_str} {req.quantity} {req.symbol.upper()} @ €{req.price:.2f}",
+    }

web/index.html

@@ -325,6 +325,7 @@
         <div class="pp-actions">
           <button class="pp-btn" onclick="openProfileEditor()">Edit Profile</button>
           <button class="pp-btn" onclick="openPlansModal()">My Plans</button>
+          <button class="pp-btn" onclick="openStockExModal()" style="background:#1a3a2e;border-color:#2a6a4e">StockEx</button>
         </div>
       </div>
       <div id="agent-detail"></div>
@@ -408,6 +409,53 @@
   </div>
 </div>
 
+<!-- StockEx Trading modal -->
+<div id="stockex-modal" class="modal-overlay" style="display:none">
+  <div class="modal-box" style="max-width:480px">
+    <h2 style="color:#4ecca3">StockEx Trading</h2>
+    <div id="stockex-status" style="font-size:11px;color:#888;margin-bottom:8px"></div>
+
+    <div id="stockex-portfolio" style="font-size:11px;color:#a0a0c0;margin-bottom:10px;max-height:120px;overflow-y:auto"></div>
+
+    <div class="modal-row">
+      <div style="flex:1">
+        <label>Member ID</label>
+        <input type="text" id="sx-member" placeholder="USR02" value="USR02" style="text-transform:uppercase">
+      </div>
+      <div style="flex:1">
+        <label>Symbol</label>
+        <select id="sx-symbol" style="width:100%;padding:6px 8px;background:#1e1e30;border:1px solid #3a3a5c;border-radius:6px;color:#e0e0f0;font-size:13px">
+          <option>Loading...</option>
+        </select>
+      </div>
+    </div>
+    <div class="modal-row">
+      <div style="flex:1">
+        <label>Side</label>
+        <select id="sx-side" style="width:100%;padding:6px 8px;background:#1e1e30;border:1px solid #3a3a5c;border-radius:6px;color:#e0e0f0;font-size:13px">
+          <option value="BUY">BUY</option>
+          <option value="SELL">SELL</option>
+        </select>
+      </div>
+      <div style="flex:1">
+        <label>Quantity</label>
+        <input type="number" id="sx-qty" min="1" value="100">
+      </div>
+      <div style="flex:1">
+        <label>Price</label>
+        <input type="number" id="sx-price" step="0.01" min="0.01" value="0">
+      </div>
+    </div>
+    <div id="sx-market-info" style="font-size:10px;color:#555;margin:4px 0"></div>
+    <div id="sx-result" style="font-size:11px;margin:6px 0;min-height:18px"></div>
+    <div class="modal-actions">
+      <button class="btn-secondary" onclick="document.getElementById('stockex-modal').style.display='none'">Close</button>
+      <button class="btn-secondary" onclick="loadStockExPortfolio()">Refresh</button>
+      <button class="btn-primary" onclick="submitStockExOrder()" style="background:#1a6a3e">Place Order</button>
+    </div>
+  </div>
+</div>
+
 <script>
 // ============================================================
 // CONFIG
@@ -3364,6 +3412,110 @@ async function addPlan() {
   } catch(e){}
 }
 
+// ── StockEx Integration ──────────────────────────────────────────
+let stockexMarketData = {};
+
+async function openStockExModal() {
+  if (!playerToken) return;
+  document.getElementById('stockex-modal').style.display = 'flex';
+  document.getElementById('sx-result').innerHTML = '';
+  // Load market data and symbols
+  try {
+    const res = await fetch(`${API_BASE}/stockex/market`);
+    if (res.ok) {
+      stockexMarketData = await res.json();
+      const sel = document.getElementById('sx-symbol');
+      const symbols = Object.keys(stockexMarketData).sort();
+      sel.innerHTML = symbols.map(s => `<option value="${s}">${s}</option>`).join('');
+      sel.value = 'EXAE'; // Default
+      updateStockExPrice();
+    }
+  } catch(e) {
+    document.getElementById('sx-market-info').textContent = 'Could not load market data';
+  }
+  loadStockExPortfolio();
+}
+
+function updateStockExPrice() {
+  const sym = document.getElementById('sx-symbol').value;
+  const mkt = stockexMarketData[sym];
+  if (mkt) {
+    const bid = mkt.bid_price || 0;
+    const ask = mkt.ask_price || 0;
+    const mid = mkt.mid || ((bid + ask) / 2);
+    document.getElementById('sx-price').value = mid.toFixed(2);
+    document.getElementById('sx-market-info').textContent =
+      `Bid: ${bid.toFixed(2)} | Ask: ${ask.toFixed(2)} | Mid: ${mid.toFixed(2)}`;
+  }
+}
+
+async function loadStockExPortfolio() {
+  const mid = document.getElementById('sx-member').value.trim().toUpperCase();
+  if (!mid) return;
+  try {
+    const res = await fetch(`${API_BASE}/stockex/portfolio/${mid}`);
+    if (res.ok) {
+      const data = await res.json();
+      const cap = data.capital || 0;
+      const pnl = data.pnl || 0;
+      const pnlColor = pnl >= 0 ? '#4ecca3' : '#e74c3c';
+      let html = `<div style="margin-bottom:4px"><b>${data.member_id}</b> Capital: <b>${cap.toFixed(2)}</b> | P&L: <span style="color:${pnlColor}">${pnl.toFixed(2)}</span></div>`;
+      const holdings = data.holdings || [];
+      if (holdings.length > 0) {
+        html += '<div style="display:flex;flex-wrap:wrap;gap:4px">';
+        for (const h of holdings) {
+          const pnlH = h.unrealized_pnl || 0;
+          const c = pnlH >= 0 ? '#4ecca3' : '#e74c3c';
+          html += `<span style="padding:1px 4px;background:#1a1a3e;border-radius:3px;font-size:10px">${h.symbol}: ${h.quantity} <span style="color:${c}">(${pnlH > 0 ? '+' : ''}${pnlH.toFixed(0)})</span></span>`;
+        }
+        html += '</div>';
+      }
+      document.getElementById('stockex-portfolio').innerHTML = html;
+      document.getElementById('stockex-status').textContent = `${holdings.length} positions | Obligation: ${data.obligation || 20}/day`;
+    } else {
+      document.getElementById('stockex-portfolio').innerHTML = '<span style="color:#e74c3c">Member not found</span>';
+    }
+  } catch(e) {
+    document.getElementById('stockex-portfolio').innerHTML = '<span style="color:#e74c3c">Could not load portfolio</span>';
+  }
+}
+
+async function submitStockExOrder() {
+  if (!playerToken) return;
+  const resultEl = document.getElementById('sx-result');
+  const body = {
+    token: playerToken,
+    member_id: document.getElementById('sx-member').value.trim().toUpperCase(),
+    symbol: document.getElementById('sx-symbol').value,
+    side: document.getElementById('sx-side').value,
+    quantity: parseInt(document.getElementById('sx-qty').value) || 0,
+    price: parseFloat(document.getElementById('sx-price').value) || 0,
+  };
+  if (body.quantity <= 0 || body.price <= 0) {
+    resultEl.innerHTML = '<span style="color:#e74c3c">Invalid quantity or price</span>';
+    return;
+  }
+  resultEl.innerHTML = '<span style="color:#888">Placing order...</span>';
+  try {
+    const res = await fetch(`${API_BASE}/stockex/order`, {
+      method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(body)
+    });
+    const data = await res.json();
+    if (res.ok) {
+      resultEl.innerHTML = `<span style="color:#4ecca3">${esc(data.detail)} — ${data.cl_ord_id}</span>`;
+      loadStockExPortfolio(); // Refresh
+    } else {
+      resultEl.innerHTML = `<span style="color:#e74c3c">${esc(data.detail || data.error || 'Order failed')}</span>`;
+    }
+  } catch(e) {
+    resultEl.innerHTML = '<span style="color:#e74c3c">Connection error</span>';
+  }
+}
+
+// Update price when symbol changes
+document.getElementById('sx-symbol')?.addEventListener('change', updateStockExPrice);
+document.getElementById('sx-member')?.addEventListener('change', loadStockExPortfolio);
+
 // Chat with an NPC
 function openChat(targetId) {
   chatTargetId = targetId;