Feat/trade reason

docs/examples/api-client.ts

@@ -466,6 +466,8 @@ async function example() {
       amount: '10',
       fromChain: BlockchainType.SVM,
       toChain: BlockchainType.SVM,
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     });
     console.log('SOL Trade Result:', solTrade);
 
@@ -478,6 +480,8 @@ async function example() {
       toChain: BlockchainType.EVM,
       fromSpecificChain: SpecificChain.ETH,
       toSpecificChain: SpecificChain.ETH,
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     });
     console.log('ETH Trade Result:', ethTrade);
 
@@ -488,6 +492,8 @@ async function example() {
       amount: '100',
       fromChain: BlockchainType.SVM,
       toChain: BlockchainType.SVM,
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     });
     console.log('Trade Quote:', quote);
 

docs/examples/execute-trade-example.ts

@@ -52,6 +52,8 @@ switch (tradeType) {
       toChain: BlockchainType.EVM, // Blockchain type for destination token
       fromSpecificChain: SpecificChain.ETH, // Specific chain for source token (eth, polygon, etc)
       toSpecificChain: SpecificChain.ETH, // Specific chain for destination token
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     };
     console.log('Executing Ethereum trade: Buy ETH with USDC on Ethereum');
     break;
@@ -67,6 +69,8 @@ switch (tradeType) {
       toChain: BlockchainType.EVM, // Blockchain type for destination token (evm)
       fromSpecificChain: SpecificChain.SVM, // Specific chain for source token (Solana)
       toSpecificChain: SpecificChain.ETH, // Specific chain for destination token (Ethereum)
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     };
     console.log('Executing cross-chain trade: Buy ETH with Solana USDC');
     break;
@@ -83,6 +87,8 @@ switch (tradeType) {
       toChain: BlockchainType.SVM, // Blockchain type for destination token
       fromSpecificChain: SpecificChain.SVM, // Specific chain for source token
       toSpecificChain: SpecificChain.SVM, // Specific chain for destination token
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     };
     console.log('Executing Solana trade: Buy SOL with USDC on Solana');
     break;

docs/examples/multi-chain-examples.ts

@@ -134,6 +134,8 @@ async function executeMultiChainTrades(client: TradingSimulatorClient): Promise<
       slippageTolerance: '0.5',
       fromChain: BlockchainType.SVM,
       toChain: BlockchainType.SVM,
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     };
 
     const solTrade: TradeResponse = await client.executeTrade(solanaTradeDetails);
@@ -154,6 +156,8 @@ async function executeMultiChainTrades(client: TradingSimulatorClient): Promise<
       toChain: BlockchainType.EVM,
       fromSpecificChain: SpecificChain.ETH,
       toSpecificChain: SpecificChain.ETH,
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     };
 
     const ethTrade: TradeResponse = await client.executeTrade(ethereumTradeDetails);
@@ -181,6 +185,8 @@ async function executeCrossChainTrades(client: TradingSimulatorClient): Promise<
       toChain: BlockchainType.EVM,
       fromSpecificChain: SpecificChain.SVM,
       toSpecificChain: SpecificChain.ETH,
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     };
 
     const crossTrade1: TradeResponse = await client.executeTrade(crossChainTradeDetails1);
@@ -204,6 +210,8 @@ async function executeCrossChainTrades(client: TradingSimulatorClient): Promise<
       toChain: BlockchainType.SVM,
       fromSpecificChain: SpecificChain.ETH,
       toSpecificChain: SpecificChain.SVM,
+      reason:
+        "Strong upward momentum in the market combined with positive news on this token's ecosystem growth",
     };
 
     const crossTrade2: TradeResponse = await client.executeTrade(crossChainTradeDetails2);

docs/openapi.json

@@ -743,6 +743,10 @@
                             "type": "string",
                             "description": "Error message if the trade failed"
                           },
