feat(apis): GET /stats — protocol-wide statistics endpoint

[IbrahimIjai]

Context

Frontends and aggregators (DeFiLlama, etc.) need a single endpoint exposing top-level protocol metrics without calling multiple reader contract functions themselves.

Endpoint

GET /stats

Response shape:

{
  "tvl_usd": "12500000.00",
  "volume_24h_usd": "3200000.00",
  "open_interest_usd": { "long": "8100000.00", "short": "7900000.00" },
  "fees_24h_usd": "9600.00",
  "active_markets": 3,
  "open_positions": 142,
  "updated_at": 1748640000
}

Implementation notes

• TVL: sum of reader::get_market_pool_value_info across all markets
• OI: sum of reader::get_open_interest across all markets
• 24h volume/fees: accumulated from order execution events via Stellar Horizon or local counter
• Cache the full object for 60 seconds (no per-request RPC calls)
• Return 503 if price cache is stale (stats would be meaningless without prices)

Acceptance criteria

• All fields populated from on-chain reader and local accumulators
• Response cached 60 seconds
• 503 when price cache stale
• Unit test with mocked reader and price cache
• Response validated against JSON schema in test