Get Investment Recommendations

POST /api/investment/:accountId/recommendations

Get Investment Recommendations

cURL

curl --request POST \
  --url https://api.example.com/api/investment/:accountId/recommendations \
  --header 'Content-Type: application/json' \
  --data '
{
  "profile": "<string>",
  "monthlyAmount": 123,
  "includeExplanation": true
}
'

200

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "type": "<string>",
        "symbol": "<string>",
        "name": "<string>",
        "percentage": 123,
        "amount": 123,
        "currentPrice": 123,
        "units": 123,
        "reason": "<string>",
        "risk": "<string>"
      }
    ],
    "totalMonthly": 123,
    "assetAllocation": {
      "stocks": 123,
      "bonds": 123,
      "crypto": 123,
      "cash": 123
    },
    "marketContext": "<string>",
    "disclaimer": "<string>"
  },
  "error": {
    "success": true,
    "message": "<string>"
  }
}

Generates personalized investment recommendations using AI based on the user’s risk profile and available monthly investment amount. Returns specific asset allocations with current market prices.

This endpoint uses AI and counts as 1 AI request toward your rate limit.

Authentication

Requires a valid Bearer token in the Authorization header.

Path Parameters

accountId · string · required

The unique identifier of the account to generate recommendations for

Request Body

profile · string

Investment risk profile to use for recommendations. If not provided, uses the profile from the user’s stored investment profile.

Options: conservative, balanced, dynamic

monthlyAmount · number

Monthly investment amount in euros (must be positive). If not provided, calculates based on stored savings capacity and investment percentage.

includeExplanation · boolean

Whether to include detailed explanations for each recommendation (currently not used in response)

Response

success · boolean

Indicates if the request was successful

data · object

AI-generated investment recommendations

Show data properties

recommendations · array

Array of specific investment recommendations

Show recommendation item properties

type · string

Type of investment asset

Values: ETF, BOND_FUND, CRYPTO, STOCK, SAVINGS

symbol · string

Trading symbol or ticker for the asset

name · string

Full name of the investment product

percentage · number

Percentage of monthly investment to allocate

amount · number

Calculated euro amount for this investment

currentPrice · number

Current market price (if available)

units · number

Number of units/shares this amount would purchase

reason · string

Explanation for why this asset is recommended

risk · string

Risk level of this specific investment

Values: low, medium, high

totalMonthly · number

Total monthly investment amount across all recommendations

assetAllocation · object

Overall portfolio allocation percentages

Show assetAllocation properties

stocks · number

Percentage allocated to stocks and equity ETFs

bonds · number

Percentage allocated to bonds and fixed income

crypto · number

Percentage allocated to cryptocurrencies

cash · number

Percentage kept in cash or savings accounts

marketContext · string

Current market conditions and how they affect recommendations

disclaimer · string

Important legal and risk disclaimers

Example Request

curl -X POST 'https://api.example.com/api/investment/acc_123/recommendations' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": "balanced",
    "monthlyAmount": 500
  }'

Example Response

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "type": "ETF",
        "symbol": "VWCE",
        "name": "Vanguard FTSE All-World UCITS ETF",
        "percentage": 60,
        "amount": 300,
        "currentPrice": 105.50,
        "units": 2.84,
        "reason": "Diversified global equity exposure with low costs, ideal for long-term balanced portfolios",
        "risk": "medium"
      },
      {
        "type": "BOND_FUND",
        "symbol": "AGGH",
        "name": "iShares Core Global Aggregate Bond UCITS ETF",
        "percentage": 30,
        "amount": 150,
        "currentPrice": 55.20,
        "units": 2.72,
        "reason": "Provides stability and reduces portfolio volatility with investment-grade bonds",
        "risk": "low"
      },
      {
        "type": "CRYPTO",
        "symbol": "BTC",
        "name": "Bitcoin",
        "percentage": 5,
        "amount": 25,
        "currentPrice": 45000,
        "units": 0.00056,
        "reason": "Small allocation for potential high growth, appropriate for balanced risk tolerance",
        "risk": "high"
      },
      {
        "type": "SAVINGS",
        "symbol": "CASH",
        "name": "High-Yield Savings Account",
        "percentage": 5,
        "amount": 25,
        "reason": "Emergency fund buffer and immediate liquidity needs",
        "risk": "low"
      }
    ],
    "totalMonthly": 500,
    "assetAllocation": {
      "stocks": 60,
      "bonds": 30,
      "crypto": 5,
      "cash": 5
    },
    "marketContext": "Current markets show moderate volatility. S&P 500 is up 1.2% this month. Bond yields remain stable. This balanced approach provides growth potential while managing downside risk.",
    "disclaimer": "This recommendation is not financial advice. Past performance does not guarantee future results. Consider consulting a certified financial advisor before making investment decisions."
  }
}

AI Provider Integration

This endpoint uses the configured AI provider to:

• Analyze current market conditions from real-time data
• Match investment products to the risk profile
• Calculate optimal allocation percentages
• Provide personalized reasoning for each recommendation
• Consider the user’s financial context and experience level

The AI pulls live market data for S&P 500, MSCI World, Nasdaq, Bitcoin, Ethereum, and currency exchange rates to inform recommendations.

Profile-Based Allocation

The AI adjusts recommendations based on the profile:

• Conservative: Higher bonds/cash (60-80%), lower stocks (20-40%), minimal/no crypto
• Balanced: Moderate mix (50-70% stocks, 30-50% bonds/cash, 0-10% crypto)
• Dynamic: Higher stocks (70-90%), lower bonds (10-30%), moderate crypto (0-15%)

Error Responses

error · object

Show Error response structure

success · boolean

Always false for errors

message · string

Human-readable error message

Common Errors

• 400 - Invalid input data
• 401 - Unauthorized (missing or invalid token)
• 403 - Forbidden (no access to this account)
• 503 - AI service unavailable