From 8fc69b98e8a495b3b8ad7a50e3b04feccd4b2c0e Mon Sep 17 00:00:00 2001
From: frankosakwe <franklinosakwek@gmail.com>
Date: Mon, 23 Mar 2026 21:21:30 +0100
Subject: [PATCH] feat: Add TVL stats endpoint with static data

- Create GET /api/v1/stats/tvl endpoint
- Add static TVL data (14.5M USD) for frontend development
- Support ?format=short query parameter for display formatting
- Update README with comprehensive API documentation
- Follow NestJS module structure and best practices
---
 README.md                     | 39 +++++++++++++++++++++++++++++++++++
 src/app.module.ts             |  3 ++-
 src/stats/stats.controller.ts | 36 ++++++++++++++++++++++++++++++++
 src/stats/stats.module.ts     |  7 +++++++
 4 files changed, 84 insertions(+), 1 deletion(-)
 create mode 100644 src/stats/stats.controller.ts
 create mode 100644 src/stats/stats.module.ts

diff --git a/README.md b/README.md
index cfee2d1..b40119b 100644
--- a/README.md
+++ b/README.md
@@ -51,3 +51,42 @@ npm run start
 # 3. Run the CORS verification script (in a new terminal)
 node test-cors.js
 ```
+
+## 📊 API Endpoints
+
+### TVL Statistics
+
+Get Total Value Locked (TVL) metrics for the TradeFlow protocol.
+
+#### `GET /api/v1/stats/tvl`
+
+Returns the current TVL in USD with optional formatting.
+
+**Response Format:**
+```json
+{
+  "tvlUSD": 14500000.50,
+  "lastUpdated": "2026-03-19T00:00:00Z"
+}
+```
+
+**Query Parameters:**
+- `format` (optional): Set to `short` to return formatted TVL (e.g., "14.5M")
+
+**Examples:**
+
+```bash
+# Get full TVL data
+curl http://localhost:3000/api/v1/stats/tvl
+
+# Get formatted TVL for display
+curl http://localhost:3000/api/v1/stats/tvl?format=short
+```
+
+**Short Format Response:**
+```json
+{
+  "tvlUSD": "14.5M",
+  "lastUpdated": "2026-03-19T00:00:00Z"
+}
+```
diff --git a/src/app.module.ts b/src/app.module.ts
index 9a9e6aa..8e2f184 100644
--- a/src/app.module.ts
+++ b/src/app.module.ts
@@ -6,9 +6,10 @@ import { AppService } from './app.service';
 import { HealthModule } from './health/health.module';
 import { RiskModule } from './risk/risk.module';
 import { AuthModule } from './auth/auth.module';
+import { StatsModule } from './stats/stats.module';
 
 @Module({
-  imports: [HealthModule, RiskModule, AuthModule],
+  imports: [HealthModule, RiskModule, AuthModule, StatsModule],
   controllers: [AppController],
   providers: [
     AppService,
diff --git a/src/stats/stats.controller.ts b/src/stats/stats.controller.ts
new file mode 100644
index 0000000..d6b6490
--- /dev/null
+++ b/src/stats/stats.controller.ts
@@ -0,0 +1,36 @@
+import { Controller, Get, Query } from '@nestjs/common';
+
+@Controller('api/v1/stats')
+export class StatsController {
+  @Get('tvl')
+  async getTVL(@Query('format') format?: string) {
+    const staticTVL = 14500000.50;
+    const lastUpdated = '2026-03-19T00:00:00Z';
+
+    if (format === 'short') {
+      // Format as "14.5M" for short display
+      const formattedTVL = this.formatTVL(staticTVL);
+      return {
+        tvlUSD: formattedTVL,
+        lastUpdated,
+      };
+    }
+
+    return {
+      tvlUSD: staticTVL,
+      lastUpdated,
+    };
+  }
+
+  private formatTVL(amount: number): string {
+    if (amount >= 1000000000) {
+      return `${(amount / 1000000000).toFixed(1)}B`;
+    } else if (amount >= 1000000) {
+      return `${(amount / 1000000).toFixed(1)}M`;
+    } else if (amount >= 1000) {
+      return `${(amount / 1000).toFixed(1)}K`;
+    } else {
+      return amount.toString();
+    }
+  }
+}
diff --git a/src/stats/stats.module.ts b/src/stats/stats.module.ts
new file mode 100644
index 0000000..d9795b0
--- /dev/null
+++ b/src/stats/stats.module.ts
@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { StatsController } from './stats.controller';
+
+@Module({
+  controllers: [StatsController],
+})
+export class StatsModule {}