From 4bc5c9bab54f2c0332cf9a428d7cbb42393d5b2f Mon Sep 17 00:00:00 2001
From: 0xMegie <koanprotocol@gmail.com>
Date: Sun, 18 Oct 2026 13:54:55 +0100
Subject: [PATCH] Add realtime burst simulation and related functionality

- Implemented a burst simulator for realtime feeds in `scripts/realtime-burst.mjs`.
- Created batching functionality in `lib/realtime/batch.ts` to handle event coalescing.
- Added burst detection and handling in `lib/realtime/burst.ts` and `lib/realtime/useBurst.ts`.
- Developed a ring buffer implementation in `lib/realtime/ring.ts` for managing event history.
- Introduced tests for batching, burst detection, and ring buffer in `lib/realtime/__tests__/`.
- Enhanced event handling in `lib/stellar/events.ts` for trade events and added decoding logic.
- Updated optimistic transaction handling in `lib/stellar/optimistic.ts` to manage provisional updates.
- Modified transaction lifecycle management in `lib/stellar/tx-lifecycle.ts` to include ledger information.
- Added utility functions for simulated transactions in `lib/stellar/typed-call.ts`.
---
 CONTRIBUTING.md                              |  14 +
 app/layout.tsx                               |  12 +-
 app/markets/page.tsx                         |  84 ++--
 app/markets/quick-view/page.tsx              |  40 +-
 app/notifications/page.tsx                   | 388 +++++++++++--------
 app/page.tsx                                 | 112 ++++--
 components/layout/Navbar.tsx                 |  18 +-
 components/layout/WalletDropdown.tsx         |  11 +-
 components/market/trade-tape.tsx             | 159 ++++++++
 docs/STATUS.md                               |  12 +
 docs/architecture.md                         |  20 +
 docs/manual-test.md                          |  15 +
 lib/hooks/__tests__/marketTrades.test.ts     |  45 +++
 lib/hooks/marketTrades.ts                    |  50 +++
 lib/hooks/useMarketTrades.ts                 |  57 +++
 lib/hooks/useStellar.ts                      | 295 +++++++++++++-
 lib/notifications/InboxProvider.tsx          | 276 +++++++++++++
 lib/notifications/__tests__/classify.test.ts |  65 ++++
 lib/notifications/__tests__/store.test.ts    |  62 +++
 lib/notifications/classify.ts                | 122 ++++++
 lib/notifications/store.ts                   | 227 +++++++++++
 lib/realtime/FeedProfiler.tsx                |  45 +++
 lib/realtime/RealtimeProvider.tsx            | 104 +++++
 lib/realtime/__tests__/batch.test.ts         |  65 ++++
 lib/realtime/__tests__/burst.test.ts         |  27 ++
 lib/realtime/__tests__/ring.test.ts          |  22 ++
 lib/realtime/batch.ts                        | 103 +++++
 lib/realtime/burst.ts                        |  33 ++
 lib/realtime/ring.ts                         |  47 +++
 lib/realtime/useBurst.ts                     |  45 +++
 lib/stellar/__tests__/events.test.ts         |  90 +++++
 lib/stellar/__tests__/optimistic.test.ts     |  73 ++++
 lib/stellar/events.ts                        | 286 ++++++++++++++
 lib/stellar/optimistic.ts                    | 100 +++++
 lib/stellar/tx-lifecycle.ts                  |   8 +-
 lib/stellar/typed-call.ts                    |  13 +
 scripts/realtime-burst.mjs                   |  71 ++++
 37 files changed, 2940 insertions(+), 276 deletions(-)
 create mode 100644 components/market/trade-tape.tsx
 create mode 100644 lib/hooks/__tests__/marketTrades.test.ts
 create mode 100644 lib/hooks/marketTrades.ts
 create mode 100644 lib/hooks/useMarketTrades.ts
 create mode 100644 lib/notifications/InboxProvider.tsx
 create mode 100644 lib/notifications/__tests__/classify.test.ts
 create mode 100644 lib/notifications/__tests__/store.test.ts
 create mode 100644 lib/notifications/classify.ts
 create mode 100644 lib/notifications/store.ts
 create mode 100644 lib/realtime/FeedProfiler.tsx
 create mode 100644 lib/realtime/RealtimeProvider.tsx
 create mode 100644 lib/realtime/__tests__/batch.test.ts
 create mode 100644 lib/realtime/__tests__/burst.test.ts
 create mode 100644 lib/realtime/__tests__/ring.test.ts
 create mode 100644 lib/realtime/batch.ts
 create mode 100644 lib/realtime/burst.ts
 create mode 100644 lib/realtime/ring.ts
 create mode 100644 lib/realtime/useBurst.ts
 create mode 100644 lib/stellar/__tests__/events.test.ts
 create mode 100644 lib/stellar/__tests__/optimistic.test.ts
 create mode 100644 lib/stellar/events.ts
 create mode 100644 lib/stellar/optimistic.ts
 create mode 100644 scripts/realtime-burst.mjs

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9adb7df..630269c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -37,6 +37,20 @@ npm run build
 `npm run e2e:testnet` is an optional, read-only check against a running
 backend and live testnet; see the header of `e2e/testnet.e2e.test.ts`.
 
