feat(accounts): enhance portfolio history endpoints with detailed summaries and descriptions; update query DTO for clarity on included fields

Author: ifaouibadi

src/account/controllers/accounts.controller.ts

@@ -161,7 +161,14 @@ export class AccountsController {
   }
 
   // Portfolio history endpoint - MUST come before :address route to avoid route conflict
-  @ApiOperation({ operationId: 'getPortfolioHistory' })
+  @ApiOperation({
+    operationId: 'getPortfolioHistory',
+    summary: 'Portfolio value history snapshots',
+    description:
+      'Returns portfolio value over time (AE balance, token values, total value). ' +
+      'Pass include=pnl or include=pnl-range to add aggregate total_pnl data. ' +
+      'Per-token PnL breakdown (tokens_pnl) is available via the dedicated :address/portfolio/tokens/history endpoint.',
+  })
   @ApiParam({ name: 'address', type: 'string', description: 'Account address' })
   @ApiOkResponse({ type: [PortfolioHistorySnapshotDto] })
   @CacheTTL(60 * 10) // 10 minutes
@@ -198,7 +205,13 @@ export class AccountsController {
     });
   }
 
-  @ApiOperation({ operationId: 'getTokensPnlHistory' })
+  @ApiOperation({
+    operationId: 'getTokensPnlHistory',
+    summary: 'Per-token PnL history snapshots',
+    description:
+      'Returns portfolio history snapshots that include the per-token PnL breakdown (tokens_pnl). ' +
+      'PnL data is always included; pass include=pnl-range to use range-based (daily window) PnL instead of cumulative.',
+  })
   @ApiParam({ name: 'address', type: 'string', description: 'Account address' })
   @ApiOkResponse({ type: [PortfolioHistorySnapshotDto] })
   @CacheTTL(60 * 10)
@@ -217,16 +230,14 @@ export class AccountsController {
     const requestedInterval = query.interval || 86400;
     const finalInterval = Math.max(requestedInterval, minimumInterval);
 
-    const includePnl =
-      includeFields.includes('pnl') || includeFields.includes('pnl-range');
     const useRangeBasedPnl = includeFields.includes('pnl-range');
 
     return await this.portfolioService.getPortfolioHistory(address, {
       startDate: start,
       endDate: end,
       interval: finalInterval,
       convertTo: query.convertTo || 'ae',
-      includePnl,
+      includePnl: true,
       useRangeBasedPnl,
       includeTokensPnl: true,
     });

src/account/dto/get-portfolio-history-query.dto.ts

@@ -62,7 +62,10 @@ export class GetPortfolioHistoryQueryDto {
     name: 'include',
     type: 'string',
     required: false,
-    description: 'Comma-separated list of fields to include (e.g., "pnl")',
+    description:
+      'Comma-separated list of fields to include. ' +
+      '"pnl" adds aggregate total_pnl, "pnl-range" uses daily-window PnL instead of cumulative. ' +
+      'Per-token breakdown (tokens_pnl) is only available via the /portfolio/tokens/history endpoint.',
     example: 'pnl',
   })
   @IsOptional()

src/account/dto/portfolio-history-response.dto.ts

@@ -73,7 +73,8 @@ export class PortfolioHistorySnapshotDto {
 
   @ApiProperty({
     description:
-      'PNL breakdown per token (included if requested), keyed by token sale_address',
+      'PNL breakdown per token, keyed by token sale_address. ' +
+      'Only returned by the dedicated /portfolio/tokens/history endpoint.',
     type: Object,
     required: false,
   })