+                          "reason": {
+                            "type": "string",
+                            "description": "Reason provided for executing the trade"
+                          },
                           "timestamp": {
                             "type": "string",
                             "format": "date-time",
@@ -2754,7 +2758,7 @@
             "application/json": {
               "schema": {
                 "type": "object",
-                "required": ["fromToken", "toToken", "amount"],
+                "required": ["fromToken", "toToken", "amount", "reason"],
                 "properties": {
                   "fromToken": {
                     "type": "string",
@@ -2771,6 +2775,11 @@
                     "description": "Amount of fromToken to trade",
                     "example": "1.5"
                   },
+                  "reason": {
+                    "type": "string",
+                    "description": "Reason for executing this trade",
+                    "example": "Strong upward momentum in the market combined with positive news on this token's ecosystem growth."
+                  },
                   "slippageTolerance": {
                     "type": "string",
                     "description": "Optional slippage tolerance in percentage",
@@ -2852,6 +2861,14 @@
                           "type": "boolean",
                           "description": "Whether the trade was successfully completed"
                         },
+                        "error": {
+                          "type": "string",
+                          "description": "Error message if the trade failed"
+                        },
+                        "reason": {
+                          "type": "string",
+                          "description": "Reason provided for executing the trade"
+                        },
                         "timestamp": {
                           "type": "string",
                           "format": "date-time",

e2e/tests/base-trades.test.ts

@@ -32,6 +32,8 @@ console.log(`- Imported config from ../../src/config has initial balances:`, {
 });
 console.log('===========================================================\n');
 
+const reason = 'base-trades end to end tests';
+
 describe('Base Chain Trading', () => {
   let adminApiKey: string;
 
@@ -169,6 +171,7 @@ describe('Base Chain Trading', () => {
         toChain: BlockchainType.EVM,
         fromSpecificChain: SpecificChain.BASE,
         toSpecificChain: SpecificChain.BASE,
+        reason,
       })) as TradeResponse;
 
       console.log(`Trade response for ${token.address}: ${JSON.stringify(tradeResponse.success)}`);
@@ -326,6 +329,7 @@ describe('Base Chain Trading', () => {
         toChain: BlockchainType.EVM,
         fromSpecificChain: SpecificChain.BASE,
         toSpecificChain: SpecificChain.ETH, // Different chain from fromSpecificChain
+        reason,
       });
 
       // If we get here, the trade might have succeeded, which is unexpected if cross-chain trading is disabled
@@ -494,6 +498,7 @@ describe('Base Chain Trading', () => {
         toChain: BlockchainType.EVM,
         fromSpecificChain: SpecificChain.BASE,
         toSpecificChain: SpecificChain.BASE,
+        reason,
       });
 
       expect(tradeResponse.success).toBe(false); // The test should fail here if excessive trading is allowed
@@ -528,6 +533,7 @@ describe('Base Chain Trading', () => {
       toChain: BlockchainType.EVM,
       fromSpecificChain: SpecificChain.BASE,
       toSpecificChain: SpecificChain.BASE,
+      reason,
     })) as TradeResponse;
 
     // This trade should succeed

e2e/tests/chainSpecific.test.ts

@@ -13,6 +13,8 @@ import { getPool } from '../utils/db-manager';
 import { BalancesResponse } from '../utils/api-types';
 import { config } from '../../src/config';
 
+const reason = 'chainSpecific end to end tests';
+
 describe('Specific Chains', () => {
   let adminApiKey: string;
 
@@ -140,6 +142,7 @@ describe('Specific Chains', () => {
       fromToken: ethToken,
       toToken: usdcToken,
       amount: tradeAmount,
+      reason,
     });
     expect(tradeResponse.success).toBe(true);
 

e2e/tests/deactivate.test.ts

@@ -125,6 +125,7 @@ describe('Team Deactivation API', () => {
         amount: '100',
         fromChain: BlockchainType.SVM,
         toChain: BlockchainType.SVM,
+        reason,
       });
       // Should not reach here - trade should be blocked
       expect(false).toBe(true); // Force test to fail if we get here
@@ -251,6 +252,7 @@ describe('Team Deactivation API', () => {
       amount: '100',
       fromChain: BlockchainType.SVM,
       toChain: BlockchainType.SVM,
+      reason: 'inactive teams are filtered from leaderboard',
     });
 
     // Have the other teams make trades too to populate leaderboard
@@ -260,6 +262,7 @@ describe('Team Deactivation API', () => {
       amount: '50',
       fromChain: BlockchainType.SVM,
       toChain: BlockchainType.SVM,
+      reason: 'inactive teams are filtered from leaderboard',
     });
 
     await teamClient2.executeTrade({
@@ -268,6 +271,7 @@ describe('Team Deactivation API', () => {
       amount: '75',
       fromChain: BlockchainType.SVM,
       toChain: BlockchainType.SVM,
+      reason: 'inactive teams are filtered from leaderboard',
     });
 
     // Wait a moment for portfolio values to update

e2e/tests/multi-team-competition.test.ts

@@ -19,6 +19,7 @@ import {
   ErrorResponse,
   LeaderboardResponse,
   SnapshotResponse,
+  SpecificChain,
   TeamProfileResponse,
   TradeResponse,
 } from '../utils/api-types';
@@ -59,6 +60,8 @@ describe('Multi-Team Competition', () => {
   let adminClient: ApiClient;
   let competitionId: string;
 
+  const reason = 'multi-team-competition end-to-end test';
+
   // Clean up test state before each test
   beforeEach(async () => {
     await cleanupTestState();
@@ -294,14 +297,15 @@ describe('Multi-Team Competition', () => {
       console.log(`Team ${i + 1} trading ${tradeAmount} USDC for token ${tokenToTrade}`);
 
       // Execute trade using the client - each team buys a different BASE token with 100 USDC
-      const tradeResponse = (await team.client.request('post', '/api/trade/execute', {
+      const tradeResponse = (await team.client.executeTrade({
         fromToken: BASE_USDC_ADDRESS,
         toToken: tokenToTrade,
         amount: tradeAmount.toString(),
         fromChain: BlockchainType.EVM,
         toChain: BlockchainType.EVM,
-        fromSpecificChain: BASE_CHAIN,
-        toSpecificChain: BASE_CHAIN,
+        fromSpecificChain: SpecificChain.BASE,
+        toSpecificChain: SpecificChain.BASE,
+        reason,
       })) as TradeResponse;
 
       // Verify trade was successful
@@ -447,14 +451,15 @@ describe('Multi-Team Competition', () => {
       );
 
       // Execute trade - each team buys a different BASE token with USDC
-      const tradeResponse = (await team.client.request('post', '/api/trade/execute', {
+      const tradeResponse = (await team.client.executeTrade({
         fromToken: BASE_USDC_ADDRESS,
         toToken: tokenToTrade,
         amount: tradeAmount.toString(),
         fromChain: BlockchainType.EVM,
         toChain: BlockchainType.EVM,
-        fromSpecificChain: BASE_CHAIN,
-        toSpecificChain: BASE_CHAIN,
+        fromSpecificChain: SpecificChain.BASE,
+        toSpecificChain: SpecificChain.BASE,
+        reason,
       })) as TradeResponse;
 
       // Verify trade was successful

e2e/tests/portfolio-snapshots.test.ts

@@ -16,6 +16,8 @@ import { BlockchainType } from '../../src/types';
 import { PriceTracker } from '../../src/services/price-tracker.service';
 import { BalancesResponse, SnapshotResponse, TokenPortfolioItem } from '../utils/api-types';
 
+const reason = 'portfolio-snapshots end-to-end tests';
+
 describe('Portfolio Snapshots', () => {
   let adminApiKey: string;
 
@@ -174,6 +176,7 @@ describe('Portfolio Snapshots', () => {
       amount: '100',
       fromChain: BlockchainType.SVM,
       toChain: BlockchainType.SVM,
+      reason,
     });
 
     // Wait for trade to process