+## Realtime burst testing
+
+`scripts/realtime-burst.mjs` emits synthetic `TRADE_EXECUTED` events so you can
+check that realtime feeds stay smooth under bursts (issue #41):
+
+```bash
+npm i --no-save socket.io@4.8.1          # server package, not a project dependency
+node scripts/realtime-burst.mjs --count 500 --rate 500 --port 4100
+NEXT_PUBLIC_API_URL=http://localhost:4100/api/v1 npm run dev
+```
+
+Open `/markets?profile=1` or `/?profile=1`: in development the feeds log commit
+counts and render time per second to the console (`[profile] …`).
+
 ## When the contracts change
 
 The contracts live in
diff --git a/app/layout.tsx b/app/layout.tsx
index 3204a21..533a546 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -3,6 +3,8 @@ import type { Metadata } from "next";
 import Navbar from "@/components/layout/Navbar";
 import { Footer } from "@/components/layout/Footer";
 import { WalletProvider } from "@/lib/contexts/WalletContext";
+import { RealtimeProvider } from "@/lib/realtime/RealtimeProvider";
+import { InboxProvider } from "@/lib/notifications/InboxProvider";
 import "./globals.css";
 
 const geistSans = {
@@ -40,9 +42,13 @@ export default function RootLayout({
       </head>
       <body className="min-h-full flex flex-col font-body-md text-on-surface">
         <WalletProvider>
-          <Navbar />
-          {children}
-          <Footer />
+          <RealtimeProvider>
+            <InboxProvider>
+              <Navbar />
+              {children}
+              <Footer />
+            </InboxProvider>
+          </RealtimeProvider>
         </WalletProvider>
       </body>
     </html>
diff --git a/app/markets/page.tsx b/app/markets/page.tsx
index 91c5103..d1e9b26 100644
--- a/app/markets/page.tsx
+++ b/app/markets/page.tsx
@@ -1,15 +1,16 @@
 "use client";
 
-import React, { useState, useEffect } from "react";
-import { motion, AnimatePresence } from "framer-motion";
+import React, { useState } from "react";
+import { motion, AnimatePresence, MotionConfig } from "framer-motion";
 import Link from "next/link";
-import { io } from "socket.io-client";
 import { useMarkets } from "@/lib/hooks/useMarkets";
 import { useOnChainMarket, useOnChainMarkets, type OnChainMarketView } from "@/lib/hooks/useStellar";
 import type { Market, MarketStatus, MarketTracePreview } from "@/lib/api/markets";
 import { BACKEND_CATEGORIES, BACKEND_CATEGORY_LABELS } from "@/lib/stellar/categories";
 import { formatUsdc } from "@/lib/stellar/units";
-import { API_URL } from "@/lib/api/client";
+import { useBurstFeed } from "@/lib/realtime/useBurst";
+import { FeedProfiler } from "@/lib/realtime/FeedProfiler";
+import type { TradeExecutedPayload } from "@/lib/realtime/RealtimeProvider";
 
 /** Where a displayed value came from, wherever backend and chain can disagree. */
 const SourceTag = ({ source }: { source: "chain" | "backend" }) => (
@@ -194,40 +195,27 @@ interface FeedRow {
 }
 
 /** Payload of the backend's TRADE_EXECUTED socket event (docs/api.md). */
-interface TradeExecutedEvent {
-  eventId: string;
-  onChainMarketId: string;
-  marketQuestion: string | null;
-  direction: "YES" | "NO";
-  isBuy: boolean;
-  collateralRaw: string;
-  priceYesBps: number;
-}
+const tradeToRow = (data: TradeExecutedPayload): FeedRow => ({
+  key: `trade:${data.eventId}`,
+  // Receipt time: the socket payload has a ledger but no close time.
+  time: new Date().toLocaleTimeString("en-GB", { hour12: false }),
+  market: data.marketQuestion || `Market #${data.onChainMarketId}`,
+  size: `$${formatUsdc(BigInt(data.collateralRaw), { maxDecimals: 2, grouping: true })}`,
+  bet: `${data.isBuy ? "" : "SELL "}${data.direction}`,
+  prob: `YES ${(data.priceYesBps / 100).toFixed(1)}%`,
+  color: data.direction === "YES" ? "text-secondary" : "text-tertiary",
+});
+const rowKey = (row: FeedRow) => row.key;
 
 const TradingFeed = () => {
-  const [feed, setFeed] = useState<FeedRow[]>([]);
-
-  useEffect(() => {
-    const socket = io(API_URL.replace(/\/api\/v1\/?$/, ""));
-
-    socket.on("TRADE_EXECUTED", (data: TradeExecutedEvent) => {
-      const time = new Date().toLocaleTimeString('en-GB', { hour12: false });
-      const newEntry: FeedRow = {
-        key: data.eventId,
-        time,
-        market: data.marketQuestion || `Market #${data.onChainMarketId}`,
-        size: `$${formatUsdc(BigInt(data.collateralRaw), { maxDecimals: 2, grouping: true })}`,
-        bet: `${data.isBuy ? "" : "SELL "}${data.direction}`,
-        prob: `YES ${(data.priceYesBps / 100).toFixed(1)}%`,
-        color: data.direction === "YES" ? "text-secondary" : "text-tertiary",
-      };
-      setFeed(prev => [newEntry, ...prev.slice(0, 7)]);
-    });
-
-    return () => {
-      socket.disconnect();
-    };
-  }, []);
+  const { rows: feed, burst, hiddenOverflow, instantKey } = useBurstFeed("TRADE_EXECUTED", {
+    capacity: 8,
+    toRow: tradeToRow,
+    key: rowKey,
+  });
+  // A burst or a catch-up batch remounts the tbody so rows appear without
+  // per-row enter/exit animations (initial={false} only applies on mount).
+  const instant = burst !== null || hiddenOverflow > 0;
 
   return (
     <section className="mt-12">
@@ -235,6 +223,7 @@ const TradingFeed = () => {
         <span className="material-symbols-outlined text-primary">analytics</span>
         <h2 className="font-headline-sm text-headline-sm uppercase tracking-tight">Real-time Trading Feed</h2>
       </div>
+      <MotionConfig reducedMotion="user">
       <div className="terminal-log-flow border border-outline-variant rounded-xl overflow-hidden bg-white">
         <div className="p-4 overflow-x-auto">
           <table className="w-full text-left">
@@ -247,7 +236,21 @@ const TradingFeed = () => {
                 <th className="pb-3 text-label-caps text-on-surface-variant text-right">Probability</th>
               </tr>
             </thead>
-            <tbody className="font-data-mono text-body-md">
+            <tbody key={instantKey} className="font-data-mono text-body-md">
+              {burst && (
+                <tr>
+                  <td colSpan={5} className="py-2 text-on-surface-variant text-xs" role="status">
+                    {burst.count} trades in the last second
+                  </td>
+                </tr>
+              )}
+              {hiddenOverflow > 0 && (
+                <tr>
+                  <td colSpan={5} className="py-2 text-on-surface-variant text-xs" role="status">
+                    {hiddenOverflow} more events while this tab was hidden
+                  </td>
+                </tr>
+              )}
               <AnimatePresence initial={false}>
                 {feed.length === 0 && (
                   <tr>
@@ -257,9 +260,9 @@ const TradingFeed = () => {
                 {feed.map((row) => (
                   <motion.tr 
                     key={row.key}
-                    initial={{ opacity: 0, x: -20 }}
+                    initial={instant ? false : { opacity: 0, x: -20 }}
                     animate={{ opacity: 1, x: 0 }}
-                    exit={{ opacity: 0, x: 20 }}
+                    exit={instant ? undefined : { opacity: 0, x: 20 }}
                     className="hover:bg-surface-container transition-colors border-b border-outline-variant/30"
                   >
                     <td className="py-3 text-on-surface-variant">{row.time}</td>
@@ -274,6 +277,7 @@ const TradingFeed = () => {
           </table>
         </div>
       </div>
+      </MotionConfig>
     </section>
   );
 };
@@ -376,7 +380,7 @@ export default function Markets() {
 
         <OnChainOnlyMarkets knownIds={knownIds} />
 
-        <TradingFeed />
+        <FeedProfiler id="TradingFeed"><TradingFeed /></FeedProfiler>
       </main>
     </div>
   );
diff --git a/app/markets/quick-view/page.tsx b/app/markets/quick-view/page.tsx
index 0fc5bea..33aa485 100644
--- a/app/markets/quick-view/page.tsx
+++ b/app/markets/quick-view/page.tsx
@@ -8,11 +8,14 @@ import { useQuery } from "@tanstack/react-query";
 import { useMarket } from "@/lib/hooks/useMarkets";
 import { getMarketByOnChainId } from "@/lib/api/markets";
 import { ApiError } from "@/lib/api/client";
-import { useBuy, useOnChainMarket, usePosition, useQuoteBuy, useUsdcBalance, useAccountReserve, usePrepareBuy } from "@/lib/hooks/useStellar";
+import { useBuy, useOnChainMarket, usePosition, usePositionState, useQuoteBuy, useUsdcBalance, useAccountReserve, usePrepareBuy } from "@/lib/hooks/useStellar";
 import { useWallet } from "@/lib/contexts/WalletContext";
 import { explorerTx } from "@/lib/stellar/config";
 import { formatUsdc, minOut, tryParseUsdc } from "@/lib/stellar/units";
 import { buyBreakdown } from "@/lib/stellar/buy-breakdown";
+import { TradeTape } from "@/components/market/trade-tape";
+import { useInbox } from "@/lib/notifications/InboxProvider";
+import { UserFacingError } from "@/lib/stellar/errors";
 
 const SLIPPAGE_BPS = 100; // 1%
 
@@ -89,6 +92,9 @@ function MarketQuickViewContent() {
 
   const { address, isConnected, isWrongNetwork, openModal } = useWallet();
   const position = usePosition(onChainMarketId, address);
+  const positionState = usePositionState(onChainMarketId, address);
+  const { recordTx } = useInbox();
+  const provisional = positionState.data?.provisional;
   const balance = useUsdcBalance(address);
   const reserve = useAccountReserve(address);
   const buy = useBuy();
@@ -201,6 +207,16 @@ function MarketQuickViewContent() {
       );
     } catch (err) {
       setBuyStatus(err instanceof Error ? err.message : "The trade didn't go through.");
+      // Same deterministic id as the tracker's record when a hash exists.
+      if (err instanceof UserFacingError) {
+        recordTx({
+          hash: "hash" in buy.phase && buy.phase.hash ? buy.phase.hash : null,
+          kind: "buy",
+          marketId: String(onChainMarketId),
+          errorKind: err.described.kind,
+          message: err.message,
+        });
+      }
     }
   };
 
@@ -478,7 +494,25 @@ function MarketQuickViewContent() {
                     {position.data && (position.data.yes > 0n || position.data.no > 0n) && (
                       <p className="text-[11px] font-data-mono text-on-surface">
                         Your position: {formatUsdc(position.data.yes, { maxDecimals: 2 })} YES · {formatUsdc(position.data.no, { maxDecimals: 2 })} NO
-                        <SourceTag source="chain" />
+                        {provisional ? (
+                          <>
+                            <span className="ml-1 text-on-surface-variant">
+                              {provisional.awaitingRpc ? "awaiting RPC" : "pending confirmation"}
+                            </span>
+                            {provisional.txHash ? (
+                              <a
+                                href={explorerTx(provisional.txHash)}
+                                target="_blank"
+                                rel="noopener noreferrer"
+                                className="ml-1 text-[9px] uppercase tracking-wider text-primary hover:underline"
+                              >
+                                tx
+                              </a>
+                            ) : null}
+                          </>
+                        ) : (
+                          <SourceTag source="chain" />
+                        )}
                       </p>
                     )}
 
@@ -506,6 +540,8 @@ function MarketQuickViewContent() {
                   </div>
                 )}
 
+                {onChainMarketId !== null && <TradeTape onChainMarketId={String(onChainMarketId)} limit={20} compact />}
+
                 {/* AI Reasoning Snippet */}
                 <div className="bg-[#f0f9fa] border border-primary-container/20 p-4 rounded-lg space-y-2 relative overflow-hidden">
                   <div className="flex items-center gap-2 text-primary z-10 relative">
diff --git a/app/notifications/page.tsx b/app/notifications/page.tsx
index f970c39..d705c86 100644
--- a/app/notifications/page.tsx
+++ b/app/notifications/page.tsx
@@ -1,217 +1,279 @@
 "use client";
 
-import React, { useState, useEffect, useMemo } from "react";
+import React, { useEffect, useMemo, useRef, useState } from "react";
 import Link from "next/link";
-import { io } from "socket.io-client";
-import { usePositions } from "@/lib/hooks/usePortfolio";
-import { API_URL } from "@/lib/api/client";
-import { explorerTx } from "@/lib/stellar/config";
+import { useInbox } from "@/lib/notifications/InboxProvider";
+import type { InboxItem, InboxKind } from "@/lib/notifications/store";
+import { explorerTx, NETWORK_LABEL } from "@/lib/stellar/config";
 import { formatUsdc } from "@/lib/stellar/units";
 
-type NotificationType = "all" | "critical" | "trading" | "ai";
+type Filter = "all" | "trades" | "redemptions" | "reasoning" | "transactions";
 
-interface NotificationItem {
-  id: string;
-  type: Exclude<NotificationType, "all">;
+const FILTER_OF: Record<InboxKind, Exclude<Filter, "all">> = {
+  fill: "trades",
+  redeemable: "redemptions",
+  redeemed: "redemptions",
+  trace: "reasoning",
+  "tx-failed": "transactions",
+  "tx-pending": "transactions",
+};
+
+const FILTERS: { type: Filter; label: string; icon: string }[] = [
+  { type: "all", label: "All", icon: "dashboard" },
+  { type: "trades", label: "Trades", icon: "payments" },
+  { type: "redemptions", label: "Redemptions", icon: "redeem" },
+  { type: "reasoning", label: "Reasoning", icon: "psychology" },
+  { type: "transactions", label: "Transactions", icon: "receipt_long" },
+];
+
+/** Live items rendered at once; the store itself keeps up to 500 per wallet. */
+const RENDER_CAP = 200;
+/** An item counts as read after this long fully in view. 0 disables it. */
+const AUTO_READ_MS = 1_000;
+
+const usdc = (raw: string | undefined) => {
+  if (!raw || !/^\d+$/.test(raw)) return "—";
+  return formatUsdc(BigInt(raw), { maxDecimals: 2, grouping: true });
+};
+
+interface View {
   title: string;
   message: string;
-  time: string;
-  timestamp: number;
-  payout?: string;
-  txHash?: string;
-  probability?: number;
   icon: string;
-  iconBg: string;
-  iconColor: string;
-  borderColor: string;
+  tone: string;
+  border: string;
 }
 
-
-export default function NotificationsPage() {
-  const [filter, setFilter] = useState<NotificationType>("all");
-  const [liveNotifications, setLiveNotifications] = useState<NotificationItem[]>([]);
-  const [clearedBefore, setClearedBefore] = useState(0);
-  const { data: positionsData } = usePositions({ limit: 10 });
-
-  // Positions become notifications; live socket events are added on top.
-  const localNotifications = useMemo(() => {
-      const positionNotifications: NotificationItem[] = (positionsData?.positions ?? []).map(pos => ({
-        id: `pos-${pos.id}`,
-        type: "trading",
-        title: "Trade Confirmed",
-        message: `${pos.status === 'CLOSED' ? 'Closed' : 'Opened'} ${pos.direction} position on "${pos.market.question}" for ${pos.size.toLocaleString()} USDC.`,
-        time: new Date(pos.createdAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }),
-        timestamp: new Date(pos.createdAt).getTime(),
-        txHash: pos.trade?.txHash || undefined,
-        icon: pos.status === 'CLOSED' ? "history" : "check_circle",
-        iconBg: "bg-secondary-fixed",
-        iconColor: "text-secondary",
-        borderColor: "border-l-secondary",
-      }));
-
-      return [...liveNotifications, ...positionNotifications]
-        .filter(n => n.timestamp > clearedBefore)
-        .sort((a, b) => b.timestamp - a.timestamp);
-  }, [positionsData, liveNotifications, clearedBefore]);
-
-  // Socket listener for real-time trades
-  useEffect(() => {
-    const socket = io(API_URL.replace(/\/api\/v1\/?$/, ""));
-
-    // Payload documented in docs/api.md (Realtime).
-    socket.on("TRADE_EXECUTED", (data: { eventId: string; direction: string; isBuy: boolean; onChainMarketId: string; marketQuestion: string | null; collateralRaw: string; txHash: string }) => {
-      const newNotif: NotificationItem = {
-        id: `socket-${data.eventId}`,
-        type: "trading",
-        title: "New Trade Executed",
-        message: `${data.isBuy ? "Bought" : "Sold"} ${data.direction} on ${data.marketQuestion ? `"${data.marketQuestion}"` : `market #${data.onChainMarketId}`} for ${formatUsdc(BigInt(data.collateralRaw), { maxDecimals: 2, grouping: true })} USDC.`,
-        time: "Just now",
-        timestamp: Date.now(),
-        txHash: data.txHash,
-        icon: "bolt",
-        iconBg: "bg-secondary-fixed",
-        iconColor: "text-secondary",
-        borderColor: "border-l-secondary",
+function describe(item: InboxItem): View {
+  const market = item.data.marketQuestion ? `"${item.data.marketQuestion}"` : `market #${item.marketId}`;
+  switch (item.kind) {
+    case "fill":
+      return {
+        title: item.data.side === "buy" ? "Buy filled" : "Sell filled",
+        message: `${item.data.side === "buy" ? "Bought" : "Sold"} ${usdc(item.data.sharesRaw)} ${item.data.direction} shares on ${market} for ${usdc(item.data.collateralRaw)} USDC.`,
+        icon: "check_circle",
+        tone: "text-secondary",
+        border: "border-l-secondary",
+      };
+    case "redeemable":
+      return {
+        title: item.data.outcome === "void" ? "Market voided — redeemable" : "Market resolved — redeemable",
+        message:
+          item.data.outcome === "void"
+            ? `Market #${item.marketId} was voided. Each side redeems at half value.`
+            : `Market #${item.marketId} resolved ${String(item.data.outcome).toUpperCase()}. You hold ${usdc(item.data.yes)} YES · ${usdc(item.data.no)} NO.`,
+        icon: "redeem",
+        tone: "text-primary",
+        border: "border-l-primary",
+      };
+    case "redeemed":
+      return {
+        title: "Redeemed",
+        message: `Redeemed market #${item.marketId} for ${usdc(item.data.payoutRaw)} USDC.`,
+        icon: "savings",
+        tone: "text-secondary",
+        border: "border-l-secondary",
+      };
+    case "trace":
+      return {
+        title: "New agent reasoning",
+        message: `Trace #${item.data.onChainTraceId} (${item.data.action || "update"}) was published on market #${item.marketId}, which you hold.`,
+        icon: "psychology",
+        tone: "text-primary",
+        border: "border-l-primary",
+      };
+    case "tx-failed":
+      return {
+        title: "Transaction failed",
+        message: `Your ${item.data.action} ${item.marketId ? `on market #${item.marketId} ` : ""}failed${item.data.message ? `: ${item.data.message}` : "."}`,
+        icon: "error",
+        tone: "text-tertiary",
+        border: "border-l-tertiary",
       };
-      setLiveNotifications(prev => [newNotif, ...prev]);
-    });
+    case "tx-pending":
+      return {
+        title: "Transaction pending",
+        message: `Your ${item.data.action} ${item.marketId ? `on market #${item.marketId} ` : ""}is waiting for a ledger.`,
+        icon: "hourglass_top",
+        tone: "text-on-surface-variant",
+        border: "border-l-outline",
+      };
+  }
+}
+
+function NotificationRow({ item, onRead }: { item: InboxItem; onRead: (id: string) => void }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const unread = item.readAt === null;
+  const view = describe(item);
 
+  // Mark read only after the item has been fully visible for AUTO_READ_MS.
+  useEffect(() => {
+    const el = ref.current;
+    if (!unread || !el || AUTO_READ_MS <= 0 || typeof IntersectionObserver === "undefined") return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const io = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting && entry.intersectionRatio >= 0.99) {
+          timer ??= setTimeout(() => onRead(item.id), AUTO_READ_MS);
+        } else if (timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      },
+      { threshold: [0, 1] },
+    );
+    io.observe(el);
     return () => {
-      socket.disconnect();
+      io.disconnect();
+      if (timer) clearTimeout(timer);
     };
-  }, []);
+  }, [unread, item.id, onRead]);
 
-  const filteredNotifications = localNotifications.filter(
-    (item) => filter === "all" || item.type === filter
+  return (
+    <div
+      ref={ref}
+      className={`group bg-surface-container-lowest border-l-4 ${view.border} border-y border-r border-outline-variant p-4 rounded-r flex gap-4 shadow-sm ${unread ? "" : "opacity-75"}`}
+    >
+      <div className="flex-shrink-0 w-10 h-10 rounded-full bg-surface-container flex items-center justify-center">
+        <span className={`material-symbols-outlined ${view.tone}`} aria-hidden="true">{view.icon}</span>
+      </div>
+      <div className="flex-grow min-w-0">
+        <div className="flex justify-between items-start gap-2">
+          <h3 className={`font-headline-sm text-headline-sm ${view.tone}`}>
+            {unread && <span className="sr-only">Unread: </span>}
+            {view.title}
+          </h3>
+          <span className="font-data-mono text-data-mono text-on-surface-variant text-[12px] whitespace-nowrap" title={item.ledger ? `Ledger ${item.ledger}` : "Receipt time"}>
+            {new Date(item.createdAt).toLocaleString([], { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" })}
+          </span>
+        </div>
+        <p className="text-body-md mt-1 text-on-surface break-words">{view.message}</p>
+        <div className="mt-2 flex flex-wrap items-center gap-3">
+          {item.marketId && (
+            <Link href={`/markets/quick-view?onChainId=${item.marketId}`} className="text-xs text-primary font-bold hover:underline">
+              {item.kind === "redeemable" ? "Redeem" : "Open market"}
+            </Link>
+          )}
+          {item.txHash && (
+            <a href={explorerTx(item.txHash)} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1 hover:opacity-80">
+              <span className="text-xs font-data-mono bg-surface-container px-2 py-0.5 rounded text-on-surface-variant">TX: {item.txHash.substring(0, 10)}…</span>
+              <span className="material-symbols-outlined text-xs text-primary" aria-hidden="true">open_in_new</span>
+            </a>
+          )}
+          {unread && (
+            <button type="button" onClick={() => onRead(item.id)} className="text-xs text-on-surface-variant hover:text-primary hover:underline">
+              Mark read
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
   );
+}
+
+export default function NotificationsPage() {
+  const inbox = useInbox();
+  const [filter, setFilter] = useState<Filter>("all");
+  const { markRead } = inbox;
+  const onRead = useMemo(() => (id: string) => markRead([id]), [markRead]);
 
-  const filterButtons = [
-    { label: "All Notifications", type: "all" as const, icon: "dashboard", count: localNotifications.length },
-    { label: "Critical", type: "critical" as const, icon: "warning", count: localNotifications.filter(n => n.type === 'critical').length },
-    { label: "Trading", type: "trading" as const, icon: "payments", count: localNotifications.filter(n => n.type === 'trading').length },
-    { label: "AI Signals", type: "ai" as const, icon: "psychology", count: localNotifications.filter(n => n.type === 'ai').length },
-  ];
+  // One pass for all filter counts.
+  const counts = useMemo(() => {
+    const c: Record<Filter, number> = { all: 0, trades: 0, redemptions: 0, reasoning: 0, transactions: 0 };
+    for (const item of inbox.items) {
+      c.all++;
+      c[FILTER_OF[item.kind]]++;
+    }
+    return c;
+  }, [inbox.items]);
+
+  const visible = useMemo(
+    () => inbox.items.filter((i) => filter === "all" || FILTER_OF[i.kind] === filter).slice(0, RENDER_CAP),
+    [inbox.items, filter],
+  );
 
   return (
     <main className="flex-grow pt-8 pb-12 px-gutter max-w-container-max-width mx-auto w-full">
       <div className="grid grid-cols-12 gap-6">
-        {/* Left Column: Filter and Summary */}
         <div className="col-span-12 lg:col-span-3 space-y-6">
           <div className="bg-surface-container-lowest border border-outline-variant p-4 rounded shadow-sm">
-            <h2 className="font-headline-sm text-headline-sm mb-4">Activity</h2>
+            <h2 className="font-headline-sm text-headline-sm mb-4">Inbox</h2>
             <div className="space-y-1">
-              {filterButtons.map((btn) => (
+              {FILTERS.map((btn) => (
                 <button
                   key={btn.type}
+                  type="button"
                   onClick={() => setFilter(btn.type)}
+                  aria-pressed={filter === btn.type}
                   className={`w-full flex items-center justify-between p-2 rounded transition-all duration-200 cursor-pointer ${
-                    filter === btn.type
-                      ? "text-primary bg-surface-container-low font-bold"
-                      : "text-on-surface-variant hover:bg-surface-container"
+                    filter === btn.type ? "text-primary bg-surface-container-low font-bold" : "text-on-surface-variant hover:bg-surface-container"
                   }`}
                 >
                   <span className="flex items-center gap-2">
-                    <span className={`material-symbols-outlined text-[20px] ${
-                      btn.type === 'critical' ? 'text-tertiary' : 
-                      btn.type === 'trading' ? 'text-secondary' : 
-                      btn.type === 'ai' ? 'text-primary' : ''
-                    }`}>
-                      {btn.icon}
-                    </span>
+                    <span className="material-symbols-outlined text-[20px]" aria-hidden="true">{btn.icon}</span>
                     {btn.label}
                   </span>
-                  <span className="text-xs bg-surface-container-high px-2 py-0.5 rounded-full">
-                    {btn.count}
-                  </span>
+                  <span className="text-xs bg-surface-container-high px-2 py-0.5 rounded-full">{counts[btn.type]}</span>
                 </button>
               ))}
             </div>
           </div>
           <div className="bg-surface-container-low border border-outline-variant p-4 rounded bg-gradient-to-br from-[#f0f9fa] to-[#e0f2f4]">
             <div className="flex items-center gap-2 mb-2">
-              <span className="material-symbols-outlined text-primary" style={{ fontVariationSettings: "'FILL' 1" }}>
-                auto_awesome
+              <span className="material-symbols-outlined text-primary" style={{ fontVariationSettings: "'FILL' 1" }} aria-hidden="true">
+                info
               </span>
-              <span className="font-label-caps text-label-caps text-primary">ORACLE INSIGHT</span>
+              <span className="font-label-caps text-label-caps text-primary">WHAT SHOWS UP HERE</span>
             </div>
-            <p className="text-body-md text-on-surface-variant leading-relaxed italic">
-              Live trades from the OracleDesk contracts on Stellar Testnet, plus agent positions.
+            <p className="text-body-md text-on-surface-variant leading-relaxed">
+              Only events for your connected wallet on {NETWORK_LABEL}: your own fills, markets you hold resolving or being voided,
+              your redemptions, new agent reasoning on markets you hold, and your failed or pending transactions. Read state is
+              saved in this browser.
             </p>
           </div>
         </div>
 
-        {/* Middle Column: Main Feed */}
         <div className="col-span-12 lg:col-span-9 space-y-4">
           <div className="flex justify-between items-center mb-2">
-            <h1 className="font-headline-md text-headline-md">Alert Center</h1>
-            <button 
-              onClick={() => { setLiveNotifications([]); setClearedBefore(Date.now()); }}
-              className="text-primary font-label-caps text-label-caps hover:underline cursor-pointer"
-            >
-              Clear all
-            </button>
-          </div>
-
-          <div className="space-y-3">
-            {filteredNotifications.map((item) => (
-              <div
-                key={item.id}
-                className={`group bg-surface-container-lowest border-l-4 ${item.borderColor} border-y border-r border-outline-variant p-4 rounded-r flex gap-4 hover:bg-white hover:translate-x-1 transition-all duration-200 cursor-pointer shadow-sm`}
+            <h1 className="font-headline-md text-headline-md">Notifications</h1>
+            {inbox.owner && (
+              <button
+                type="button"
+                onClick={inbox.markAllRead}
+                disabled={inbox.unread === 0}
+                className="text-primary font-label-caps text-label-caps hover:underline cursor-pointer disabled:opacity-50 disabled:no-underline"
               >
-                <div className={`flex-shrink-0 w-10 h-10 rounded-full ${item.iconBg} flex items-center justify-center`}>
-                  <span className={`material-symbols-outlined ${item.iconColor}`}>
-                    {item.icon}
-                  </span>
-                </div>
-                <div className="flex-grow">
-                  <div className="flex justify-between items-start">
-                    <h3 className={`font-headline-sm text-headline-sm ${item.iconColor}`}>
-                      {item.title}
-                    </h3>
-                    <span className="font-data-mono text-data-mono text-on-surface-variant text-[12px]">
-                      {item.time}
-                    </span>
-                  </div>
-                  <p className="text-body-md mt-1 text-on-surface">
-                    {item.message}
-                  </p>
-                  
-                  {item.probability !== undefined && (
-                    <div className="mt-3">
-                      <div className="w-full bg-surface-container h-1 rounded overflow-hidden">
-                        <div 
-                          className="bg-primary h-full transition-all duration-1000" 
-                          style={{ width: `${item.probability}%` }}
-                        ></div>
-                      </div>
-                    </div>
-                  )}
-
-                  {item.txHash && (
-                    <a 
-                      href={explorerTx(item.txHash)} 
-                      target="_blank" 
-                      rel="noopener noreferrer"
-                      className="mt-2 inline-flex items-center gap-2 hover:opacity-80 transition-opacity"
-                    >
-                      <span className="text-xs font-data-mono bg-surface-container px-2 py-0.5 rounded text-on-surface-variant">
-                        TX: {item.txHash.substring(0, 10)}...
-                      </span>
-                      <span className="material-symbols-outlined text-xs text-primary">
-                        open_in_new
-                      </span>
-                    </a>
-                  )}
-                </div>
-              </div>
-            ))}
-            
-            {filteredNotifications.length === 0 && (
-              <div className="text-center py-12 bg-white border border-dashed border-outline-variant rounded-lg">
-                <p className="text-on-surface-variant">No active alerts. Monitoring the network...</p>
-              </div>
+                Mark all read
+              </button>
             )}
           </div>
+
+          {inbox.owner && !inbox.persistent && (
+            <p className="text-xs text-on-surface-variant bg-surface-container px-3 py-2 rounded" role="status">
+              Notifications won&apos;t be saved in this browser.
+            </p>
+          )}
+
+          {inbox.status === "disconnected" ? (
+            <div className="text-center py-12 bg-white border border-dashed border-outline-variant rounded-lg">
+              <p className="text-on-surface-variant">Connect your wallet (top right) to see notifications for your address.</p>
+            </div>
+          ) : inbox.status === "loading" ? (
+            <div className="text-center py-12 bg-white border border-dashed border-outline-variant rounded-lg" aria-busy="true">
+              <p className="text-on-surface-variant">Loading your inbox…</p>
+            </div>
+          ) : (
+            <div className="space-y-3">
+              {visible.map((item) => (
+                <NotificationRow key={item.id} item={item} onRead={onRead} />
+              ))}
+              {visible.length === 0 && (
+                <div className="text-center py-12 bg-white border border-dashed border-outline-variant rounded-lg">
+                  <p className="text-on-surface-variant">Nothing here yet. Your fills, redemptions and transactions will show up here.</p>
+                </div>
+              )}
+            </div>
+          )}
         </div>
       </div>
     </main>
diff --git a/app/page.tsx b/app/page.tsx
index 164d216..bbd089f 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -1,16 +1,19 @@
 "use client";
 
-import React, { useState, useEffect, useRef } from "react";
+import React, { useState, useEffect, useRef, useMemo } from "react";
 import Link from "next/link";
-import { motion } from "framer-motion";
-import { io } from "socket.io-client";
+import { motion, useReducedMotion } from "framer-motion";
 import { useWallet } from "@/lib/contexts/WalletContext";
 import { useMarkets } from "@/lib/hooks/useMarkets";
-import { API_URL } from "@/lib/api/client";
+import { useBurstFeed } from "@/lib/realtime/useBurst";
+import { FeedProfiler } from "@/lib/realtime/FeedProfiler";
+import type { ReasoningPublishedPayload, TradeExecutedPayload } from "@/lib/realtime/RealtimeProvider";
 import { formatUsdc } from "@/lib/stellar/units";
 import { DemoBadge } from "@/components/ui/demo-badge";
 
 interface FeedItem {
+  key: string;
+  receivedAt: number;
   time: string;
   agent: string;
   action: string;
@@ -19,57 +22,69 @@ interface FeedItem {
   color: string;
 }
 
-const AgentActivityFeed = () => {
-  const [feed, setFeed] = useState<FeedItem[]>([]);
+// Socket payloads carry a ledger but no close time, so this is receipt time.
+const receiptTime = () => new Date().toLocaleTimeString("en-GB", { hour12: false });
 
-  useEffect(() => {
-    const socket = io(API_URL.replace(/\/api\/v1\/?$/, ""));
+const tradeToFeedItem = (data: TradeExecutedPayload): FeedItem => ({
+  key: `trade:${data.eventId}`,
+  receivedAt: Date.now(),
+  time: receiptTime(),
+  agent: "Trader",
+  action: data.isBuy ? "BUY" : "SELL",
+  details: `${data.direction} ${formatUsdc(BigInt(data.collateralRaw), { maxDecimals: 2, grouping: true })} USDC on #${data.onChainMarketId} · YES ${(data.priceYesBps / 100).toFixed(1)}%`,
+  chain: "Stellar",
+  color: "text-secondary",
+});
 
-    // Payloads are documented in docs/api.md (Realtime).
-    socket.on("TRADE_EXECUTED", (data: { direction: string; isBuy: boolean; collateralRaw: string; priceYesBps: number; onChainMarketId: string }) => {
-      const time = new Date().toLocaleTimeString('en-GB', { hour12: false });
-      setFeed(prev => [{
-        time,
-        agent: "Trader",
-        action: data.isBuy ? "BUY" : "SELL",
-        details: `${data.direction} ${formatUsdc(BigInt(data.collateralRaw), { maxDecimals: 2, grouping: true })} USDC on #${data.onChainMarketId} · YES ${(data.priceYesBps / 100).toFixed(1)}%`,
-        chain: "Stellar",
-        color: "text-secondary"
-      }, ...prev.slice(0, 5)]);
-    });
+const traceToFeedItem = (data: ReasoningPublishedPayload): FeedItem => ({
+  key: `trace:${data.onChainTraceId}`,
+  receivedAt: Date.now(),
+  time: receiptTime(),
+  agent: "Reasoner",
+  action: "PUBLISH_TRACE",
+  details: `Trace #${data.onChainTraceId} (${data.action})`,
+  chain: "Stellar",
+  color: "text-primary-fixed",
+});
 
-    socket.on("REASONING_PUBLISHED", (data: { onChainTraceId: string; action: string }) => {
-      const time = new Date().toLocaleTimeString('en-GB', { hour12: false });
-      setFeed(prev => [{
-        time,
-        agent: "Reasoner",
-        action: "PUBLISH_TRACE",
-        details: `Trace #${data.onChainTraceId} (${data.action})`,
-        chain: "Stellar",
-        color: "text-primary-fixed"
-      }, ...prev.slice(0, 5)]);
-    });
+const feedKey = (item: FeedItem) => item.key;
+const FEED_CAPACITY = 6;
 
-    return () => {
-      socket.disconnect();
-    };
-  }, []);
+const AgentActivityFeed = () => {
+  const trades = useBurstFeed("TRADE_EXECUTED", { capacity: FEED_CAPACITY, toRow: tradeToFeedItem, key: feedKey });
+  const traces = useBurstFeed("REASONING_PUBLISHED", { capacity: FEED_CAPACITY, toRow: traceToFeedItem, key: feedKey });
+  const feed = useMemo(
+    () => [...trades.rows, ...traces.rows].sort((a, b) => b.receivedAt - a.receivedAt).slice(0, FEED_CAPACITY),
+    [trades.rows, traces.rows],
+  );
+  const burst = trades.burst ?? traces.burst;
+  const hiddenOverflow = trades.hiddenOverflow + traces.hiddenOverflow;
 
   return (
     <div className="bg-on-background rounded-xl overflow-hidden shadow-2xl border border-outline border-opacity-30">
       <div className="px-6 py-4 border-b border-white/10 flex justify-between items-center bg-white/5">
         <div className="flex items-center gap-2">
-          <span className="material-symbols-outlined text-secondary animate-pulse">monitoring</span>
+          <span className="material-symbols-outlined text-secondary animate-pulse motion-reduce:animate-none">monitoring</span>
           <h3 className="font-headline-sm text-headline-sm text-white uppercase tracking-widest text-xs">Live Agent Activity</h3>
         </div>
-        <span className="text-white/30 text-[9px] font-data-mono uppercase">Stellar Testnet</span>
+        <span className="text-white/30 text-[9px] font-data-mono uppercase">Stellar Testnet · receipt time</span>
       </div>
       <div className="p-6 h-[320px] overflow-y-auto font-data-mono text-[11px] space-y-3 custom-scrollbar">
+        {burst && (
+          <p className="text-white/50" role="status">
+            {burst.count} events in the last second
+          </p>
+        )}
+        {hiddenOverflow > 0 && (
+          <p className="text-white/50" role="status">
+            {hiddenOverflow} more events while this tab was hidden
+          </p>
+        )}
         {feed.length === 0 && (
           <p className="text-white/40">Waiting for agent activity on-chain…</p>
         )}
-        {feed.map((item, i) => (
-          <div key={i} className="flex gap-4 border-l border-white/10 pl-4 py-1 hover:bg-white/5 transition-colors group">
+        {feed.map((item) => (
+          <div key={item.key} className="flex gap-4 border-l border-white/10 pl-4 py-1 hover:bg-white/5 transition-colors group">
             <span className="text-white/20 whitespace-nowrap">[{item.time}]</span>
             <span className="text-primary font-bold whitespace-nowrap">{item.agent}</span>
             <span className={`font-black ${item.color} whitespace-nowrap`}>{item.action}</span>
@@ -129,10 +144,25 @@ const Ticker = () => {
       })
     : ["NO LIVE MARKETS YET"];
 
+  const reduceMotion = useReducedMotion();
+
+  // Reduced motion: a static list, not a frozen half-scrolled marquee.
+  if (reduceMotion) {
+    return (
+      <div className="bg-on-background text-primary-fixed-dim py-2 border-b border-outline overflow-hidden">
+        <ul className="font-data-mono text-data-mono uppercase flex flex-wrap gap-x-8 gap-y-1 px-gutter">
+          {tickerItems.map((item) => (
+            <li key={item}>{item}</li>
+          ))}
+        </ul>
+      </div>
+    );
+  }
+
   return (
     <div className="bg-on-background text-primary-fixed-dim py-2 border-b border-outline overflow-hidden">
       <div className="ticker-wrap w-full">
-        <div className="ticker-content animate-ticker font-data-mono text-data-mono uppercase flex gap-8 whitespace-nowrap">
+        <div className="ticker-content animate-ticker motion-reduce:animate-none font-data-mono text-data-mono uppercase flex gap-8 whitespace-nowrap">
           {[...tickerItems, ...tickerItems, ...tickerItems].map((item, i) => (
             <span key={i}>{item} •</span>
           ))}
@@ -529,7 +559,7 @@ export default function Home() {
         <section className="bg-white py-12 border-b border-outline-variant">
           <div className="max-w-container-max-width mx-auto px-gutter grid lg:grid-cols-3 gap-8">
             <div className="lg:col-span-2">
-              <AgentActivityFeed />
+              <FeedProfiler id="AgentActivityFeed"><AgentActivityFeed /></FeedProfiler>
             </div>
             <div>
               <ProtocolActivity />
diff --git a/components/layout/Navbar.tsx b/components/layout/Navbar.tsx
index ba80518..95d691b 100644
--- a/components/layout/Navbar.tsx
+++ b/components/layout/Navbar.tsx
@@ -4,9 +4,11 @@ import React from "react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import WalletDropdown from "./WalletDropdown";
+import { useInbox } from "@/lib/notifications/InboxProvider";
 
 const Navbar = () => {
   const pathname = usePathname();
+  const { unread } = useInbox();
 
   const navLinks = [
     { 
@@ -94,14 +96,22 @@ const Navbar = () => {
           </nav>
         </div>
         <div className="flex items-center gap-4">
-          <Link 
+          <Link
             href="/notifications"
-            className={`material-symbols-outlined ${
+            aria-label={unread ? `Notifications, ${unread} unread` : "Notifications"}
+            className={`${
               pathname === "/notifications" ? "text-primary" : "text-on-surface-variant"
             } hover:text-primary transition-colors cursor-pointer relative pt-1`}
           >
-            notifications
-            <span className="absolute top-0 right-0 w-2 h-2 bg-tertiary rounded-full border border-white"></span>
+            <span className="material-symbols-outlined" aria-hidden="true">notifications</span>
+            {unread > 0 && (
+              <span
+                aria-hidden="true"
+                className="absolute -top-1 -right-2 min-w-[18px] h-[18px] px-1 bg-tertiary text-white text-[10px] font-bold leading-[18px] text-center rounded-full border border-white"
+              >
+                {unread > 99 ? "99+" : unread}
+              </span>
+            )}
           </Link>
           
           <WalletDropdown />
diff --git a/components/layout/WalletDropdown.tsx b/components/layout/WalletDropdown.tsx
index 0010e2d..cab07f9 100644
--- a/components/layout/WalletDropdown.tsx
+++ b/components/layout/WalletDropdown.tsx
@@ -3,7 +3,7 @@
 import React, { useState, useRef, useEffect } from "react";
 import { motion, AnimatePresence } from "framer-motion";
 import { useWallet } from "@/lib/contexts/WalletContext";
-import { useAccountReserve, useEnableUsdc, useRpcNetwork, useUsdcBalance, useUsdcTrustline } from "@/lib/hooks/useStellar";
+import { useAccountReserve, useEnableUsdc, useRpcNetwork, useUsdcBalance, useUsdcBalanceState, useUsdcTrustline } from "@/lib/hooks/useStellar";
 import { NETWORK_LABEL, NETWORK_PASSPHRASE, TESTNET_PASSPHRASE, explorerAccount } from "@/lib/stellar/config";
 import { formatUsdc, formatXlm, shortAddress } from "@/lib/stellar/units";
 
@@ -13,6 +13,7 @@ const WalletDropdown = () => {
   const [copied, setCopied] = useState(false);
   const dropdownRef = useRef<HTMLDivElement>(null);
   const balance = useUsdcBalance(address);
+  const balanceProvisional = useUsdcBalanceState(address).data?.provisional;
   const trustline = useUsdcTrustline(address);
   const enableUsdc = useEnableUsdc();
   const reserve = useAccountReserve(address);
@@ -122,6 +123,14 @@ const WalletDropdown = () => {
                 <span className="text-xl font-bold text-on-surface font-data-mono">
                   {balanceText}
                 </span>
+                {balanceProvisional && (
+                  <span
+                    role="status"
+                    aria-label="Balance pending on-chain confirmation"
+                    title="Pending on-chain confirmation"
+                    className="w-2 h-2 rounded-full bg-tertiary animate-pulse motion-reduce:animate-none self-center"
+                  />
+                )}
                 <span className="text-xs font-bold text-on-surface-variant uppercase">
                   USDC
                 </span>
diff --git a/components/market/trade-tape.tsx b/components/market/trade-tape.tsx
new file mode 100644
index 0000000..141ff61
--- /dev/null
+++ b/components/market/trade-tape.tsx
@@ -0,0 +1,159 @@
+"use client";
+
+import React, { useEffect, useRef, useState } from "react";
+import { useWallet } from "@/lib/contexts/WalletContext";
+import { useMarketTrades } from "@/lib/hooks/useMarketTrades";
+import { explorerAccount, explorerTx } from "@/lib/stellar/config";
+import { formatUsdc, shortAddress } from "@/lib/stellar/units";
+
+const ROW_HEIGHT = 32;
+const OVERSCAN = 8;
+const COLUMNS = ["Time", "Side", "Type", "Trader", "USDC", "Shares", "Fee", "Price after", "Tx"];
+
+function relativeTime(iso: string, now: number): string {
+  const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86_400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86_400)}d ago`;
+}
+
+/** Minimal fixed-row windowing: renders only rows in view plus overscan. */
+function useWindow(count: number) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [height, setHeight] = useState(ROW_HEIGHT * 10);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const ro = new ResizeObserver(() => setHeight(el.clientHeight));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const start = Math.max(0, Math.floor(scrollTop / ROW_HEIGHT) - OVERSCAN);
+  const end = Math.min(count, Math.ceil((scrollTop + height) / ROW_HEIGHT) + OVERSCAN);
+  return { ref, start, end, onScroll: (e: React.UIEvent<HTMLDivElement>) => setScrollTop(e.currentTarget.scrollTop) };
+}
+
+/**
+ * Per-market trade tape from market-core Trade events (issue #40).
+ * Side and buy/sell are text, not colour alone.
+ */
+export function TradeTape({ onChainMarketId, limit = 20, compact = false }: { onChainMarketId: string; limit?: number; compact?: boolean }) {
+  const { address } = useWallet();
+  const tape = useMarketTrades(onChainMarketId, { limit });
+  const { ref, start, end, onScroll } = useWindow(tape.rows.length);
+  const [now, setNow] = useState(() => Date.now());
+
+  useEffect(() => {
+    const t = setInterval(() => setNow(Date.now()), 15_000);
+    return () => clearInterval(t);
+  }, []);
+
+  const grid = "grid grid-cols-[4.5rem_3rem_3rem_6rem_5rem_5rem_4rem_6rem_3rem] gap-2 items-center";
+
+  return (
+    <section className="border border-outline-variant rounded-lg bg-white" aria-label="Recent trades">
+      <div className="flex items-center justify-between px-3 py-2 border-b border-outline-variant">
+        <span className="font-label-caps text-label-caps uppercase font-bold tracking-wider text-on-surface-variant">Recent trades</span>
+        <span className="text-[9px] font-bold uppercase px-1 rounded bg-secondary-container text-on-secondary-container" title="Decoded from contract Trade events via Stellar RPC">
+          chain
+        </span>
+      </div>
+
+      {tape.isLoading ? (
+        <div className="p-3 space-y-2" aria-busy="true">
+          {Array.from({ length: 4 }, (_, i) => (
+            <div key={i} className="h-5 bg-surface-container-low rounded animate-pulse motion-reduce:animate-none" />
+          ))}
+        </div>
+      ) : tape.isError ? (
+        <div className="p-3 text-xs text-error flex items-center gap-2" role="alert">
+          Couldn&apos;t load trades from the RPC.
+          <button type="button" onClick={() => tape.refetch()} className="text-primary hover:underline font-bold">
+            Retry
+          </button>
+        </div>
+      ) : tape.rows.length === 0 ? (
+        <p className="p-3 text-xs text-on-surface-variant">No trades on this market in the RPC&apos;s retention window.</p>
+      ) : (
+        <div className="overflow-x-auto">
+          <div role="table" aria-rowcount={tape.rows.length + 1} className="min-w-[44rem] font-data-mono text-[11px]">
+            <div role="row" aria-rowindex={1} className={`${grid} px-3 py-1 text-on-surface-variant border-b border-outline-variant/40`}>
+              {COLUMNS.map((c) => (
+                <span key={c} role="columnheader" className={c === "USDC" || c === "Shares" || c === "Fee" ? "text-right" : ""}>
+                  {c}
+                </span>
+              ))}
+            </div>
+            <div ref={ref} onScroll={onScroll} className={`overflow-y-auto ${compact ? "max-h-64" : "max-h-[32rem]"}`}>
+              <div style={{ height: tape.rows.length * ROW_HEIGHT, position: "relative" }}>
+                {tape.rows.slice(start, end).map((row, i) => {
+                  const index = start + i;
+                  const moved = row.prevYesBps === null ? 0 : row.yesBpsAfter - row.prevYesBps;
+                  const isYou = address !== null && row.trader === address;
+                  return (
+                    <div
+                      key={row.id}
+                      role="row"
+                      aria-rowindex={index + 2}
+                      className={`${grid} px-3 absolute left-0 right-0 border-b border-outline-variant/20`}
+                      style={{ top: index * ROW_HEIGHT, height: ROW_HEIGHT }}
+                    >
+                      <span role="cell" title={row.closedAt}>
+                        {relativeTime(row.closedAt, now)}
+                      </span>
+                      <span role="cell" className={`font-bold ${row.outcome === "Yes" ? "text-secondary" : "text-tertiary"}`}>
+                        {row.outcome === "Yes" ? "YES" : "NO"}
+                      </span>
+                      <span role="cell">{row.isBuy ? "BUY" : "SELL"}</span>
+                      <span role="cell">
+                        <a href={explorerAccount(row.trader)} target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">
+                          {isYou ? "you" : shortAddress(row.trader)}
+                        </a>
+                      </span>
+                      <span role="cell" className="text-right">{formatUsdc(row.collateral, { maxDecimals: 2, grouping: true })}</span>
+                      <span role="cell" className="text-right">{formatUsdc(row.shares, { maxDecimals: 2, grouping: true })}</span>
+                      <span role="cell" className="text-right">{formatUsdc(row.fee, { maxDecimals: 2, grouping: true })}</span>
+                      <span role="cell">
+                        {(row.yesBpsAfter / 100).toFixed(1)}%
+                        {moved !== 0 && (
+                          <span className={moved > 0 ? "text-secondary" : "text-tertiary"}>
+                            {" "}
+                            {moved > 0 ? "▲" : "▼"}
+                            <span className="sr-only">{moved > 0 ? "up" : "down"}</span> {(Math.abs(moved) / 100).toFixed(1)}
+                          </span>
+                        )}
+                        {row.origin === "socket" && <span className="sr-only"> (live, unconfirmed by RPC)</span>}
+                      </span>
+                      <span role="cell">
+                        <a href={explorerTx(row.txHash)} target="_blank" rel="noopener noreferrer" className="text-primary hover:underline" aria-label={`Transaction ${row.txHash.slice(0, 8)}`}>
+                          {row.txHash.slice(0, 4)}…
+                        </a>
+                      </span>
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {!tape.isLoading && !tape.isError && (
+        <div className="px-3 py-2 border-t border-outline-variant text-[11px] text-on-surface-variant flex items-center justify-between gap-2">
+          {tape.reachedRetention ? (
+            <span>Older trades are beyond the RPC&apos;s retention window.</span>
+          ) : (
+            <button type="button" onClick={tape.loadOlder} disabled={tape.isFetching} className="text-primary font-bold hover:underline disabled:opacity-50">
+              {tape.isFetching ? "Loading…" : "Load older"}
+            </button>
+          )}
+          <span>USDC is gross in for buys, net out for sells; fee shown separately.</span>
+        </div>
+      )}
+    </section>
+  );
+}
diff --git a/docs/STATUS.md b/docs/STATUS.md
index 6350c2c..6353e21 100644
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@@ -65,6 +65,18 @@ DEMO_TRACE_FILE=<rebuilt demo trace bytes> DEMO_TRACE_ID=1 npm run e2e:testnet
 3. Login with a throwaway keypair: backend `scripts/smoke.sh`, passed.
 4. Trace #1 from `scripts/demo.sh`: bytes rebuilt from the script's template hash to the on-chain `38f728a8…` and verify; a tampered copy is a mismatch; the real gateway can't serve the placeholder CID, so it's `unavailable` and no content is rendered.
 
+## Realtime batching profile (issue #41)
+
+Measured with `scripts/realtime-burst.mjs` and `?profile=1` (React Profiler,
+development build). Fill in after running locally:
+
+| Scenario | Feed | Commits/s before | Commits/s after | actualDuration/s before | after |
+|---|---|---|---|---|---|
+| 500 events @ 500/s | TradingFeed | _todo_ | _todo_ | _todo_ | _todo_ |
+| 500 events @ 500/s | AgentActivityFeed | _todo_ | _todo_ | _todo_ | _todo_ |
+| 500 events @ 50/s | TradingFeed | _todo_ | _todo_ | _todo_ | _todo_ |
+| 500 events @ 50/s | AgentActivityFeed | _todo_ | _todo_ | _todo_ | _todo_ |
+
 ## Not verified (and how to verify)
 
 Everything that needs a browser wallet. Follow [docs/manual-test.md](manual-test.md), which lists every click:
diff --git a/docs/architecture.md b/docs/architecture.md
index c5a8dc8..a9c6adb 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -8,6 +8,8 @@ The frontend has two sources that can disagree, and it says which one a value ca
 |---|---|---|
 | Prices, reserves, market status, positions, USDC balance | **Chain**, via simulated contract calls (`lib/hooks/useStellar.ts`) | The contract is the truth; the backend's copy can lag. |
 | Question text, category, reasoning traces (metadata), subscriptions, platform counts | **Backend** (`lib/api/*`, `docs/api.md`) | Not stored on-chain in readable form. |
+| Per-market trade tape (quick-view) | **Chain events**: market-core `Trade` events via RPC `getEvents`, topic-filtered by market id (`lib/stellar/events.ts`, `components/market/trade-tape.tsx`) | Every trade is a public contract event. Only covers the RPC's retention window (days, not months); older trades are not shown and the tape says so. Live socket rows are replaced by decoded RPC rows on refetch. |
+| Notifications inbox | **Chain events + socket**, stored per wallet and network in IndexedDB (`lib/notifications/*`) | Derived from the connected address only: own fills, held markets resolving, own redemptions, traces on held markets, own failed/pending txs. Nothing is stored server-side. |
 | Trace content | **IPFS**, then hash-checked against `reasoning_registry.get_trace` | Gateways are not authenticated; content is shown only if its sha256 matches the chain (`lib/stellar/trace.ts`). |
 
 A backend market links to the chain through `onChainMarketId` (market-core's `u64` id, a decimal string in JSON). On-chain markets the backend doesn't know are still listed on `/markets`, with on-chain data only.
@@ -27,6 +29,24 @@ A backend market links to the chain through `onChainMarketId` (market-core's `u6
 - Reads are simulations (no fee, no signature).
 - Writes (`useBuy`, `useSell`, `useRedeem`, `useUsdcTransfer`) check that a wallet is connected and on the right network, run fresh contract preflight checks, simulate, then `signAndSend`. A per-address queue serializes complete build/sign/send jobs in this tab and coordinates browser tabs with Web Locks (or a local-storage lease fallback); stale-sequence errors receive one fresh-build retry. The buy, sell, redeem, and USDC-transfer paths can decode the final simulated contract invocation and show its arguments and transaction envelope for review before the wallet prompt.
 - `useBuy` quotes again immediately before building the transaction and sets `min_shares_out = minOut(quote, slippageBps)`, so slippage is enforced on-chain.
+### Optimistic position and balance updates
+
+After a confirmed `buy`, `sell` or `redeem`, the hooks write the contract's own
+return value (`shares_out`, `shares_in`, `payout`) into the position and USDC
+balance caches immediately, marked provisional with the tx hash and the ledger
+the tx landed in (`lib/stellar/optimistic.ts`). Rules:
+
+- Position and balance queries store `{ value, ledger }`, where `ledger` is the
+  read simulation's `latestLedger`. Components still see plain values via `select`;
+  `usePositionState` / `useUsdcBalanceState` expose the provisional marker.
+- In-flight reads are cancelled before signing, and the query function never
+  replaces a provisional value with a read simulated at a lower ledger.
+- Reconciliation re-reads after 1 s, 3 s and 8 s. A read at or above the tx ledger
+  clears the marker; if it differs, the chain value wins and `[optimistic] mismatch`
+  is logged. If the RPC still lags, the value stays, labelled "awaiting RPC".
+- Rejected or failed writes restore the snapshot. An unknown outcome, or a
+  missing landing ledger, falls back to plain invalidation with no optimistic write.
+
 ## Write path and transaction lifecycle
 
 Every state-changing write (`useBuy`, `useSell`, `useRedeem`, `useUsdcTransfer`) follows an explicit, observable lifecycle governed by `TxLifecycle` in `lib/stellar/tx-lifecycle.ts`:
diff --git a/docs/manual-test.md b/docs/manual-test.md
index e89336b..59d2303 100644
--- a/docs/manual-test.md
+++ b/docs/manual-test.md
@@ -119,6 +119,21 @@ To try the same on market 0 (resolved): the buy button is disabled and the panel
 - [ ] If spendable XLM is below the total fee: verify the message "You need about X more XLM to pay the network fee." is displayed and the Buy button is disabled.
 - [ ] Verify the same fee preview, spendable XLM display, and blocking warnings appear on `/copy-trade` (next to slippage text) and `/premium` (in the checkout modal above the pay button).
 
+## 12. Notifications inbox
+
+- [ ] Disconnected, `/notifications` shows a connect prompt and no feed; the bell has no badge.
+- [ ] Connect wallet A in browser 1 and wallet B in browser 2. Buy with A: only A gets a "Buy filled" item, and A's bell shows `1` with an accessible label "Notifications, 1 unread".
+- [ ] Scroll the item into view for one second (or click **Mark read**): the count drops. Reload: read state is kept.
+- [ ] Switch to another account: the previous account's items never appear, even briefly.
+- [ ] Resolve or void a seeded market you hold (`seed-market.sh` in the contracts repo). Within about a minute a "redeemable" item appears linking to quick-view.
+- [ ] In a private window where IndexedDB is blocked, the page says "Notifications won't be saved in this browser".
+
+## 13. Optimistic updates and trade tape
+
+- [ ] After a buy in quick-view, "Your position" and the wallet dropdown balance update at once, with "pending confirmation" and a `tx` link; within a few seconds the marker clears.
+- [ ] Quick-view lists recent trades for the market, with YES/NO and BUY/SELL as text, linking to the trader and the transaction. A new trade appears at the top without duplicating when the RPC copy arrives.
+- [ ] **Load older** pages back until the "beyond the RPC's retention window" notice.
+
 ## Also worth clicking
 
 - [ ] `/premium` → **Get a daily pass** → **Pay with wallet**. Freighter shows a USDC `transfer` to the treasury (`CBTFA3EP…`) for 0.50 USDC. After approval the backend verifies it on-chain and says the pass is active. Note: until `PAYMENTS_RECIPIENT` is decided, this payment becomes treasury trading capital (see docs/STATUS.md).
diff --git a/lib/hooks/__tests__/marketTrades.test.ts b/lib/hooks/__tests__/marketTrades.test.ts
new file mode 100644
index 0000000..eea3098
--- /dev/null
+++ b/lib/hooks/__tests__/marketTrades.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { mergeTrades, socketTradeToRow, withPrevPrice } from "../marketTrades";
+import type { TradeExecutedPayload } from "@/lib/realtime/RealtimeProvider";
+
+const payload = (over: Partial<TradeExecutedPayload> = {}): TradeExecutedPayload => ({
+  onChainMarketId: "7",
+  marketId: null,
+  marketQuestion: null,
+  trader: "GTRADER",
+  direction: "YES",
+  isBuy: true,
+  collateralRaw: "10000000",
+  sharesRaw: "15873015",
+  feeRaw: "200000",
+  priceYesBps: 6421,
+  txHash: "a".repeat(64),
+  ledger: 10,
+  eventId: "e1",
+  ...over,
+});
+
+describe("market trades merging", () => {
+  it("ignores socket rows for other markets", () => {
+    expect(socketTradeToRow(payload({ onChainMarketId: "8" }), "7")).toBeNull();
+  });
+
+  it("rejects malformed amounts", () => {
+    expect(socketTradeToRow(payload({ collateralRaw: "1.5" }), "7")).toBeNull();
+  });
+
+  it("replaces a socket row with the decoded RPC row of the same id", () => {
+    const socket = socketTradeToRow(payload(), "7")!;
+    const rpcRow = { ...socket, origin: "rpc" as const, reserveYes: 1n, reserveNo: 2n };
+    const merged = mergeTrades([rpcRow], [socket]);
+    expect(merged).toHaveLength(1);
+    expect(merged[0].origin).toBe("rpc");
+  });
+
+  it("computes the previous price from the next-older row", () => {
+    const a = socketTradeToRow(payload({ eventId: "a", ledger: 11, priceYesBps: 6500 }), "7")!;
+    const b = socketTradeToRow(payload({ eventId: "b", ledger: 10, priceYesBps: 6400 }), "7")!;
+    const rows = withPrevPrice(mergeTrades([], [b, a]));
+    expect(rows.map((r) => r.prevYesBps)).toEqual([6400, null]);
+  });
+});
diff --git a/lib/hooks/marketTrades.ts b/lib/hooks/marketTrades.ts
new file mode 100644
index 0000000..1588cfe
--- /dev/null
+++ b/lib/hooks/marketTrades.ts
@@ -0,0 +1,50 @@
+import type { TradeRow } from "@/lib/stellar/events";
+import { MAX_TAPE_ROWS } from "@/lib/stellar/events";
+import type { TradeExecutedPayload } from "@/lib/realtime/RealtimeProvider";
+
+/** Pure helpers behind useMarketTrades (issue #40), kept React-free for tests. */
+
+const INT = /^\d+$/;
+
+/** Builds a provisional tape row from a socket payload, or null if it is for another market or malformed. */
+export function socketTradeToRow(p: TradeExecutedPayload, marketId: string): TradeRow | null {
+  if (p.onChainMarketId !== marketId) return null;
+  if (!INT.test(p.collateralRaw) || !INT.test(p.sharesRaw) || !INT.test(p.feeRaw ?? "0")) return null;
+  if (typeof p.eventId !== "string" || !p.eventId) return null;
+  return {
+    id: p.eventId,
+    ledger: p.ledger,
+    closedAt: new Date().toISOString(),
+    txHash: p.txHash,
+    marketId,
+    trader: p.trader,
+    outcome: p.direction === "YES" ? "Yes" : "No",
+    isBuy: p.isBuy,
+    collateral: BigInt(p.collateralRaw),
+    shares: BigInt(p.sharesRaw),
+    fee: BigInt(p.feeRaw ?? "0"),
+    // Socket rows carry no reserves; the next RPC refetch replaces them.
+    reserveYes: 0n,
+    reserveNo: 0n,
+    yesBpsAfter: p.priceYesBps,
+    origin: "socket",
+  };
+}
+
+/**
+ * Merges RPC rows (authoritative) with live socket rows, newest first,
+ * deduped by event id. A decoded RPC row replaces a socket row with the same id.
+ */
+export function mergeTrades(rpcRows: readonly TradeRow[], socketRows: readonly TradeRow[]): TradeRow[] {
+  const byId = new Map<string, TradeRow>();
+  for (const r of socketRows) byId.set(r.id, r);
+  for (const r of rpcRows) byId.set(r.id, r);
+  return [...byId.values()]
+    .sort((a, b) => (b.ledger - a.ledger) || (b.id < a.id ? -1 : b.id > a.id ? 1 : 0))
+    .slice(0, MAX_TAPE_ROWS);
+}
+
+/** Price before each trade, from the next-older row (null for the oldest). */
+export function withPrevPrice(rows: readonly TradeRow[]): Array<TradeRow & { prevYesBps: number | null }> {
+  return rows.map((r, i) => ({ ...r, prevYesBps: i + 1 < rows.length ? rows[i + 1].yesBpsAfter : null }));
+}
diff --git a/lib/hooks/useMarketTrades.ts b/lib/hooks/useMarketTrades.ts
new file mode 100644
index 0000000..6a6a31c
--- /dev/null
+++ b/lib/hooks/useMarketTrades.ts
@@ -0,0 +1,57 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { fetchMarketTrades, type TradeRow } from "@/lib/stellar/events";
+import { useRealtimeBatch, type TradeExecutedPayload } from "@/lib/realtime/RealtimeProvider";
+import { mergeTrades, socketTradeToRow, withPrevPrice } from "./marketTrades";
+
+/**
+ * Newest trades for one market, decoded from market-core Trade events via RPC
+ * and extended live by TRADE_EXECUTED (issue #40). The key starts with
+ * "stellar" so a disconnect drops it with the other chain reads.
+ */
+export function useMarketTrades(onChainMarketId: string | null | undefined, { limit = 20 }: { limit?: number } = {}) {
+  const [want, setWant] = useState(limit);
+  const [live, setLive] = useState<{ marketId: string; rows: TradeRow[] }>({ marketId: "", rows: [] });
+
+  const query = useQuery({
+    queryKey: ["stellar", "marketTrades", onChainMarketId ?? "", want],
+    enabled: Boolean(onChainMarketId),
+    queryFn: ({ signal }) => fetchMarketTrades(BigInt(onChainMarketId as string), { want, signal }),
+    staleTime: 60_000,
+  });
+
+  const onBatch = useCallback(
+    (batch: readonly TradeExecutedPayload[]) => {
+      if (!onChainMarketId) return;
+      const rows: TradeRow[] = [];
+      for (const p of batch) {
+        const row = socketTradeToRow(p, onChainMarketId);
+        if (row) rows.push(row);
+      }
+      if (rows.length === 0) return;
+      setLive((prev) => ({
+        marketId: onChainMarketId,
+        rows: mergeTrades([], [...rows, ...(prev.marketId === onChainMarketId ? prev.rows : [])]),
+      }));
+    },
+    [onChainMarketId],
+  );
+  useRealtimeBatch("TRADE_EXECUTED", onBatch);
+
+  const liveRows = live.marketId === onChainMarketId ? live.rows : [];
+  const rpcRows = query.data?.trades;
+  const rows = useMemo(() => withPrevPrice(mergeTrades(rpcRows ?? [], liveRows)), [rpcRows, liveRows]);
+
+  return {
+    rows,
+    isLoading: query.isLoading,
+    isError: query.isError,
+    error: query.error,
+    refetch: query.refetch,
+    isFetching: query.isFetching,
+    reachedRetention: query.data?.reachedRetention ?? false,
+    loadOlder: () => setWant((w) => w * 2),
+  };
+}
diff --git a/lib/hooks/useStellar.ts b/lib/hooks/useStellar.ts
index 5748c4a..49269f4 100644
--- a/lib/hooks/useStellar.ts
+++ b/lib/hooks/useStellar.ts
@@ -10,7 +10,22 @@ import { UserFacingError, type ContractName } from "@/lib/stellar/errors";
 import { collateralOutForShares, priceYesBps } from "@/lib/stellar/generated/fpmm";
 import type { Config, Market as OnChainMarket, Position } from "@/lib/stellar/generated/market-core";
 import { fetchAndVerifyTrace, type TraceCheck } from "@/lib/stellar/trace";
-import { read, submit, bytesToHex, simulated } from "@/lib/stellar/typed-call";
+import { read, submit, bytesToHex, simulated, simulatedWithLedger } from "@/lib/stellar/typed-call";
+import {
+  applyBuy,
+  applyRedeem,
+  applySell,
+  balanceDelta,
+  bigintEquals,
+  guardRead,
+  positionEquals,
+  reconcile,
+  stackProvisional,
+  RECONCILE_DELAYS_MS,
+  type Provisional,
+  type Stamped,
+  type WriteResult,
+} from "@/lib/stellar/optimistic";
 import { maxIn, minOut } from "@/lib/stellar/units";
 import {
   feeBreakdown,
@@ -31,7 +46,8 @@ import { NETWORK_PASSPHRASE } from "@/lib/stellar/config";
 export { simulated };
 export { tradeInvalidationKeys };
 
-export { read, submit, simulated, bytesToHex };
+export { read, submit, simulated, bytesToHex, simulatedWithLedger };
+export type { Stamped, Provisional };
 
 /** Query keys all start with "stellar" so a disconnect can drop them in one go. */
 export const stellarKeys = {
@@ -166,26 +182,67 @@ export function useOnChainMarkets(limit = 20) {
   });
 }
 
-export function usePosition(id: bigint | string | null | undefined, holder: string | null | undefined) {
+async function readPosition(id: bigint, holder: string): Promise<Stamped<Position>> {
+  return simulatedWithLedger(await marketCore().get_position({ market_id: id, holder }));
+}
+
+async function readUsdcBalance(owner: string): Promise<Stamped<bigint>> {
+  return simulatedWithLedger(await token.balance(owner));
+}
+
+function usePositionQuery<S>(
+  id: bigint | string | null | undefined,
+  holder: string | null | undefined,
+  select: (d: Stamped<Position>) => S,
+) {
+  const queryClient = useQueryClient();
+  const key = stellarKeys.position(String(id), holder ?? "");
   return useQuery({
-    queryKey: stellarKeys.position(String(id), holder ?? ""),
+    queryKey: key,
     enabled: id !== null && id !== undefined && Boolean(holder),
+    // Guarded: a read simulated below a provisional write's ledger is stale
+    // and must not overwrite the optimistic value (issue #39).
     queryFn: async () =>
-      read(await marketCore().get_position({ market_id: toId(id as string), holder: holder as string })),
+      guardRead(queryClient.getQueryData<Stamped<Position>>(key), await readPosition(toId(id as string), holder as string)),
+    select,
     staleTime: 15_000,
   });
 }
 
-export function useUsdcBalance(owner: string | null | undefined) {
+function useUsdcBalanceQuery<S>(owner: string | null | undefined, select: (d: Stamped<bigint>) => S) {
+  const queryClient = useQueryClient();
+  const key = stellarKeys.balance(owner ?? "");
   return useQuery({
-    queryKey: stellarKeys.balance(owner ?? ""),
+    queryKey: key,
     enabled: Boolean(owner),
-    queryFn: async () => read(await token.balance(owner as string)),
+    queryFn: async () => guardRead(queryClient.getQueryData<Stamped<bigint>>(key), await readUsdcBalance(owner as string)),
+    select,
     staleTime: 15_000,
     refetchInterval: 30_000,
   });
 }
 
+const unwrapStamped = <T,>(d: Stamped<T>) => d.value;
+const keepStamped = <T,>(d: Stamped<T>) => d;
+
+export function usePosition(id: bigint | string | null | undefined, holder: string | null | undefined) {
+  return usePositionQuery(id, holder, unwrapStamped<Position>);
+}
+
+/** The stamped position, including the provisional marker after a write. */
+export function usePositionState(id: bigint | string | null | undefined, holder: string | null | undefined) {
+  return usePositionQuery(id, holder, keepStamped<Position>);
+}
+
+export function useUsdcBalance(owner: string | null | undefined) {
+  return useUsdcBalanceQuery(owner, unwrapStamped<bigint>);
+}
+
+/** The stamped USDC balance, including the provisional marker after a write. */
+export function useUsdcBalanceState(owner: string | null | undefined) {
+  return useUsdcBalanceQuery(owner, keepStamped<bigint>);
+}
+
 export interface AccountReserveState extends AccountReserve {
   funded: boolean;
 }
@@ -449,8 +506,14 @@ function useWriteGuard(): () => Signer {
 
 export function useInvalidateAfterTrade() {
   const queryClient = useQueryClient();
-  return (marketId: string, holder: string) => {
+  return (marketId: string, holder: string, opts: { skipHolderKeys?: boolean } = {}) => {
+    const holderKeys = new Set([
+      JSON.stringify(stellarKeys.position(marketId, holder)),
+      JSON.stringify(stellarKeys.balance(holder)),
+    ]);
     for (const key of tradeInvalidationKeys(marketId, holder)) {
+      // Position and balance are reconciled by ledger instead (issue #39).
+      if (opts.skipHolderKeys && holderKeys.has(JSON.stringify(key))) continue;
       queryClient.invalidateQueries({ queryKey: key });
     }
     // Fees change the XLM balance, so the account entry is stale after a trade.
@@ -458,6 +521,147 @@ export function useInvalidateAfterTrade() {
   };
 }
 
+interface OptimisticSnapshot {
+  position?: Stamped<Position>;
+  balance?: Stamped<bigint>;
+}
+
+/**
+ * Optimistic position/balance updates with ledger-aware reconciliation
+ * (issue #39). Values come only from the contract's return value.
+ */
+function useOptimisticTrade() {
+  const queryClient = useQueryClient();
+  const { address } = useWallet();
+  const addressRef = useRef(address);
+  addressRef.current = address;
+
+  /** Cancel in-flight reads so they cannot resolve after the write and win. */
+  const begin = useCallback(
+    async (marketId: string, holder: string | null | undefined): Promise<OptimisticSnapshot> => {
+      if (!holder) return {};
+      const posKey = stellarKeys.position(marketId, holder);
+      const balKey = stellarKeys.balance(holder);
+      await Promise.all([
+        queryClient.cancelQueries({ queryKey: posKey }),
+        queryClient.cancelQueries({ queryKey: balKey }),
+      ]);
+      return {
+        position: queryClient.getQueryData<Stamped<Position>>(posKey),
+        balance: queryClient.getQueryData<Stamped<bigint>>(balKey),
+      };
+    },
+    [queryClient],
+  );
+
+  const rollback = useCallback(
+    (marketId: string, holder: string | null | undefined, snap: OptimisticSnapshot | undefined) => {
+      if (!holder || !snap) return;
+      if (snap.position) queryClient.setQueryData(stellarKeys.position(marketId, holder), snap.position);
+      if (snap.balance) queryClient.setQueryData(stellarKeys.balance(holder), snap.balance);
+    },
+    [queryClient],
+  );
+
+  const scheduleReconcile = useCallback(
+    <T,>(key: readonly unknown[], holder: string, read: () => Promise<Stamped<T>>, equals: (a: T, b: T) => boolean) => {
+      let attempt = 0;
+      const tick = async () => {
+        const current = queryClient.getQueryData<Stamped<T>>(key);
+        // Disconnected or switched wallet: the key is gone, nothing to do.
+        if (!current?.provisional || addressRef.current !== holder) return;
+        let fresh: Stamped<T>;
+        try {
+          fresh = await read();
+        } catch {
+          fresh = { value: current.value, ledger: -1 };
+        }
+        const latest = queryClient.getQueryData<Stamped<T>>(key);
+        if (!latest?.provisional || addressRef.current !== holder) return;
+        const outcome = reconcile(latest, fresh, equals);
+        if (outcome.status === "lagging") {
+          attempt++;
+          if (attempt < RECONCILE_DELAYS_MS.length) {
+            setTimeout(tick, RECONCILE_DELAYS_MS[attempt] - RECONCILE_DELAYS_MS[attempt - 1]);
+          } else {
+            // Keep the provisional value but say the RPC hasn't caught up.
+            queryClient.setQueryData<Stamped<T>>(key, { ...latest, provisional: { ...latest.provisional, awaitingRpc: true } });
+          }
+          return;
+        }
+        if (outcome.status === "mismatch") {
+          console.warn("[optimistic] mismatch", {
+            key,
+            expected: outcome.expected,
+            actual: outcome.actual,
+            txHash: latest.provisional.txHash,
+          });
+        }
+        queryClient.setQueryData<Stamped<T>>(key, outcome.next);
+      };
+      setTimeout(tick, RECONCILE_DELAYS_MS[0]);
+    },
+    [queryClient],
+  );
+
+  const apply = useCallback(
+    (args: {
+      marketId: string;
+      holder: string;
+      snap: OptimisticSnapshot | undefined;
+      ledger: number | null;
+      txHash: string | null;
+      position: (p: Position) => Position;
+      result: WriteResult;
+    }): boolean => {
+      const { marketId, holder, snap, ledger, txHash } = args;
+      // Unknown landing ledger: we cannot reconcile safely, so don't guess.
+      if (ledger === null) return false;
+      const posKey = stellarKeys.position(marketId, holder);
+      const balKey = stellarKeys.balance(holder);
+      const provisional: Provisional = { txHash, ledger, kind: args.result.kind };
+
+      // Base on the snapshot (or a newer provisional, so quick buys stack).
+      const posNow = queryClient.getQueryData<Stamped<Position>>(posKey);
+      const posBase = posNow?.provisional ? posNow : snap?.position ?? posNow;
+      if (posBase) {
+        let next: Position;
+        try {
+          next = args.position(posBase.value);
+        } catch {
+          // Would go negative: the cache was already wrong. Ask the chain.
+          queryClient.invalidateQueries({ queryKey: posKey });
+          return false;
+        }
+        queryClient.setQueryData(posKey, stackProvisional(posBase, next, provisional));
+        scheduleReconcile(posKey, holder, () => readPosition(BigInt(marketId), holder), positionEquals);
+      } else {
+        queryClient.invalidateQueries({ queryKey: posKey });
+      }
+
+      const balNow = queryClient.getQueryData<Stamped<bigint>>(balKey);
+      const balBase = balNow?.provisional ? balNow : snap?.balance ?? balNow;
+      if (balBase) {
+        queryClient.setQueryData(balKey, stackProvisional(balBase, balBase.value + balanceDelta(args.result), provisional));
+        scheduleReconcile(balKey, holder, () => readUsdcBalance(holder), bigintEquals);
+      } else {
+        queryClient.invalidateQueries({ queryKey: balKey });
+      }
+      return true;
+    },
+    [queryClient, scheduleReconcile],
+  );
+
+  return { begin, rollback, apply, address };
+}
+
+/** True when the error happened after submission and the outcome is unknown. */
+function isUnknownOutcome(error: unknown): boolean {
+  if (!(error instanceof UserFacingError)) return false;
+  const d = error.described as { kind?: string; submission?: string };
+  return d.kind === "unknown" || d.submission === "timeout";
+}
+
 /** The RPC's network info, including the Friendbot URL on testnet. */
 export function useRpcNetwork() {
   return useQuery({
@@ -480,7 +684,7 @@ function useTxRunner(contract: ContractName) {
       tx: AssembledTransaction<T>,
       parse: (v: xdr.ScVal | undefined) => R,
       onHash?: (hash: string) => void,
-    ): Promise<{ value: R; txHash: string }> => {
+    ): Promise<{ value: R; txHash: string; ledger: number | null }> => {
       const runner = new TxLifecycle<R>({
         server: rpcServer(),
         contract,
@@ -736,10 +940,13 @@ async function fetchTradePreflightInput(marketId: bigint, holder: string, includ
 export function useBuy() {
   const guard = useWriteGuard();
   const invalidate = useInvalidateAfterTrade();
+  const optimistic = useOptimisticTrade();
   const runner = useTxRunner("marketCore");
   const tracker = useTxTracker();
 
   const mutation = useMutation({
+    onMutate: (v: BuyParams & { prepared?: PreparedBuy; collateralIn: bigint }) =>
+      optimistic.begin(String(v.marketId), optimistic.address),
     mutationFn: async ({
       marketId,
       outcome,
@@ -790,10 +997,25 @@ export function useBuy() {
         return (val ? scValToNative(val) : quote) as bigint;
       };
 
-      const { value, txHash } = await runner.start(tx, parse, onHash);
-      return { sharesOut: value, quotedShares: quote, minSharesOut, txHash, holder: signer.publicKey };
+      const { value, txHash, ledger } = await runner.start(tx, parse, onHash);
+      return { sharesOut: value, quotedShares: quote, minSharesOut, txHash, ledger, holder: signer.publicKey };
+    },
+    onSuccess: (d, v, snap) => {
+      const applied = optimistic.apply({
+        marketId: String(v.marketId),
+        holder: d.holder,
+        snap,
+        ledger: d.ledger,
+        txHash: d.txHash,
+        position: (p) => applyBuy(p, v.outcome, d.sharesOut),
+        result: { kind: "buy", collateralIn: v.collateralIn },
+      });
+      invalidate(String(v.marketId), d.holder, { skipHolderKeys: applied });
+    },
+    onError: (error, v, snap) => {
+      if (isUnknownOutcome(error) && optimistic.address) invalidate(String(v.marketId), optimistic.address);
+      else optimistic.rollback(String(v.marketId), optimistic.address, snap);
     },
-    onSuccess: (d, v) => invalidate(String(v.marketId), d.holder),
   });
 
   return {
@@ -812,10 +1034,12 @@ export type SellParams = {
 export function useSell() {
   const guard = useWriteGuard();
   const invalidate = useInvalidateAfterTrade();
+  const optimistic = useOptimisticTrade();
   const runner = useTxRunner("marketCore");
   const tracker = useTxTracker();
 
   const mutation = useMutation({
+    onMutate: (v: SellParams) => optimistic.begin(String(v.marketId), optimistic.address),
     mutationFn: async ({ marketId, outcome, shares, slippageBps }: SellParams) => {
       const signer = guard();
       await requireUsdcTrustline(signer.publicKey);
@@ -951,10 +1175,25 @@ export function useSell() {
         return (val ? scValToNative(val) : shares) as bigint;
       };
 
-      const { value, txHash } = await runner.start(tx, parse, onHash);
-      return { sharesSold: value, collateralOut, maxSharesIn, txHash, holder: signer.publicKey };
+      const { value, txHash, ledger } = await runner.start(tx, parse, onHash);
+      return { sharesSold: value, collateralOut: confirmed.collateralOut, maxSharesIn, txHash, ledger, holder: signer.publicKey };
+    },
+    onSuccess: (d, v, snap) => {
+      const applied = optimistic.apply({
+        marketId: String(v.marketId),
+        holder: d.holder,
+        snap,
+        ledger: d.ledger,
+        txHash: d.txHash,
+        position: (p) => applySell(p, v.outcome, d.sharesSold),
+        result: { kind: "sell", collateralOut: d.collateralOut },
+      });
+      invalidate(String(v.marketId), d.holder, { skipHolderKeys: applied });
+    },
+    onError: (error, v, snap) => {
+      if (isUnknownOutcome(error) && optimistic.address) invalidate(String(v.marketId), optimistic.address);
+      else optimistic.rollback(String(v.marketId), optimistic.address, snap);
     },
-    onSuccess: (d, v) => invalidate(String(v.marketId), d.holder),
   });
 
   return {
@@ -966,10 +1205,12 @@ export function useSell() {
 export function useRedeem() {
   const guard = useWriteGuard();
   const invalidate = useInvalidateAfterTrade();
+  const optimistic = useOptimisticTrade();
   const runner = useTxRunner("marketCore");
   const tracker = useTxTracker();
 
   const mutation = useMutation({
+    onMutate: (v: { marketId: bigint | string }) => optimistic.begin(String(v.marketId), optimistic.address),
     mutationFn: async ({ marketId }: { marketId: bigint | string }) => {
       const signer = guard();
       const tx = await marketCore(signer).redeem({ holder: signer.publicKey, market_id: toId(marketId) });
@@ -989,10 +1230,26 @@ export function useRedeem() {
         return (val ? scValToNative(val) : 0n) as bigint;
       };
 
-      const { value, txHash } = await runner.start(tx, parse, onHash);
-      return { payout: value, txHash, holder: signer.publicKey };
+      const { value, txHash, ledger } = await runner.start(tx, parse, onHash);
+      return { payout: value, txHash, ledger, holder: signer.publicKey };
+    },
+    onSuccess: (d, v, snap) => {
+      // A losing redeem pays 0n but still zeroes the position.
+      const applied = optimistic.apply({
+        marketId: String(v.marketId),
+        holder: d.holder,
+        snap,
+        ledger: d.ledger,
+        txHash: d.txHash,
+        position: () => applyRedeem(),
+        result: { kind: "redeem", payout: d.payout },
+      });
+      invalidate(String(v.marketId), d.holder, { skipHolderKeys: applied });
+    },
+    onError: (error, v, snap) => {
+      if (isUnknownOutcome(error) && optimistic.address) invalidate(String(v.marketId), optimistic.address);
+      else optimistic.rollback(String(v.marketId), optimistic.address, snap);
     },
-    onSuccess: (d, v) => invalidate(String(v.marketId), d.holder),
   });
 
   return {
diff --git a/lib/notifications/InboxProvider.tsx b/lib/notifications/InboxProvider.tsx
new file mode 100644
index 0000000..e6e632a
--- /dev/null
+++ b/lib/notifications/InboxProvider.tsx
@@ -0,0 +1,276 @@
+"use client";
+
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useWallet } from "@/lib/contexts/WalletContext";
+import { useRealtimeBatch, type ReasoningPublishedPayload, type TradeExecutedPayload } from "@/lib/realtime/RealtimeProvider";
+import { useTxTracker } from "@/lib/stellar/tx-tracker";
+import { marketCore } from "@/lib/stellar/clients";
+import { NETWORK_PASSPHRASE } from "@/lib/stellar/config";
+import type { Position } from "@/lib/stellar/generated/market-core";
+import type { Stamped } from "@/lib/stellar/optimistic";
+import { read } from "@/lib/stellar/typed-call";
+import {
+  decodeRedeemed,
+  decodeResolved,
+  fetchEventsSince,
+  redeemedTopicFilter,
+  resolvedTopicFilter,
+} from "@/lib/stellar/events";
+import { classifyRedeemed, classifyResolved, classifyTrace, classifyTrade, classifyTx } from "./classify";
+import { MAX_ITEMS, openInbox, type Inbox, type InboxItem } from "./store";
+
+const POLL_MS = 60_000;
+/** RPC allows at most 5 topic filters per event filter. */
+const TOPICS_PER_FILTER = 5;
+const LAST_LEDGER_KEY = "lastLedger";
+
+export interface InboxApi {
+  /** Owner the items belong to; null when disconnected. */
+  owner: string | null;
+  items: InboxItem[];
+  unread: number;
+  status: "disconnected" | "loading" | "ready";
+  /** False when IndexedDB is unavailable and items live in memory only. */
+  persistent: boolean;
+  markRead: (ids: string[]) => void;
+  markAllRead: () => void;
+  /** Record the user's own failed transaction (rejections are ignored). */
+  recordTx: (tx: { hash: string | null; kind: string; marketId?: string; errorKind?: string; message?: string }) => void;
+}
+
+const InboxContext = createContext<InboxApi | null>(null);
+
+const EMPTY: InboxApi = {
+  owner: null,
+  items: [],
+  unread: 0,
+  status: "disconnected",
+  persistent: true,
+  markRead: () => {},
+  markAllRead: () => {},
+  recordTx: () => {},
+};
+
+export function useInbox(): InboxApi {
+  return useContext(InboxContext) ?? EMPTY;
+}
+
+function chunk<T>(list: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < list.length; i += size) out.push(list.slice(i, i + size));
+  return out;
+}
+
+/**
+ * Inbox scoped to the connected address and network (issue #42). The store
+ * is reopened on every address change and the previous handle closed, so no
+ * items leak across wallets.
+ */
+export function InboxProvider({ children }: { children: React.ReactNode }) {
+  const { address } = useWallet();
+  const queryClient = useQueryClient();
+  const tracker = useTxTracker();
+  const network = NETWORK_PASSPHRASE;
+
+  const [state, setState] = useState<{ owner: string | null; inbox: Inbox | null; items: InboxItem[] }>({
+    owner: null,
+    inbox: null,
+    items: [],
+  });
+  const inboxRef = useRef<Inbox | null>(null);
+  inboxRef.current = state.owner === address ? state.inbox : null;
+
+  // Open the store for the current address; clear state first.
+  useEffect(() => {
+    setState({ owner: address, inbox: null, items: [] });
+    if (!address) return;
+    let cancelled = false;
+    let opened: Inbox | null = null;
+    openInbox(address, network).then(async (inbox) => {
+      if (cancelled) {
+        inbox.close();
+        return;
+      }
+      opened = inbox;
+      const items = await inbox.list().catch(() => []);
+      if (!cancelled) setState({ owner: address, inbox, items });
+    });
+    return () => {
+      cancelled = true;
+      opened?.close();
+    };
+  }, [address, network]);
+
+  const refresh = useCallback(async (inbox: Inbox, owner: string) => {
+    const items = await inbox.list().catch(() => []);
+    setState((prev) => (prev.owner === owner && prev.inbox === inbox ? { ...prev, items } : prev));
+  }, []);
+
+  const putItems = useCallback(
+    async (list: (InboxItem | null)[]) => {
+      const inbox = inboxRef.current;
+      const owner = address;
+      const items = list.filter((i): i is InboxItem => i !== null);
+      if (!inbox || !owner || items.length === 0) return;
+      try {
+        await inbox.put(items);
+        await inbox.prune(MAX_ITEMS);
+      } catch {
+        // Storage failure: keep going with what is already in memory.
+      }
+      await refresh(inbox, owner);
+    },
+    [address, refresh],
+  );
+
+  // Held markets: own fills plus non-zero positions already read into the cache.
+  const heldMarketIds = useMemo(() => {
+    const held = new Set<string>();
+    for (const it of state.items) if (it.kind === "fill" && it.marketId) held.add(it.marketId);
+    if (address) {
+      for (const [key, data] of queryClient.getQueriesData<Stamped<Position>>({ queryKey: ["stellar", "position"] })) {
+        const [, , id, holder] = key as [string, string, string, string];
+        const pos = data?.value;
+        if (holder === address && pos && pos.yes + pos.no > 0n) held.add(id);
+      }
+    }
+    return held;
+  }, [state.items, address, queryClient]);
+
+  const heldRef = useRef(heldMarketIds);
+  heldRef.current = heldMarketIds;
+
+  const ctx = useMemo(() => (address ? { owner: address, network } : null), [address, network]);
+
+  useRealtimeBatch(
+    "TRADE_EXECUTED",
+    useCallback((batch: readonly TradeExecutedPayload[]) => {
+      if (!ctx) return;
+      void putItems(batch.map((p) => classifyTrade(p, ctx)));
+    }, [ctx, putItems]),
+  );
+
+  useRealtimeBatch(
+    "REASONING_PUBLISHED",
+    useCallback((batch: readonly ReasoningPublishedPayload[]) => {
+      if (!ctx) return;
+      void putItems(batch.map((p) => classifyTrace(p, heldRef.current, ctx)));
+    }, [ctx, putItems]),
+  );
+
+  // Own transactions from the pending-transaction tracker (issue #3).
+  useEffect(() => {
+    if (!ctx) return;
+    const mine = tracker.list.filter((t) => t.holder === ctx.owner && t.networkPassphrase === ctx.network);
+    const items = mine
+      .filter((t) => t.state === "pending" || t.state === "failed")
+      .map((t) =>
+        classifyTx(
+          { hash: t.hash, kind: t.kind, state: t.state as "pending" | "failed", marketId: t.marketId, errorKind: t.error?.kind, message: t.error?.message },
+          { ...ctx, now: t.submittedAt },
+        ),
+      );
+    void putItems(items);
+    // A pending item that settled is marked read so it stops counting.
+    const settled = mine.filter((t) => t.state !== "pending").map((t) => `tx-pending:${t.hash}`);
+    if (settled.length > 0 && inboxRef.current) {
+      const inbox = inboxRef.current;
+      void inbox.markRead(settled).then(() => refresh(inbox, ctx.owner)).catch(() => {});
+    }
+  }, [tracker.list, ctx, putItems, refresh, state.inbox]);
+
+  // Resolution / redemption poller for held markets only.
+  useEffect(() => {
+    const inbox = state.inbox;
+    if (!ctx || !inbox || state.owner !== ctx.owner) return;
+    let cancelled = false;
+
+    const positionOf = async (marketId: string): Promise<Position> =>
+      read(await marketCore().get_position({ market_id: BigInt(marketId), holder: ctx.owner }));
+
+    // Covers resolutions older than RPC retention: check status directly.
+    const checkStatuses = async () => {
+      const found: (InboxItem | null)[] = [];
+      for (const id of heldRef.current) {
+        try {
+          const market = read(await marketCore().get_market({ market_id: BigInt(id) }));
+          if (market.status.tag === "Open") continue;
+          const outcome = market.status.tag === "Resolved" ? market.status.values[0].tag : null;
+          found.push(
+            classifyResolved(
+              { id: `status:${id}`, ledger: 0, closedAt: new Date().toISOString(), marketId: id, outcome },
+              await positionOf(id),
+              ctx,
+            ),
+          );
+        } catch {
+          // Unreachable market or RPC error: try again next poll.
+        }
+      }
+      if (!cancelled) await putItems(found);
+    };
+
+    const poll = async () => {
+      if (document.hidden) return;
+      try {
+        const last = Number((await inbox.getMeta(LAST_LEDGER_KEY)) ?? 0);
+        const held = [...heldRef.current];
+        const found: (InboxItem | null)[] = [];
+        let latest = last;
+
+        for (const ids of chunk(held, TOPICS_PER_FILTER)) {
+          const res = await fetchEventsSince(ids.map((id) => resolvedTopicFilter(BigInt(id))), last + 1);
+          latest = Math.max(latest, res.latestLedger);
+          for (const ev of res.events) {
+            const decoded = decodeResolved(ev);
+            found.push(classifyResolved(decoded, await positionOf(decoded.marketId), ctx));
+          }
+        }
+        const redeemed = await fetchEventsSince([redeemedTopicFilter(ctx.owner)], last + 1);
+        latest = Math.max(latest, redeemed.latestLedger);
+        for (const ev of redeemed.events) found.push(classifyRedeemed(decodeRedeemed(ev), ctx));
+
+        if (cancelled) return;
+        await putItems(found);
+        if (latest > last) await inbox.setMeta(LAST_LEDGER_KEY, String(latest));
+      } catch {
+        // RPC hiccup: the stored ledger is unchanged, so the next poll resumes.
+      }
+    };
+
+    void checkStatuses().then(poll);
+    const timer = setInterval(poll, POLL_MS);
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+  }, [ctx, state.inbox, state.owner, putItems]);
+
+  const api = useMemo<InboxApi>(() => {
+    if (!address) return EMPTY;
+    const owned = state.owner === address;
+    const items = owned ? state.items : [];
+    const inbox = owned ? state.inbox : null;
+    return {
+      owner: address,
+      items,
+      unread: items.reduce((n, i) => (i.readAt === null ? n + 1 : n), 0),
+      status: inbox ? "ready" : "loading",
+      persistent: inbox?.persistent ?? true,
+      markRead: (ids) => {
+        if (!inbox || ids.length === 0) return;
+        void inbox.markRead(ids).then(() => refresh(inbox, address)).catch(() => {});
+      },
+      markAllRead: () => {
+        if (!inbox) return;
+        void inbox.markAllRead().then(() => refresh(inbox, address)).catch(() => {});
+      },
+      recordTx: (tx) => {
+        void putItems([classifyTx({ ...tx, state: "failed" }, { owner: address, network })]);
+      },
+    };
+  }, [address, network, state, refresh, putItems]);
+
+  return <InboxContext.Provider value={api}>{children}</InboxContext.Provider>;
+}
diff --git a/lib/notifications/__tests__/classify.test.ts b/lib/notifications/__tests__/classify.test.ts
new file mode 100644
index 0000000..e3430b3
--- /dev/null
+++ b/lib/notifications/__tests__/classify.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { classifyRedeemed, classifyResolved, classifyTrace, classifyTrade, classifyTx } from "../classify";
+
+const owner = "GOWNER";
+const ctx = { owner, network: "Test SDF Network ; September 2015", now: 1_000 };
+const trade = {
+  trader: owner,
+  eventId: "0001-0001",
+  onChainMarketId: "7",
+  collateralRaw: "10000000",
+  sharesRaw: "15873015",
+  txHash: "b".repeat(64),
+  direction: "YES",
+  isBuy: true,
+  ledger: 5,
+};
+
+describe("classifyTrade", () => {
+  it("ignores trades by other traders", () => {
+    expect(classifyTrade({ ...trade, trader: "GOTHER" }, ctx)).toBeNull();
+  });
+
+  it("rejects malformed collateralRaw and txHash", () => {
+    expect(classifyTrade({ ...trade, collateralRaw: "-1" }, ctx)).toBeNull();
+    expect(classifyTrade({ ...trade, collateralRaw: "1.5" }, ctx)).toBeNull();
+    expect(classifyTrade({ ...trade, txHash: "xyz" }, ctx)).toBeNull();
+  });
+
+  it("produces deterministic ids for the same event", () => {
+    expect(classifyTrade(trade, ctx)!.id).toBe("fill:0001-0001");
+    expect(classifyTrade(trade, { ...ctx, now: 2_000 })!.id).toBe(classifyTrade(trade, ctx)!.id);
+  });
+});
+
+describe("classifyTrace", () => {
+  const payload = { onChainMarketId: "7", onChainTraceId: "3", action: "buy" };
+  it("only fires for held markets", () => {
+    expect(classifyTrace(payload, new Set(["8"]), ctx)).toBeNull();
+    expect(classifyTrace(payload, new Set(["7"]), ctx)?.id).toBe("trace:3");
+  });
+});
+
+describe("resolution and redemption", () => {
+  const resolved = { id: "e", ledger: 9, closedAt: "2026-10-01T00:00:00Z", marketId: "7" };
+
+  it("a void resolution is redeemable", () => {
+    const item = classifyResolved({ ...resolved, outcome: null }, { yes: 1n, no: 0n }, ctx);
+    expect(item).toMatchObject({ kind: "redeemable", id: "redeemable:7", data: { outcome: "void" } });
+  });
+
+  it("nothing to redeem without a position", () => {
+    expect(classifyResolved({ ...resolved, outcome: "Yes" }, { yes: 0n, no: 0n }, ctx)).toBeNull();
+  });
+
+  it("redeemed only for the owner", () => {
+    const ev = { ...resolved, txHash: "c".repeat(64), holder: "GOTHER", payout: 5n };
+    expect(classifyRedeemed(ev, ctx)).toBeNull();
+    expect(classifyRedeemed({ ...ev, holder: owner }, ctx)?.data.payoutRaw).toBe("5");
+  });
+
+  it("does not record wallet rejections", () => {
+    expect(classifyTx({ hash: null, kind: "buy", state: "failed", errorKind: "rejected" }, ctx)).toBeNull();
+    expect(classifyTx({ hash: "d".repeat(64), kind: "buy", state: "failed" }, ctx)?.id).toBe(`tx-failed:${"d".repeat(64)}`);
+  });
+});
diff --git a/lib/notifications/__tests__/store.test.ts b/lib/notifications/__tests__/store.test.ts
new file mode 100644
index 0000000..4741a6d
--- /dev/null
+++ b/lib/notifications/__tests__/store.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { createMemoryInbox, openInbox, type InboxItem } from "../store";
+
+const NET = "Test SDF Network ; September 2015";
+const item = (id: string, over: Partial<InboxItem> = {}): InboxItem => ({
+  id,
+  owner: "GA",
+  network: NET,
+  kind: "fill",
+  createdAt: 1,
+  readAt: null,
+  data: {},
+  ...over,
+});
+
+describe("inbox store (memory backend; same merge rules as IndexedDB)", () => {
+  it("put is idempotent and keeps readAt", async () => {
+    const inbox = createMemoryInbox("GA", NET);
+    await inbox.put([item("fill:1")]);
+    await inbox.markRead(["fill:1"]);
+    await inbox.put([item("fill:1")]);
+    const [stored] = await inbox.list();
+    expect(stored.readAt).not.toBeNull();
+    expect(await inbox.list()).toHaveLength(1);
+  });
+
+  it("isolates by owner and network", async () => {
+    const inbox = createMemoryInbox("GA", NET);
+    await inbox.put([item("a"), item("b", { owner: "GB" }), item("c", { network: "Public Global Stellar Network ; September 2015" })]);
+    expect((await inbox.list()).map((i) => i.id)).toEqual(["a"]);
+  });
+
+  it("counts unread", async () => {
+    const inbox = createMemoryInbox("GA", NET);
+    await inbox.put([item("a"), item("b"), item("c")]);
+    await inbox.markRead(["a"]);
+    expect(await inbox.unreadCount()).toBe(2);
+    await inbox.markAllRead();
+    expect(await inbox.unreadCount()).toBe(0);
+  });
+
+  it("prune drops the oldest read items first and keeps unread", async () => {
+    const inbox = createMemoryInbox("GA", NET);
+    await inbox.put([item("old-read", { createdAt: 1 }), item("old-unread", { createdAt: 2 }), item("new", { createdAt: 3 })]);
+    await inbox.markRead(["old-read"]);
+    await inbox.prune(2);
+    expect((await inbox.list()).map((i) => i.id).sort()).toEqual(["new", "old-unread"]);
+  });
+
+  it("falls back to memory when indexedDB throws", async () => {
+    const broken = { open: () => { throw new Error("SecurityError"); } } as unknown as IDBFactory;
+    const inbox = await openInbox("GA", NET, broken);
+    expect(inbox.persistent).toBe(false);
+    await inbox.put([item("a")]);
+    expect(await inbox.unreadCount()).toBe(1);
+  });
+
+  it("falls back to memory when indexedDB is unavailable", async () => {
+    const inbox = await openInbox("GA", NET, undefined);
+    expect(inbox.persistent).toBe(false);
+  });
+});
diff --git a/lib/notifications/classify.ts b/lib/notifications/classify.ts
new file mode 100644
index 0000000..a2dfdac
--- /dev/null
+++ b/lib/notifications/classify.ts
@@ -0,0 +1,122 @@
+import type { Position } from "@/lib/stellar/generated/market-core";
+import type { RedeemedEvent, ResolvedEvent } from "@/lib/stellar/events";
+import type { InboxItem } from "./store";
+
+/**
+ * Pure classifiers that turn validated socket payloads or decoded contract
+ * events into inbox items for one owner (issue #42). Anything that is not
+ * about the owner, or fails validation, returns null.
+ */
+
+const UINT = /^\d+$/;
+const HEX64 = /^[0-9a-f]{64}$/i;
+const isStr = (v: unknown): v is string => typeof v === "string" && v.length > 0;
+
+interface Ctx {
+  owner: string;
+  network: string;
+  now?: number;
+}
+
+const base = (ctx: Ctx, rest: Omit<InboxItem, "owner" | "network" | "readAt" | "createdAt"> & { createdAt?: number }): InboxItem => ({
+  owner: ctx.owner,
+  network: ctx.network,
+  readAt: null,
+  createdAt: rest.createdAt ?? ctx.now ?? Date.now(),
+  ...rest,
+});
+
+/** A TRADE_EXECUTED payload becomes a fill only when the owner is the trader. */
+export function classifyTrade(payload: unknown, ctx: Ctx): InboxItem | null {
+  if (!payload || typeof payload !== "object") return null;
+  const p = payload as Record<string, unknown>;
+  if (p.trader !== ctx.owner) return null;
+  if (!isStr(p.eventId) || !isStr(p.onChainMarketId) || !UINT.test(p.onChainMarketId)) return null;
+  if (!isStr(p.collateralRaw) || !UINT.test(p.collateralRaw)) return null;
+  if (!isStr(p.sharesRaw) || !UINT.test(p.sharesRaw)) return null;
+  if (!isStr(p.txHash) || !HEX64.test(p.txHash)) return null;
+  if (p.direction !== "YES" && p.direction !== "NO") return null;
+  if (typeof p.isBuy !== "boolean") return null;
+  return base(ctx, {
+    id: `fill:${p.eventId}`,
+    kind: "fill",
+    marketId: p.onChainMarketId,
+    txHash: p.txHash.toLowerCase(),
+    ledger: typeof p.ledger === "number" ? p.ledger : undefined,
+    data: {
+      direction: p.direction,
+      side: p.isBuy ? "buy" : "sell",
+      collateralRaw: p.collateralRaw,
+      sharesRaw: p.sharesRaw,
+      ...(isStr(p.marketQuestion) ? { marketQuestion: p.marketQuestion } : {}),
+    },
+  });
+}
+
+/** A REASONING_PUBLISHED payload becomes a trace item only for held markets. */
+export function classifyTrace(payload: unknown, heldMarketIds: ReadonlySet<string>, ctx: Ctx): InboxItem | null {
+  if (!payload || typeof payload !== "object") return null;
+  const p = payload as Record<string, unknown>;
+  if (!isStr(p.onChainMarketId) || !UINT.test(p.onChainMarketId)) return null;
+  if (!heldMarketIds.has(p.onChainMarketId)) return null;
+  if (!isStr(p.onChainTraceId) || !UINT.test(p.onChainTraceId)) return null;
+  return base(ctx, {
+    id: `trace:${p.onChainTraceId}`,
+    kind: "trace",
+    marketId: p.onChainMarketId,
+    txHash: isStr(p.txHash) && HEX64.test(p.txHash) ? p.txHash.toLowerCase() : undefined,
+    ledger: typeof p.ledger === "number" ? p.ledger : undefined,
+    data: {
+      onChainTraceId: p.onChainTraceId,
+      action: isStr(p.action) ? p.action : "",
+      ...(isStr(p.traceId) ? { traceId: p.traceId } : {}),
+    },
+  });
+}
+
+/** A resolved (or voided) market is redeemable if the owner still holds shares. */
+export function classifyResolved(decoded: ResolvedEvent, position: Position, ctx: Ctx): InboxItem | null {
+  if (position.yes + position.no <= 0n) return null;
+  return base(ctx, {
+    id: `redeemable:${decoded.marketId}`,
+    kind: "redeemable",
+    marketId: decoded.marketId,
+    ledger: decoded.ledger,
+    createdAt: Date.parse(decoded.closedAt) || undefined,
+    data: {
+      outcome: decoded.outcome ?? "void",
+      yes: position.yes.toString(),
+      no: position.no.toString(),
+    },
+  });
+}
+
+/** A Redeemed event is the owner's only when they are the holder. */
+export function classifyRedeemed(decoded: RedeemedEvent, ctx: Ctx): InboxItem | null {
+  if (decoded.holder !== ctx.owner) return null;
+  return base(ctx, {
+    id: `redeemed:${decoded.marketId}`,
+    kind: "redeemed",
+    marketId: decoded.marketId,
+    txHash: decoded.txHash,
+    ledger: decoded.ledger,
+    createdAt: Date.parse(decoded.closedAt) || undefined,
+    data: { payoutRaw: decoded.payout.toString() },
+  });
+}
+
+/** The owner's own failed or pending transaction. Rejections are not recorded. */
+export function classifyTx(
+  tx: { hash: string | null; kind: string; state: "pending" | "failed"; marketId?: string; errorKind?: string; message?: string },
+  ctx: Ctx,
+): InboxItem | null {
+  if (tx.errorKind === "rejected") return null;
+  const ref = tx.hash ?? `${tx.kind}:${tx.marketId ?? ""}:${ctx.now ?? Date.now()}`;
+  return base(ctx, {
+    id: `tx-${tx.state}:${ref}`,
+    kind: tx.state === "failed" ? "tx-failed" : "tx-pending",
+    marketId: tx.marketId,
+    txHash: tx.hash ?? undefined,
+    data: { action: tx.kind, ...(tx.message ? { message: tx.message } : {}) },
+  });
+}
diff --git a/lib/notifications/store.ts b/lib/notifications/store.ts
new file mode 100644
index 0000000..5e289dc
--- /dev/null
+++ b/lib/notifications/store.ts
@@ -0,0 +1,227 @@
+/**
+ * Per-wallet, per-network notification inbox persisted in IndexedDB
+ * (issue #42). Falls back to an in-memory store when IndexedDB is
+ * unavailable (private mode, quota, prerender).
+ */
+
+export type InboxKind = "fill" | "redeemable" | "redeemed" | "trace" | "tx-failed" | "tx-pending";
+
+export interface InboxItem {
+  /** Deterministic: `${kind}:${eventId|marketId|txHash}`. */
+  id: string;
+  owner: string;
+  network: string;
+  kind: InboxKind;
+  marketId?: string;
+  txHash?: string;
+  ledger?: number;
+  /** Ledger close time if known, else receipt time. */
+  createdAt: number;
+  readAt: number | null;
+  /** bigint values as decimal strings. */
+  data: Record<string, string>;
+}
+
+export interface ListOptions {
+  limit?: number;
+  unreadOnly?: boolean;
+}
+
+export interface Inbox {
+  readonly persistent: boolean;
+  put(items: InboxItem[]): Promise<void>;
+  list(opts?: ListOptions): Promise<InboxItem[]>;
+  markRead(ids: string[]): Promise<void>;
+  markAllRead(): Promise<void>;
+  unreadCount(): Promise<number>;
+  prune(max: number): Promise<void>;
+  getMeta(key: string): Promise<string | undefined>;
+  setMeta(key: string, value: string): Promise<void>;
+  close(): void;
+}
+
+export const DB_NAME = "oracledesk-inbox";
+const DB_VERSION = 1;
+const ITEMS = "items";
+const META = "meta";
+export const MAX_ITEMS = 500;
+
+const req = <T,>(r: IDBRequest<T>) =>
+  new Promise<T>((resolve, reject) => {
+    r.onsuccess = () => resolve(r.result);
+    r.onerror = () => reject(r.error);
+  });
+
+const done = (tx: IDBTransaction) =>
+  new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error);
+  });
+
+const byNewest = (a: InboxItem, b: InboxItem) => b.createdAt - a.createdAt || (a.id < b.id ? 1 : -1);
+
+/** Shared ordering/merge rules so both backends behave identically. */
+function mergeItem(existing: InboxItem | undefined, incoming: InboxItem): InboxItem {
+  // Idempotent on id; never resets readAt.
+  if (!existing) return incoming;
+  return { ...incoming, readAt: existing.readAt ?? incoming.readAt, createdAt: Math.min(existing.createdAt, incoming.createdAt) };
+}
+
+function pruneOrder(items: InboxItem[], max: number): InboxItem[] {
+  if (items.length <= max) return [];
+  // Oldest read items go first; unread items only if still over the cap.
+  const read = items.filter((i) => i.readAt !== null).sort((a, b) => a.createdAt - b.createdAt);
+  const unread = items.filter((i) => i.readAt === null).sort((a, b) => a.createdAt - b.createdAt);
+  return [...read, ...unread].slice(0, items.length - max);
+}
+
+export function createMemoryInbox(owner: string, network: string): Inbox {
+  const items = new Map<string, InboxItem>();
+  const meta = new Map<string, string>();
+  return {
+    persistent: false,
+    async put(list) {
+      for (const it of list) {
+        if (it.owner !== owner || it.network !== network) continue;
+        items.set(it.id, mergeItem(items.get(it.id), it));
+      }
+    },
+    async list(opts = {}) {
+      let out = [...items.values()].sort(byNewest);
+      if (opts.unreadOnly) out = out.filter((i) => i.readAt === null);
+      return opts.limit ? out.slice(0, opts.limit) : out;
+    },
+    async markRead(ids) {
+      const now = Date.now();
+      for (const id of ids) {
+        const it = items.get(id);
+        if (it && it.readAt === null) items.set(id, { ...it, readAt: now });
+      }
+    },
+    async markAllRead() {
+      const now = Date.now();
+      for (const [id, it] of items) if (it.readAt === null) items.set(id, { ...it, readAt: now });
+    },
+    async unreadCount() {
+      let n = 0;
+      for (const it of items.values()) if (it.readAt === null) n++;
+      return n;
+    },
+    async prune(max) {
+      for (const it of pruneOrder([...items.values()], max)) items.delete(it.id);
+    },
+    async getMeta(key) {
+      return meta.get(key);
+    },
+    async setMeta(key, value) {
+      meta.set(key, value);
+    },
+    close() {},
+  };
+}
+
+function openDb(factory: IDBFactory): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const open = factory.open(DB_NAME, DB_VERSION);
+    open.onupgradeneeded = () => {
+      const db = open.result;
+      if (!db.objectStoreNames.contains(ITEMS)) {
+        const store = db.createObjectStore(ITEMS, { keyPath: ["owner", "network", "id"] });
+        store.createIndex("byCreated", ["owner", "network", "createdAt"]);
+        store.createIndex("byOwner", ["owner", "network"]);
+      }
+      if (!db.objectStoreNames.contains(META)) db.createObjectStore(META, { keyPath: ["owner", "network", "key"] });
+    };
+    open.onsuccess = () => resolve(open.result);
+    open.onerror = () => reject(open.error);
+    open.onblocked = () => reject(new Error("IndexedDB open blocked"));
+  });
+}
+
+function createIdbInbox(db: IDBDatabase, owner: string, network: string): Inbox {
+  const range = () => IDBKeyRange.only([owner, network]);
+
+  const all = async (): Promise<InboxItem[]> => {
+    const tx = db.transaction(ITEMS, "readonly");
+    return req(tx.objectStore(ITEMS).index("byOwner").getAll(range())) as Promise<InboxItem[]>;
+  };
+
+  return {
+    persistent: true,
+    async put(list) {
+      const mine = list.filter((it) => it.owner === owner && it.network === network);
+      if (mine.length === 0) return;
+      const tx = db.transaction(ITEMS, "readwrite");
+      const store = tx.objectStore(ITEMS);
+      for (const it of mine) {
+        const getReq = store.get([owner, network, it.id]);
+        getReq.onsuccess = () => store.put(mergeItem(getReq.result as InboxItem | undefined, it));
+      }
+      await done(tx);
+    },
+    async list(opts = {}) {
+      let out = (await all()).sort(byNewest);
+      if (opts.unreadOnly) out = out.filter((i) => i.readAt === null);
+      return opts.limit ? out.slice(0, opts.limit) : out;
+    },
+    async markRead(ids) {
+      const now = Date.now();
+      const tx = db.transaction(ITEMS, "readwrite");
+      const store = tx.objectStore(ITEMS);
+      for (const id of ids) {
+        const getReq = store.get([owner, network, id]);
+        getReq.onsuccess = () => {
+          const it = getReq.result as InboxItem | undefined;
+          if (it && it.readAt === null) store.put({ ...it, readAt: now });
+        };
+      }
+      await done(tx);
+    },
+    async markAllRead() {
+      const items = await all();
+      await this.markRead(items.filter((i) => i.readAt === null).map((i) => i.id));
+    },
+    async unreadCount() {
+      return (await all()).filter((i) => i.readAt === null).length;
+    },
+    async prune(max) {
+      const victims = pruneOrder(await all(), max);
+      if (victims.length === 0) return;
+      const tx = db.transaction(ITEMS, "readwrite");
+      for (const it of victims) tx.objectStore(ITEMS).delete([owner, network, it.id]);
+      await done(tx);
+    },
+    async getMeta(key) {
+      const tx = db.transaction(META, "readonly");
+      const row = (await req(tx.objectStore(META).get([owner, network, key]))) as { value: string } | undefined;
+      return row?.value;
+    },
+    async setMeta(key, value) {
+      const tx = db.transaction(META, "readwrite");
+      tx.objectStore(META).put({ owner, network, key, value });
+      await done(tx);
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+/**
+ * Opens the inbox for one address on one network. Call only from effects:
+ * IndexedDB does not exist during prerender.
+ */
+export async function openInbox(
+  owner: string,
+  network: string,
+  factory: IDBFactory | undefined = typeof indexedDB === "undefined" ? undefined : indexedDB,
+): Promise<Inbox> {
+  if (!factory) return createMemoryInbox(owner, network);
+  try {
+    const db = await openDb(factory);
+    return createIdbInbox(db, owner, network);
+  } catch {
+    return createMemoryInbox(owner, network);
+  }
+}
diff --git a/lib/realtime/FeedProfiler.tsx b/lib/realtime/FeedProfiler.tsx
new file mode 100644
index 0000000..33ca9e9
--- /dev/null
+++ b/lib/realtime/FeedProfiler.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import React, { Profiler, useEffect, useState } from "react";
+
+/**
+ * Dev-only render profiler for realtime feeds (issue #41). Enabled with
+ * ?profile=1 outside production; logs commits and actualDuration per second.
+ * In production builds this renders children only and the branch is removed.
+ */
+export function FeedProfiler({ id, children }: { id: string; children: React.ReactNode }) {
+  const [enabled, setEnabled] = useState(false);
+
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+    setEnabled(new URLSearchParams(window.location.search).get("profile") === "1");
+  }, []);
+
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production" || !enabled) return;
+    const timer = setInterval(() => {
+      const s = stats.get(id);
+      if (s && s.commits > 0) {
+        console.info(`[profile] ${id}: ${s.commits} commits, ${s.duration.toFixed(1)}ms actual in the last second`);
+        stats.set(id, { commits: 0, duration: 0 });
+      }
+    }, 1_000);
+    return () => clearInterval(timer);
+  }, [enabled, id]);
+
+  if (process.env.NODE_ENV === "production" || !enabled) return <>{children}</>;
+  return (
+    <Profiler id={id} onRender={onRender}>
+      {children}
+    </Profiler>
+  );
+}
+
+const stats = new Map<string, { commits: number; duration: number }>();
+
+function onRender(id: string, _phase: string, actualDuration: number) {
+  const s = stats.get(id) ?? { commits: 0, duration: 0 };
+  s.commits++;
+  s.duration += actualDuration;
+  stats.set(id, s);
+}
diff --git a/lib/realtime/RealtimeProvider.tsx b/lib/realtime/RealtimeProvider.tsx
new file mode 100644
index 0000000..137eb77
--- /dev/null
+++ b/lib/realtime/RealtimeProvider.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import React, { createContext, useContext, useEffect, useRef, useState } from "react";
+import { io } from "socket.io-client";
+import { API_URL } from "@/lib/api/client";
+import { createBatcher, type Batcher, type BatchMeta } from "./batch";
+
+/** Payloads documented in docs/api.md (Realtime). */
+export interface TradeExecutedPayload {
+  onChainMarketId: string;
+  marketId: string | null;
+  marketQuestion: string | null;
+  trader: string;
+  direction: "YES" | "NO";
+  isBuy: boolean;
+  collateralRaw: string;
+  sharesRaw: string;
+  feeRaw: string;
+  priceYesBps: number;
+  txHash: string;
+  ledger: number;
+  eventId: string;
+}
+
+export interface ReasoningPublishedPayload {
+  onChainTraceId: string;
+  onChainMarketId: string;
+  traceId: string | null;
+  agent: string;
+  action: string;
+  ipfsCid?: string;
+  traceHash?: string;
+  txHash?: string;
+  ledger: number;
+}
+
+export interface RealtimeEvents {
+  TRADE_EXECUTED: TradeExecutedPayload;
+  REASONING_PUBLISHED: ReasoningPublishedPayload;
+}
+export type RealtimeEventName = keyof RealtimeEvents;
+
+const EVENT_NAMES: RealtimeEventName[] = ["TRADE_EXECUTED", "REASONING_PUBLISHED"];
+
+type Batchers = { [K in RealtimeEventName]: Batcher<RealtimeEvents[K]> };
+
+const RealtimeContext = createContext<Batchers | null>(null);
+
+function makeBatchers(): Batchers {
+  return {
+    TRADE_EXECUTED: createBatcher<TradeExecutedPayload>(),
+    REASONING_PUBLISHED: createBatcher<ReasoningPublishedPayload>(),
+  };
+}
+
+/**
+ * One socket for the app. Handlers only push into per-event batchers; React
+ * sees at most one batch per subscriber per animation frame (issue #41).
+ * Hidden tabs pause all batchers and get one catch-up batch on return.
+ */
+export function RealtimeProvider({ children }: { children: React.ReactNode }) {
+  const [batchers] = useState(makeBatchers);
+
+  useEffect(() => {
+    const socket = io(API_URL.replace(/\/api\/v1\/?$/, ""));
+    for (const name of EVENT_NAMES) {
+      socket.on(name, (payload: unknown) => {
+        if (payload && typeof payload === "object") {
+          (batchers[name] as Batcher<unknown>).push(payload);
+        }
+      });
+    }
+
+    const onVisibility = () => {
+      for (const name of EVENT_NAMES) batchers[name].setPaused(document.hidden);
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    onVisibility();
+
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibility);
+      socket.disconnect();
+    };
+  }, [batchers]);
+
+  return <RealtimeContext.Provider value={batchers}>{children}</RealtimeContext.Provider>;
+}
+
+/** Subscribe to per-frame batches of one realtime event. Idempotent under StrictMode. */
+export function useRealtimeBatch<K extends RealtimeEventName>(
+  eventName: K,
+  handler: (batch: readonly RealtimeEvents[K][], meta: BatchMeta) => void,
+) {
+  const batchers = useContext(RealtimeContext);
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+
+  useEffect(() => {
+    if (!batchers) return;
+    return batchers[eventName].subscribe((batch, meta) => handlerRef.current(batch as readonly RealtimeEvents[K][], meta));
+  }, [batchers, eventName]);
+}
diff --git a/lib/realtime/__tests__/batch.test.ts b/lib/realtime/__tests__/batch.test.ts
new file mode 100644
index 0000000..3305f9a
--- /dev/null
+++ b/lib/realtime/__tests__/batch.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { createBatcher } from "../batch";
+
+function fakeScheduler() {
+  const queue: Array<() => void> = [];
+  return {
+    schedule: (cb: () => void) => {
+      queue.push(cb);
+      return queue.length;
+    },
+    frame: () => queue.splice(0).forEach((cb) => cb()),
+    pending: () => queue.length,
+  };
+}
+
+describe("createBatcher", () => {
+  it("coalesces events pushed in one frame into one batch", () => {
+    const s = fakeScheduler();
+    const b = createBatcher<number>({ schedule: s.schedule });
+    const batches: number[][] = [];
+    b.subscribe((batch) => batches.push([...batch]));
+    b.push(1);
+    b.push(2);
+    b.push(3);
+    expect(s.pending()).toBe(1);
+    s.frame();
+    expect(batches).toEqual([[1, 2, 3]]);
+  });
+
+  it("delivers nothing while paused and one batch on resume", () => {
+    const s = fakeScheduler();
+    const b = createBatcher<number>({ schedule: s.schedule });
+    const metas: Array<{ batch: number[]; resumed: boolean }> = [];
+    b.subscribe((batch, meta) => metas.push({ batch: [...batch], resumed: meta.resumed }));
+    b.setPaused(true);
+    b.push(1);
+    b.push(2);
+    s.frame();
+    expect(metas).toEqual([]);
+    b.setPaused(false);
+    expect(metas).toEqual([{ batch: [1, 2], resumed: true }]);
+  });
+
+  it("caps a paused backlog at maxBatch and reports overflow", () => {
+    const s = fakeScheduler();
+    const b = createBatcher<number>({ schedule: s.schedule, maxBatch: 3 });
+    const seen: Array<{ n: number; overflow: number }> = [];
+    b.subscribe((batch, meta) => seen.push({ n: batch.length, overflow: meta.overflow }));
+    b.setPaused(true);
+    for (let i = 0; i < 10; i++) b.push(i);
+    b.setPaused(false);
+    expect(seen).toEqual([{ n: 3, overflow: 7 }]);
+  });
+
+  it("dispose cancels a scheduled flush", () => {
+    const s = fakeScheduler();
+    const b = createBatcher<number>({ schedule: s.schedule });
+    const batches: number[][] = [];
+    b.subscribe((batch) => batches.push([...batch]));
+    b.push(1);
+    b.dispose();
+    s.frame();
+    expect(batches).toEqual([]);
+  });
+});
diff --git a/lib/realtime/__tests__/burst.test.ts b/lib/realtime/__tests__/burst.test.ts
new file mode 100644
index 0000000..0437826
--- /dev/null
+++ b/lib/realtime/__tests__/burst.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { initialBurstState, reduceBatch } from "../burst";
+
+const key = (x: { id: string }) => x.id;
+const rows = (n: number) => Array.from({ length: n }, (_, i) => ({ id: String(i) }));
+
+describe("reduceBatch", () => {
+  it("flags a burst above the threshold", () => {
+    const s = reduceBatch(initialBurstState(8, key), rows(42), { overflow: 0, resumed: false }, { burstThreshold: 10, now: 1 });
+    expect(s.burst).toEqual({ count: 42, at: 1 });
+    expect(s.ring.size).toBe(8);
+    expect(s.instantKey).toBe(1);
+  });
+
+  it("does not flag normal batches", () => {
+    const s = reduceBatch(initialBurstState(8, key), rows(3), { overflow: 0, resumed: false }, { burstThreshold: 10, now: 1 });
+    expect(s.burst).toBeNull();
+    expect(s.instantKey).toBe(0);
+    // Newest (last in the batch) first.
+    expect(s.ring.toArray()[0].id).toBe("2");
+  });
+
+  it("reports overflow from a hidden-tab catch-up", () => {
+    const s = reduceBatch(initialBurstState(8, key), rows(5), { overflow: 12, resumed: true }, { burstThreshold: 100, now: 1 });
+    expect(s.hiddenOverflow).toBe(12);
+  });
+});
diff --git a/lib/realtime/__tests__/ring.test.ts b/lib/realtime/__tests__/ring.test.ts
new file mode 100644
index 0000000..ddb5339
--- /dev/null
+++ b/lib/realtime/__tests__/ring.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { Ring } from "../ring";
+
+const key = (x: { id: string }) => x.id;
+
+describe("Ring", () => {
+  it("keeps the newest capacity items", () => {
+    const r = new Ring(3, key).pushMany([{ id: "a" }, { id: "b" }]).pushMany([{ id: "c" }, { id: "d" }]);
+    expect(r.toArray().map(key)).toEqual(["c", "d", "a"]);
+  });
+
+  it("dedupes by key", () => {
+    const r = new Ring(5, key).pushMany([{ id: "a" }]).pushMany([{ id: "a" }, { id: "b" }]);
+    expect(r.toArray().map(key)).toEqual(["b", "a"]);
+  });
+
+  it("returns the same ring when nothing changes", () => {
+    const r = new Ring(5, key).pushMany([{ id: "a" }]);
+    expect(r.pushMany([{ id: "a" }])).toBe(r);
+    expect(r.pushMany([])).toBe(r);
+  });
+});
diff --git a/lib/realtime/batch.ts b/lib/realtime/batch.ts
new file mode 100644
index 0000000..473a65c
--- /dev/null
+++ b/lib/realtime/batch.ts
@@ -0,0 +1,103 @@
+/**
+ * Per-frame event batching between the socket and React (issue #41).
+ * Framework-free so it is unit-testable in node.
+ */
+
+export interface Batcher<E> {
+  push(e: E): void;
+  subscribe(fn: (batch: readonly E[], meta: BatchMeta) => void): () => void;
+  setPaused(paused: boolean): void;
+  dispose(): void;
+}
+
+export interface BatchMeta {
+  /** Events dropped because the pending batch hit maxBatch. */
+  overflow: number;
+  /** True when this batch is the catch-up flush after a pause. */
+  resumed: boolean;
+}
+
+type Schedule = (cb: () => void) => unknown;
+type Cancel = (handle: unknown) => void;
+
+const defaultSchedule: Schedule = (cb) =>
+  typeof requestAnimationFrame === "function" ? { raf: requestAnimationFrame(cb) } : { t: setTimeout(cb, 16) };
+
+const defaultCancel: Cancel = (h) => {
+  const handle = h as { raf?: number; t?: ReturnType<typeof setTimeout> };
+  if (handle.raf !== undefined && typeof cancelAnimationFrame === "function") cancelAnimationFrame(handle.raf);
+  if (handle.t !== undefined) clearTimeout(handle.t);
+};
+
+export function createBatcher<E>(opts: { schedule?: Schedule; cancel?: Cancel; maxBatch?: number } = {}): Batcher<E> {
+  const schedule = opts.schedule ?? defaultSchedule;
+  const cancel = opts.cancel ?? (opts.schedule ? () => {} : defaultCancel);
+  const maxBatch = opts.maxBatch ?? 500;
+  const subscribers = new Set<(batch: readonly E[], meta: BatchMeta) => void>();
+  let pending: E[] = [];
+  let overflow = 0;
+  let paused = false;
+  let resumed = false;
+  let handle: unknown = null;
+  let cancelled = false;
+  let disposed = false;
+
+  const flush = () => {
+    handle = null;
+    if (cancelled || disposed || paused || pending.length === 0) return;
+    const batch = pending;
+    const meta: BatchMeta = { overflow, resumed };
+    pending = [];
+    overflow = 0;
+    resumed = false;
+    for (const fn of subscribers) fn(batch, meta);
+  };
+
+  const ensureScheduled = () => {
+    // rAF does not fire in hidden tabs, so never schedule while paused.
+    if (handle !== null || paused || disposed) return;
+    cancelled = false;
+    handle = schedule(flush);
+  };
+
+  return {
+    push(e) {
+      if (disposed) return;
+      if (pending.length >= maxBatch) overflow++;
+      else pending.push(e);
+      ensureScheduled();
+    },
+    subscribe(fn) {
+      subscribers.add(fn);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    setPaused(next) {
+      if (next === paused) return;
+      paused = next;
+      if (paused) {
+        if (handle !== null) {
+          cancel(handle);
+          cancelled = true;
+          handle = null;
+        }
+        return;
+      }
+      if (pending.length > 0) {
+        resumed = true;
+        flush();
+      }
+    },
+    dispose() {
+      disposed = true;
+      if (handle !== null) {
+        cancel(handle);
+        cancelled = true;
+        handle = null;
+      }
+      pending = [];
+      subscribers.clear();
+    },
+  };
+}
diff --git a/lib/realtime/burst.ts b/lib/realtime/burst.ts
new file mode 100644
index 0000000..a706be0
--- /dev/null
+++ b/lib/realtime/burst.ts
@@ -0,0 +1,33 @@
+import { Ring } from "./ring";
+import type { BatchMeta } from "./batch";
+
+/** Pure reducer behind useBurstFeed (issue #41). */
+export interface BurstState<T> {
+  ring: Ring<T>;
+  burst: { count: number; at: number } | null;
+  /** Events dropped while the tab was hidden. */
+  hiddenOverflow: number;
+  /** Bumped when a batch should render without per-row animation. */
+  instantKey: number;
+}
+
+export function initialBurstState<T>(capacity: number, key: (row: T) => string): BurstState<T> {
+  return { ring: new Ring<T>(capacity, key), burst: null, hiddenOverflow: 0, instantKey: 0 };
+}
+
+export function reduceBatch<T>(
+  state: BurstState<T>,
+  rows: readonly T[],
+  meta: BatchMeta,
+  opts: { burstThreshold: number; now: number },
+): BurstState<T> {
+  // Batches arrive oldest first; the ring is newest first.
+  const ring = state.ring.pushMany([...rows].reverse());
+  const isBurst = rows.length + meta.overflow > opts.burstThreshold;
+  return {
+    ring,
+    burst: isBurst ? { count: rows.length + meta.overflow, at: opts.now } : null,
+    hiddenOverflow: meta.resumed ? meta.overflow : 0,
+    instantKey: isBurst || meta.resumed ? state.instantKey + 1 : state.instantKey,
+  };
+}
diff --git a/lib/realtime/ring.ts b/lib/realtime/ring.ts
new file mode 100644
index 0000000..ef9c18c
--- /dev/null
+++ b/lib/realtime/ring.ts
@@ -0,0 +1,47 @@
+/**
+ * Fixed-capacity, newest-first ring with stable keys (issue #41).
+ * Immutable on write: pushMany returns a new Ring (or the same one when
+ * nothing changed) so React state comparisons stay cheap.
+ */
+export class Ring<T> {
+  private readonly items: readonly T[];
+  readonly version: number;
+
+  constructor(
+    readonly capacity: number,
+    private readonly keyOf: (item: T) => string,
+    items: readonly T[] = [],
+    version = 0,
+  ) {
+    this.items = items;
+    this.version = version;
+  }
+
+  /** Items are given newest first. Duplicates (by key) are dropped. */
+  pushMany(incoming: readonly T[]): Ring<T> {
+    if (incoming.length === 0) return this;
+    const seen = new Set(this.items.map(this.keyOf));
+    const fresh: T[] = [];
+    for (const item of incoming) {
+      const k = this.keyOf(item);
+      if (seen.has(k)) continue;
+      seen.add(k);
+      fresh.push(item);
+    }
+    if (fresh.length === 0) return this;
+    const next = [...fresh, ...this.items].slice(0, this.capacity);
+    return new Ring(this.capacity, this.keyOf, next, this.version + 1);
+  }
+
+  clear(): Ring<T> {
+    return this.items.length === 0 ? this : new Ring(this.capacity, this.keyOf, [], this.version + 1);
+  }
+
+  toArray(): readonly T[] {
+    return this.items;
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+}
diff --git a/lib/realtime/useBurst.ts b/lib/realtime/useBurst.ts
new file mode 100644
index 0000000..4dd909c
--- /dev/null
+++ b/lib/realtime/useBurst.ts
@@ -0,0 +1,45 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { useRealtimeBatch, type RealtimeEventName, type RealtimeEvents } from "./RealtimeProvider";
+import { initialBurstState, reduceBatch, type BurstState } from "./burst";
+
+/**
+ * A bounded, stable-keyed feed for one realtime event. Batches above
+ * `burstThreshold` set `burst` so the UI can show one summary line instead
+ * of animating every row (issue #41).
+ */
+export function useBurstFeed<K extends RealtimeEventName, T>(
+  eventName: K,
+  opts: {
+    capacity: number;
+    burstThreshold?: number;
+    toRow: (e: RealtimeEvents[K]) => T | null;
+    key: (row: T) => string;
+  },
+): {
+  rows: readonly T[];
+  burst: BurstState<T>["burst"];
+  hiddenOverflow: number;
+  instantKey: number;
+} {
+  const { capacity, key, toRow } = opts;
+  const burstThreshold = opts.burstThreshold ?? 10;
+  const [state, setState] = useState(() => initialBurstState<T>(capacity, key));
+
+  const onBatch = useCallback(
+    (batch: readonly RealtimeEvents[K][], meta: { overflow: number; resumed: boolean }) => {
+      const rows: T[] = [];
+      for (const e of batch) {
+        const row = toRow(e);
+        if (row !== null) rows.push(row);
+      }
+      if (rows.length === 0 && meta.overflow === 0) return;
+      setState((prev) => reduceBatch(prev, rows, meta, { burstThreshold, now: Date.now() }));
+    },
+    [toRow, burstThreshold],
+  );
+  useRealtimeBatch(eventName, onBatch);
+
+  return { rows: state.ring.toArray(), burst: state.burst, hiddenOverflow: state.hiddenOverflow, instantKey: state.instantKey };
+}
diff --git a/lib/stellar/__tests__/events.test.ts b/lib/stellar/__tests__/events.test.ts
new file mode 100644
index 0000000..3e20358
--- /dev/null
+++ b/lib/stellar/__tests__/events.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { nativeToScVal, xdr } from "@stellar/stellar-sdk";
+import { priceYesBps } from "../generated/fpmm";
+import {
+  clearTradeCache,
+  decodeTrade,
+  eventPrefix,
+  fetchMarketTrades,
+  tradeTopicFilter,
+  type EventsServer,
+  type RawEvent,
+} from "../events";
+
+const TRADER = "GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN7";
+
+function tradeEvent(id: string, ledger: number, marketId = 7n): RawEvent {
+  const body = xdr.ScVal.scvMap([
+    ["collateral", nativeToScVal(10_000_000n, { type: "i128" })],
+    ["fee", nativeToScVal(200_000n, { type: "i128" })],
+    ["is_buy", xdr.ScVal.scvBool(true)],
+    ["outcome", xdr.ScVal.scvVec([xdr.ScVal.scvSymbol("Yes")])],
+    ["reserve_no", nativeToScVal(60_000_000n, { type: "i128" })],
+    ["reserve_yes", nativeToScVal(40_000_000n, { type: "i128" })],
+    ["shares", nativeToScVal(15_873_015n, { type: "i128" })],
+  ].map(([k, v]) => new xdr.ScMapEntry({ key: xdr.ScVal.scvSymbol(k as string), val: v as xdr.ScVal })));
+  return {
+    id,
+    ledger,
+    ledgerClosedAt: "2026-10-01T00:00:00Z",
+    txHash: "a".repeat(64),
+    topic: [xdr.ScVal.scvSymbol("trade"), nativeToScVal(marketId, { type: "u64" }), nativeToScVal(TRADER, { type: "address" })],
+    value: body,
+  };
+}
+
+describe("tradeTopicFilter", () => {
+  it("encodes the market id as scvU64 and wildcards the trader", () => {
+    const [name, market, trader] = tradeTopicFilter(7n);
+    expect(xdr.ScVal.fromXDR(market, "base64").switch().name).toBe("scvU64");
+    expect(xdr.ScVal.fromXDR(name, "base64").sym().toString()).toBe("trade");
+    expect(trader).toBe("*");
+  });
+
+  it("reads the event name from the contract spec", () => {
+    expect(eventPrefix("Trade")).toBe("trade");
+    expect(eventPrefix("MarketResolved")).toBe("market_resolved");
+  });
+});
+
+describe("decodeTrade", () => {
+  it("decodes into a TradeRow with bigint amounts and the exact post-trade price", () => {
+    const row = decodeTrade(tradeEvent("e1", 10));
+    expect(row).toMatchObject({ marketId: "7", trader: TRADER, outcome: "Yes", isBuy: true, collateral: 10_000_000n, fee: 200_000n });
+    expect(row.yesBpsAfter).toBe(Number(priceYesBps(40_000_000n, 60_000_000n)));
+  });
+});
+
+function fakeServer(events: RawEvent[], oldestLedger: number, latestLedger: number): EventsServer & { starts: number[] } {
+  const starts: number[] = [];
+  return {
+    starts,
+    getHealth: async () => ({ oldestLedger, latestLedger }),
+    getEvents: async (req) => {
+      const start = (req as { startLedger?: number }).startLedger ?? oldestLedger;
+      starts.push(start);
+      return { events: events.filter((e) => e.ledger >= start), latestLedger };
+    },
+  };
+}
+
+describe("fetchMarketTrades", () => {
+  beforeEach(() => clearTradeCache());
+
+  it("widens the window until want is satisfied", async () => {
+    const server = fakeServer([tradeEvent("old", 95_000), tradeEvent("new", 99_500)], 1_000, 100_000);
+    const res = await fetchMarketTrades(7n, { want: 2, server });
+    expect(res.trades.map((t) => t.id)).toEqual(["new", "old"]);
+    expect(server.starts[0]).toBe(98_000);
+    expect(server.starts.length).toBeGreaterThan(1);
+    expect(res.reachedRetention).toBe(false);
+  });
+
+  it("reports reachedRetention at oldestLedger", async () => {
+    const server = fakeServer([tradeEvent("only", 99_900)], 99_000, 100_000);
+    const res = await fetchMarketTrades(7n, { want: 5, server });
+    expect(res.trades).toHaveLength(1);
+    expect(res.reachedRetention).toBe(true);
+    expect(Math.min(...server.starts)).toBe(99_000);
+  });
+});
diff --git a/lib/stellar/__tests__/optimistic.test.ts b/lib/stellar/__tests__/optimistic.test.ts
new file mode 100644
index 0000000..df4e076
--- /dev/null
+++ b/lib/stellar/__tests__/optimistic.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyBuy,
+  applyRedeem,
+  applySell,
+  balanceDelta,
+  bigintEquals,
+  guardRead,
+  positionEquals,
+  reconcile,
+  stackProvisional,
+  type Stamped,
+} from "../optimistic";
+import type { Position } from "../generated/market-core";
+
+const pos = (yes: bigint, no: bigint): Position => ({ yes, no });
+
+describe("delta functions", () => {
+  it("applyBuy adds to the chosen side", () => {
+    expect(applyBuy(pos(1n, 2n), "Yes", 5n)).toEqual(pos(6n, 2n));
+    expect(applyBuy(pos(1n, 2n), "No", 5n)).toEqual(pos(1n, 7n));
+  });
+
+  it("applySell throws below zero", () => {
+    expect(applySell(pos(5n, 0n), "Yes", 5n)).toEqual(pos(0n, 0n));
+    expect(() => applySell(pos(4n, 0n), "Yes", 5n)).toThrow(RangeError);
+  });
+
+  it("applyRedeem zeroes both sides", () => {
+    expect(applyRedeem()).toEqual(pos(0n, 0n));
+  });
+
+  it("balanceDelta signs per kind", () => {
+    expect(balanceDelta({ kind: "buy", collateralIn: 10n })).toBe(-10n);
+    expect(balanceDelta({ kind: "sell", collateralOut: 7n })).toBe(7n);
+    expect(balanceDelta({ kind: "redeem", payout: 0n })).toBe(0n);
+  });
+});
+
+describe("ledger-aware cache rules", () => {
+  const provisional: Stamped<bigint> = { value: 90n, ledger: 100, provisional: { txHash: "ab", ledger: 100, kind: "buy" } };
+
+  it("a stale read at a lower ledger does not overwrite a provisional value", () => {
+    expect(guardRead(provisional, { value: 100n, ledger: 99 })).toBe(provisional);
+  });
+
+  it("a read at or above the tx ledger wins", () => {
+    expect(guardRead(provisional, { value: 90n, ledger: 100 })).toEqual({ value: 90n, ledger: 100 });
+  });
+
+  it("reconcile clears provisional on match", () => {
+    const r = reconcile(provisional, { value: 90n, ledger: 101 }, bigintEquals);
+    expect(r.status).toBe("match");
+    if (r.status === "match") expect(r.next.provisional).toBeUndefined();
+  });
+
+  it("reconcile replaces with the chain value on mismatch", () => {
+    const r = reconcile(provisional, { value: 80n, ledger: 101 }, bigintEquals);
+    expect(r).toMatchObject({ status: "mismatch", expected: 90n, actual: 80n, next: { value: 80n } });
+  });
+
+  it("reconcile reports lagging below the tx ledger", () => {
+    expect(reconcile(provisional, { value: 100n, ledger: 50 }, bigintEquals).status).toBe("lagging");
+  });
+
+  it("two consecutive buys stack and keep the highest ledger", () => {
+    const first = stackProvisional<Position>({ value: pos(0n, 0n), ledger: 10 }, pos(5n, 0n), { txHash: "a", ledger: 20, kind: "buy" });
+    const second = stackProvisional(first, applyBuy(first.value, "Yes", 3n), { txHash: "b", ledger: 22, kind: "buy" });
+    expect(second.value).toEqual(pos(8n, 0n));
+    expect(second.provisional?.ledger).toBe(22);
+    expect(positionEquals(second.value, pos(8n, 0n))).toBe(true);
+  });
+});
diff --git a/lib/stellar/events.ts b/lib/stellar/events.ts
new file mode 100644
index 0000000..b7ea513
--- /dev/null
+++ b/lib/stellar/events.ts
@@ -0,0 +1,286 @@
+import { nativeToScVal, rpc, scValToNative, xdr } from "@stellar/stellar-sdk";
+import { marketCore, rpcServer, type OutcomeTag } from "./clients";
+import { CONTRACTS } from "./config";
+import { priceYesBps } from "./generated/fpmm";
+
+/**
+ * Contract event helpers backed by Stellar RPC getEvents (issues #40, #42).
+ *
+ * Topic layout for market-core events: [<event name symbol>, ...indexed fields].
+ * The name symbol comes from the contract spec, not a hard-coded string.
+ */
+
+const snake = (name: string) => name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+
+/** The prefix topic symbol for a market-core event, read from the shipped spec. */
+export function eventPrefix(eventName: "Trade" | "Redeemed" | "MarketResolved"): string {
+  try {
+    const entries = (marketCore().spec as unknown as { entries: xdr.ScSpecEntry[] }).entries;
+    for (const entry of entries) {
+      if (entry.switch().value !== xdr.ScSpecEntryKind.scSpecEntryEventV0().value) continue;
+      const ev = entry.eventV0();
+      if (ev.name().toString() !== eventName) continue;
+      const prefix = ev.prefixTopics();
+      if (prefix.length > 0) return prefix[0].toString();
+    }
+  } catch {
+    // Fall through to the #[contractevent] default (snake_case struct name).
+  }
+  return snake(eventName);
+}
+
+const symbolTopic = (s: string) => xdr.ScVal.scvSymbol(s).toXDR("base64");
+const u64Topic = (n: bigint) => nativeToScVal(n, { type: "u64" }).toXDR("base64");
+const addressTopic = (a: string) => nativeToScVal(a, { type: "address" }).toXDR("base64");
+
+export function tradeTopicFilter(marketId: bigint): string[] {
+  return [symbolTopic(eventPrefix("Trade")), u64Topic(marketId), "*"];
+}
+
+export function resolvedTopicFilter(marketId: bigint): string[] {
+  return [symbolTopic(eventPrefix("MarketResolved")), u64Topic(marketId)];
+}
+
+export function redeemedTopicFilter(holder: string): string[] {
+  return [symbolTopic(eventPrefix("Redeemed")), "*", addressTopic(holder)];
+}
+
+export interface RawEvent {
+  id: string;
+  ledger: number;
+  ledgerClosedAt: string;
+  txHash: string;
+  topic: xdr.ScVal[];
+  value: xdr.ScVal;
+}
+
+export interface TradeRow {
+  id: string;
+  ledger: number;
+  closedAt: string;
+  txHash: string;
+  marketId: string;
+  trader: string;
+  outcome: OutcomeTag;
+  isBuy: boolean;
+  collateral: bigint;
+  shares: bigint;
+  fee: bigint;
+  reserveYes: bigint;
+  reserveNo: bigint;
+  yesBpsAfter: number;
+  origin?: "rpc" | "socket";
+}
+
+const outcomeTag = (v: unknown): OutcomeTag => {
+  const tag = Array.isArray(v) ? v[0] : (v as { tag?: string })?.tag ?? v;
+  if (tag !== "Yes" && tag !== "No") throw new Error(`Unexpected outcome ${String(tag)}`);
+  return tag;
+};
+
+const big = (v: unknown) => (typeof v === "bigint" ? v : BigInt(v as number | string));
+
+function fields(value: xdr.ScVal): Record<string, unknown> {
+  const native = scValToNative(value) as unknown;
+  if (native && typeof native === "object" && !Array.isArray(native)) return native as Record<string, unknown>;
+  throw new Error("Expected a map-shaped event body");
+}
+
+export function decodeTrade(ev: RawEvent): TradeRow {
+  const marketId = big(scValToNative(ev.topic[1])).toString();
+  const trader = String(scValToNative(ev.topic[2]));
+  const f = fields(ev.value);
+  const reserveYes = big(f.reserve_yes);
+  const reserveNo = big(f.reserve_no);
+  return {
+    id: ev.id,
+    ledger: ev.ledger,
+    closedAt: ev.ledgerClosedAt,
+    txHash: ev.txHash,
+    marketId,
+    trader,
+    outcome: outcomeTag(f.outcome),
+    isBuy: Boolean(f.is_buy),
+    collateral: big(f.collateral),
+    shares: big(f.shares),
+    fee: big(f.fee),
+    reserveYes,
+    reserveNo,
+    yesBpsAfter: Number(priceYesBps(reserveYes, reserveNo)),
+    origin: "rpc",
+  };
+}
+
+export interface ResolvedEvent {
+  id: string;
+  ledger: number;
+  closedAt: string;
+  marketId: string;
+  /** null = voided (still redeemable at half of each side). */
+  outcome: OutcomeTag | null;
+}
+
+export function decodeResolved(ev: RawEvent): ResolvedEvent {
+  const marketId = big(scValToNative(ev.topic[1])).toString();
+  const f = fields(ev.value);
+  const raw = f.outcome;
+  return {
+    id: ev.id,
+    ledger: ev.ledger,
+    closedAt: ev.ledgerClosedAt,
+    marketId,
+    outcome: raw === undefined || raw === null ? null : outcomeTag(raw),
+  };
+}
+
+export interface RedeemedEvent {
+  id: string;
+  ledger: number;
+  closedAt: string;
+  txHash: string;
+  marketId: string;
+  holder: string;
+  payout: bigint;
+}
+
+export function decodeRedeemed(ev: RawEvent): RedeemedEvent {
+  const f = fields(ev.value);
+  return {
+    id: ev.id,
+    ledger: ev.ledger,
+    closedAt: ev.ledgerClosedAt,
+    txHash: ev.txHash,
+    marketId: big(scValToNative(ev.topic[1])).toString(),
+    holder: String(scValToNative(ev.topic[2])),
+    payout: big(f.payout),
+  };
+}
+
+/** The subset of rpc.Server used here, so tests can fake it. */
+export interface EventsServer {
+  getHealth(): Promise<{ oldestLedger: number; latestLedger: number }>;
+  getEvents(req: rpc.Server.GetEventsRequest): Promise<{
+    events: Array<{ id: string; ledger: number; ledgerClosedAt: string; txHash: string; topic: xdr.ScVal[]; value: xdr.ScVal }>;
+    cursor?: string;
+    latestLedger: number;
+  }>;
+}
+
+const defaultServer = (): EventsServer => rpcServer() as unknown as EventsServer;
+
+/** Pages forward from startLedger through all events matching the filter. */
+async function collectForward(
+  server: EventsServer,
+  topics: string[][],
+  startLedger: number,
+  signal?: AbortSignal,
+  pageLimit = 200,
+): Promise<{ events: RawEvent[]; latestLedger: number; cursor: string }> {
+  const events: RawEvent[] = [];
+  let cursor: string | undefined;
+  let latestLedger = startLedger;
+  for (let page = 0; page < 50; page++) {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    const filters = [{ type: "contract" as const, contractIds: [CONTRACTS.marketCore], topics }];
+    const res = await server.getEvents(
+      (cursor
+        ? { filters, cursor, limit: pageLimit }
+        : { filters, startLedger, limit: pageLimit }) as rpc.Server.GetEventsRequest,
+    );
+    latestLedger = res.latestLedger;
+    for (const e of res.events) {
+      events.push({ id: e.id, ledger: e.ledger, ledgerClosedAt: e.ledgerClosedAt, txHash: e.txHash, topic: e.topic, value: e.value });
+    }
+    if (res.events.length < pageLimit || !res.cursor) {
+      cursor = res.cursor;
+      break;
+    }
+    cursor = res.cursor;
+  }
+  return { events, latestLedger, cursor: cursor ?? "" };
+}
+
+const PROBE_WINDOWS = [2_000, 8_000, 32_000, 128_000] as const;
+export const MAX_TAPE_ROWS = 2_000;
+
+interface TradeCacheEntry {
+  trades: TradeRow[];
+  fromLedger: number;
+  cursor: string;
+  reachedRetention: boolean;
+  latestLedger: number;
+}
+const tradeCache = new Map<string, TradeCacheEntry>();
+
+/** Test hook. */
+export function clearTradeCache() {
+  tradeCache.clear();
+}
+
+/**
+ * Newest `want` Trade events for one market, newest first. RPC only pages
+ * forward, so windows widen backwards from the tip until enough events are
+ * found or RPC retention (oldestLedger) is reached.
+ */
+export async function fetchMarketTrades(
+  marketId: bigint,
+  opts: { want: number; signal?: AbortSignal; server?: EventsServer },
+): Promise<{ trades: TradeRow[]; reachedRetention: boolean; latestLedger: number; cursor: string }> {
+  const server = opts.server ?? defaultServer();
+  const topics = [tradeTopicFilter(marketId)];
+  const key = marketId.toString();
+  const cached = tradeCache.get(key);
+  if (cached && (cached.trades.length >= opts.want || cached.reachedRetention)) {
+    return { ...cached, trades: cached.trades.slice(0, opts.want) };
+  }
+
+  let health = await server.getHealth();
+  let found: RawEvent[] = [];
+  let fromLedger = health.latestLedger;
+  let cursor = "";
+  let latestLedger = health.latestLedger;
+  let reachedRetention = false;
+
+  for (const span of [...PROBE_WINDOWS, Infinity]) {
+    fromLedger = Math.max(health.oldestLedger, health.latestLedger - span);
+    let res;
+    try {
+      res = await collectForward(server, topics, fromLedger, opts.signal);
+    } catch (err) {
+      // Retention moved under us: re-read the window once and retry.
+      if (err instanceof DOMException) throw err;
+      health = await server.getHealth();
+      fromLedger = Math.max(health.oldestLedger, fromLedger);
+      res = await collectForward(server, topics, fromLedger, opts.signal);
+    }
+    found = res.events;
+    cursor = res.cursor;
+    latestLedger = res.latestLedger;
+    reachedRetention = fromLedger <= health.oldestLedger;
+    if (found.length >= opts.want || reachedRetention) break;
+  }
+
+  const trades: TradeRow[] = [];
+  for (let i = found.length - 1; i >= 0 && trades.length < MAX_TAPE_ROWS; i--) {
+    try {
+      trades.push(decodeTrade(found[i]));
+    } catch {
+      // Skip events that do not decode with the shipped spec.
+    }
+  }
+  const entry = { trades, fromLedger, cursor, reachedRetention, latestLedger };
+  tradeCache.set(key, entry);
+  return { trades: trades.slice(0, opts.want), reachedRetention, latestLedger, cursor };
+}
+
+/** All events matching `topics` from `startLedger` (clamped to retention). */
+export async function fetchEventsSince(
+  topics: string[][],
+  startLedger: number,
+  server: EventsServer = defaultServer(),
+): Promise<{ events: RawEvent[]; latestLedger: number }> {
+  const health = await server.getHealth();
+  const from = Math.max(health.oldestLedger, startLedger || health.latestLedger - 2_000);
+  const { events, latestLedger } = await collectForward(server, topics, from);
+  return { events, latestLedger };
+}
diff --git a/lib/stellar/optimistic.ts b/lib/stellar/optimistic.ts
new file mode 100644
index 0000000..5fae810
--- /dev/null
+++ b/lib/stellar/optimistic.ts
@@ -0,0 +1,100 @@
+import type { OutcomeTag } from "./clients";
+import type { Position } from "./generated/market-core";
+
+/**
+ * Optimistic position/balance updates (issue #39).
+ *
+ * After a confirmed write we know the exact contract-returned amounts, so the
+ * caches are updated immediately and marked provisional. Reads whose
+ * simulation ledger is below the tx ledger are ignored until the RPC catches
+ * up; the chain value always wins once it does.
+ */
+
+export type WriteKind = "buy" | "sell" | "redeem";
+
+export interface Provisional {
+  txHash: string | null;
+  ledger: number;
+  kind: WriteKind;
+  /** Set when reconciliation gave up waiting for the RPC to reach `ledger`. */
+  awaitingRpc?: boolean;
+}
+
+export interface Stamped<T> {
+  value: T;
+  ledger: number;
+  provisional?: Provisional;
+}
+
+export function applyBuy(p: Position, outcome: OutcomeTag, sharesOut: bigint): Position {
+  return outcome === "Yes" ? { yes: p.yes + sharesOut, no: p.no } : { yes: p.yes, no: p.no + sharesOut };
+}
+
+export function applySell(p: Position, outcome: OutcomeTag, sharesSold: bigint): Position {
+  const next = outcome === "Yes" ? { yes: p.yes - sharesSold, no: p.no } : { yes: p.yes, no: p.no - sharesSold };
+  if (next.yes < 0n || next.no < 0n) throw new RangeError("applySell would make the position negative");
+  return next;
+}
+
+export function applyRedeem(): Position {
+  return { yes: 0n, no: 0n };
+}
+
+export type WriteResult =
+  | { kind: "buy"; collateralIn: bigint }
+  | { kind: "sell"; collateralOut: bigint }
+  | { kind: "redeem"; payout: bigint };
+
+/** Signed change to the holder's USDC balance. */
+export function balanceDelta(r: WriteResult): bigint {
+  switch (r.kind) {
+    case "buy":
+      return -r.collateralIn;
+    case "sell":
+      return r.collateralOut;
+    case "redeem":
+      return r.payout;
+  }
+}
+
+/**
+ * Decides what a query function should store given the cached value and a
+ * fresh read. A read below a provisional ledger is stale and must not win.
+ */
+export function guardRead<T>(cached: Stamped<T> | undefined, fresh: Stamped<T>): Stamped<T> {
+  if (cached?.provisional && fresh.ledger < cached.provisional.ledger) return cached;
+  return fresh;
+}
+
+export type ReconcileOutcome<T> =
+  | { status: "lagging" }
+  | { status: "match"; next: Stamped<T> }
+  | { status: "mismatch"; next: Stamped<T>; expected: T; actual: T };
+
+export function reconcile<T>(
+  provisional: Stamped<T>,
+  fresh: Stamped<T>,
+  equals: (a: T, b: T) => boolean,
+): ReconcileOutcome<T> {
+  const minLedger = provisional.provisional?.ledger ?? 0;
+  if (fresh.ledger < minLedger) return { status: "lagging" };
+  const next: Stamped<T> = { value: fresh.value, ledger: fresh.ledger };
+  if (equals(provisional.value, fresh.value)) return { status: "match", next };
+  return { status: "mismatch", next, expected: provisional.value, actual: fresh.value };
+}
+
+export const positionEquals = (a: Position, b: Position) => a.yes === b.yes && a.no === b.no;
+export const bigintEquals = (a: bigint, b: bigint) => a === b;
+
+/** Stacks a provisional write on top of whatever is cached (possibly another provisional). */
+export function stackProvisional<T>(
+  base: Stamped<T>,
+  value: T,
+  p: Provisional,
+): Stamped<T> {
+  const ledger = Math.max(p.ledger, base.provisional?.ledger ?? 0);
+  return { value, ledger: Math.max(base.ledger, ledger), provisional: { ...p, ledger } };
+}
+
+/** Retry schedule for reconciliation reads, in ms after the write. */
+export const RECONCILE_DELAYS_MS = [1_000, 3_000, 8_000] as const;
diff --git a/lib/stellar/tx-lifecycle.ts b/lib/stellar/tx-lifecycle.ts
index 1ec48dd..8ea9dc6 100644
--- a/lib/stellar/tx-lifecycle.ts
+++ b/lib/stellar/tx-lifecycle.ts
@@ -99,7 +99,7 @@ export class TxLifecycle<T> {
   async run(
     tx: AssembledTransaction<T>,
     parse: (v: xdr.ScVal | undefined) => T,
-  ): Promise<{ value: T; txHash: string }> {
+  ): Promise<{ value: T; txHash: string; ledger: number | null }> {
     // 1. Simulating
     this.setPhase({ name: "simulating" });
     try {
@@ -202,13 +202,15 @@ export class TxLifecycle<T> {
         } catch {
           value = (getRes.returnValue ? scValToNative(getRes.returnValue) : null) as T;
         }
+        const ledger = getRes.ledger ?? getRes.latestLedger;
         this.setPhase({
           name: "confirmed",
           hash,
-          ledger: getRes.ledger ?? getRes.latestLedger,
+          ledger,
           returnValue: getRes.returnValue,
         });
-        return { value, txHash: hash };
+        // The ledger the tx landed in; reads at or after it reflect the write.
+        return { value, txHash: hash, ledger: typeof getRes.ledger === "number" ? getRes.ledger : null };
       }
 
       if (getRes.status === "FAILED") {
diff --git a/lib/stellar/typed-call.ts b/lib/stellar/typed-call.ts
index b80e0ee..7748a2c 100644
--- a/lib/stellar/typed-call.ts
+++ b/lib/stellar/typed-call.ts
@@ -96,3 +96,16 @@ export async function submit<Tx extends AssembledTransaction<any>>(
  * the binding method signature without requiring explicit type arguments.
  */
 export const simulated = read;
+
+/**
+ * Like `read`, but also returns the ledger the simulation ran against, so
+ * caches can tell a stale read from a fresh one.
+ */
+export function simulatedWithLedger<Tx extends AssembledTransaction<any>>(
+  tx: Tx,
+  contract: ContractName = "marketCore",
+): { value: Unwrapped<TxValue<Tx>>; ledger: number } {
+  const value = read(tx, contract);
+  const sim = tx.simulation as { latestLedger?: number } | undefined;
+  return { value, ledger: sim?.latestLedger ?? 0 };
+}
diff --git a/scripts/realtime-burst.mjs b/scripts/realtime-burst.mjs
new file mode 100644
index 0000000..29040f7
--- /dev/null
+++ b/scripts/realtime-burst.mjs
@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Dev-only burst simulator for realtime feeds (issue #41).
+ *
+ * Starts a local socket.io server and emits synthetic TRADE_EXECUTED payloads
+ * shaped like docs/api.md. Point the app at it with
+ *   NEXT_PUBLIC_API_URL=http://localhost:4100/api/v1 npm run dev
+ *
+ * Usage: node scripts/realtime-burst.mjs --count 500 --rate 500 [--port 4100] [--market 0]
+ *
+ * socket.io (the server package) is not a project dependency; install it
+ * locally without saving: npm i --no-save socket.io@4.8.1
+ */
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+
+const arg = (name, fallback) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : fallback;
+};
+const count = Number(arg("count", 500));
+const rate = Number(arg("rate", 500));
+const port = Number(arg("port", 4100));
+const market = String(arg("market", "0"));
+
+let Server;
+try {
+  ({ Server } = await import("socket.io"));
+} catch {
+  console.error("socket.io is not installed. Run: npm i --no-save socket.io@4.8.1");
+  process.exit(1);
+}
+
+const http = createServer((_, res) => res.writeHead(404).end());
+const io = new Server(http, { cors: { origin: "*" } });
+let ledger = 1_000_000;
+
+function payload(i) {
+  const isYes = Math.random() < 0.5;
+  return {
+    onChainMarketId: market,
+    marketId: null,
+    marketQuestion: `Synthetic burst market #${market}`,
+    trader: "GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN7",
+    direction: isYes ? "YES" : "NO",
+    isBuy: Math.random() < 0.8,
+    collateralRaw: String(10_000_000 + Math.floor(Math.random() * 90_000_000)),
+    sharesRaw: String(15_000_000 + Math.floor(Math.random() * 90_000_000)),
+    feeRaw: "200000",
+    priceYesBps: 3000 + Math.floor(Math.random() * 4000),
+    txHash: randomBytes(32).toString("hex"),
+    ledger: (ledger += i % 5 === 0 ? 1 : 0),
+    eventId: `${String(ledger).padStart(19, "0")}-${String(i).padStart(10, "0")}`,
+  };
+}
+
+io.on("connection", (socket) => {
+  console.log(`client connected (${socket.id}); emitting ${count} events at ${rate}/s`);
+  let sent = 0;
+  const perTick = Math.max(1, Math.round(rate / 100));
+  const timer = setInterval(() => {
+    for (let k = 0; k < perTick && sent < count; k++) socket.emit("TRADE_EXECUTED", payload(sent++));
+    if (sent >= count) {
+      clearInterval(timer);
+      console.log(`done: ${sent} events`);
+    }
+  }, 10);
+  socket.on("disconnect", () => clearInterval(timer));
+});
+
+http.listen(port, () => console.log(`burst server on http://localhost:${port}`));