Merge pull request #179 from shirtlessfounder/feat/platform-stats-177

feat: add /stats endpoint for live platform statistics

Author: spiceoogway

routes/meta.py

@@ -132,3 +132,29 @@ async def get_currency():
         "starting_balance": STARTING_BALANCE,
         "note": "MoltMarkets uses points (ŧ), not real money. All balances and amounts are in points.",
     }
+
+
+@router.get("/stats")
+async def get_platform_stats():
+    """Get live platform statistics for homepage display.
+
+    Returns counts for agents (with claimed/pending breakdown),
+    markets, and total trading volume.
+
+    See: https://github.com/shirtlessfounder/moltmarkets-api/issues/177
+    """
+    db = get_db()
+    agent_counts = db.count_agents_by_status()
+    market_count = db.count_markets()
+    total_volume = db.get_platform_volume()
+
+    return {
+        "agents": {
+            "total": agent_counts["total"],
+            "claimed": agent_counts["claimed"],
+            "pending": agent_counts["pending"],
+        },
+        "markets": market_count,
+        "volume": round(total_volume, 3),
+        "currency": CURRENCY_SYMBOL,
+    }

storage/markets.py

@@ -94,6 +94,24 @@ def count_markets(self) -> int:
         finally:
             self._put_conn(conn)
 
+    def get_platform_volume(self) -> float:
+        """Get total trading volume across all markets.
+
+        O(1) via SUM aggregate instead of O(N) full-table load.
+
+        See: https://github.com/shirtlessfounder/moltmarkets-api/issues/177
+        """
+        if self._use_memory:
+            return sum(m.get("total_volume", 0.0) for m in self._markets.values())
+
+        conn = self._get_conn()
+        try:
+            with conn.cursor() as cur:
+                cur.execute("SELECT COALESCE(SUM(total_volume), 0) AS total FROM markets")
+                return float(cur.fetchone()["total"])
+        finally:
+            self._put_conn(conn)
+
     def get_markets_by_ids(self, market_ids: set) -> Dict[str, MarketDict]:
         """Get specific markets by their IDs in a single query.
 

storage/users.py

@@ -351,6 +351,55 @@ def count_users(self) -> int:
         finally:
             self._put_conn(conn)
 
+    def count_agents_by_status(self) -> dict:
+        """Count agents grouped by status (claimed/pending/etc).
+
+        Returns dict with keys: total, claimed, pending, other.
+        Excludes sandbox agents from counts.
+
+        See: https://github.com/shirtlessfounder/moltmarkets-api/issues/177
+        """
+        if self._use_memory:
+            total = claimed = pending = 0
+            for user in self._users.values():
+                if user.get("user_type") != "agent" or user.get("is_sandbox"):
+                    continue
+                total += 1
+                status = user.get("status", "pending")
+                if status == "claimed":
+                    claimed += 1
+                elif status == "pending":
+                    pending += 1
+            return {
+                "total": total,
+                "claimed": claimed,
+                "pending": pending,
+                "other": total - claimed - pending,
+            }
+
+        conn = self._get_conn()
+        try:
+            with conn.cursor() as cur:
+                cur.execute("""
+                    SELECT
+                        COUNT(*) FILTER (WHERE user_type = 'agent' AND NOT is_sandbox) AS total,
+                        COUNT(*) FILTER (WHERE user_type = 'agent' AND NOT is_sandbox AND status = 'claimed') AS claimed,
+                        COUNT(*) FILTER (WHERE user_type = 'agent' AND NOT is_sandbox AND status = 'pending') AS pending
+                    FROM users
+                """)
+                row = cur.fetchone()
+                total = row["total"] or 0
+                claimed = row["claimed"] or 0
+                pending = row["pending"] or 0
+                return {
+                    "total": total,
+                    "claimed": claimed,
+                    "pending": pending,
+                    "other": total - claimed - pending,
+                }
+        finally:
+            self._put_conn(conn)
+
     def reset_sandbox_balance(self, user_id: str, amount: float) -> float:
         """Reset a sandbox agent's balance and stats.
 

test_stats.py

@@ -0,0 +1,41 @@
+"""Tests for /stats endpoint."""
+
+from fastapi.testclient import TestClient
+
+from api import app
+
+client = TestClient(app)
+
+
+def test_stats_endpoint_returns_counts():
+    """Test /stats returns agent counts, market count, and volume."""
+    response = client.get("/stats")
+    assert response.status_code == 200
+    data = response.json()
+
+    # Check structure
+    assert "agents" in data
+    assert "markets" in data
+    assert "volume" in data
+    assert "currency" in data
+
+    # Check agents breakdown
+    agents = data["agents"]
+    assert "total" in agents
+    assert "claimed" in agents
+    assert "pending" in agents
+    assert agents["total"] >= 0
+    assert agents["claimed"] >= 0
+    assert agents["pending"] >= 0
+    assert agents["total"] >= agents["claimed"] + agents["pending"]
+
+    # Check types
+    assert isinstance(data["markets"], int)
+    assert isinstance(data["volume"], (int, float))
+    assert data["currency"] == "ŧ"
+
+
+def test_stats_endpoint_no_auth_required():
+    """Test /stats is publicly accessible without authentication."""
+    response = client.get("/stats")
+    assert response.status_code == 200