### Get Portfolio Rebalancing Guide (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Provides actionable rebalancing suggestions to help a portfolio reach its target asset allocation. It details necessary adjustments, including buy/sell actions and estimated trading costs.

```bash
# Get rebalancing guide
curl -X GET "http://localhost:8080/api/v1/portfolios/1/analysis/rebalancing" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get New Listings

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves recently listed stocks on KOSPI and KOSDAQ markets.

```APIDOC
## GET /api/v1/stocks/new-listings

### Description
Retrieves a list of recently listed stocks on KOSPI/KOSDAQ markets.

### Method
GET

### Endpoint
`/api/v1/stocks/new-listings`

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1/stocks/new-listings"
```

### Response
#### Success Response (200)
- **Array of objects** - A list of newly listed stocks with details.
  - **ticker** (string) - The stock ticker symbol.
  - **name** (string) - The name of the company.
  - **marketType** (string) - The market type (e.g., KOSDAQ, KOSPI).
  - **listingDate** (string) - The date the stock was listed.
  - **currentPrice** (number) - The current trading price.
  - **changeRate** (number) - The percentage change in price.

#### Response Example
```json
[
  {
    "ticker": "450220",
    "name": "AI Semiconductor Corp",
    "marketType": "KOSDAQ",
    "listingDate": "2026-03-10",
    "currentPrice": 25000,
    "changeRate": 15.5
  }
]
```
```

--------------------------------

### Get Latest AI Advice

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves the most recent AI-generated rebalancing recommendations for a portfolio, including suggested actions.

```APIDOC
## Get Latest AI Advice

### Description
Retrieves the most recent AI-generated rebalancing recommendations for a portfolio, including suggested actions.

### Method
GET

### Endpoint
/api/v1/portfolios/{portfolioId}/advice/latest

### Parameters
#### Path Parameters
- **portfolioId** (integer) - Required - The unique identifier of the portfolio for which to get advice.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1/portfolios/1/advice/latest" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Response
#### Success Response (200)
- **data** (object) - The latest AI advice for the portfolio.
  - **generatedAt** (string) - Timestamp when the advice was generated.
  - **marketCondition** (string) - Current market condition (e.g., "BULLISH").
  - **advice** (string) - General advice based on market conditions and portfolio status.
  - **suggestedActions** (array) - Specific actions recommended for rebalancing.
    - **symbol** (string) - Stock symbol for the action.
    - **action** (string) - Type of action (e.g., "REDUCE", "BUY").
    - **currentWeight** (number) - Current weight of the asset in the portfolio.
    - **targetWeight** (number) - Target weight for the asset.
    - **suggestedQuantity** (integer) - Suggested change in quantity.
- **timestamp** (string) - Timestamp of the API response.

#### Response Example
```json
{
  "data": {
    "generatedAt": "2026-03-12T09:00:00",
    "marketCondition": "BULLISH",
    "advice": "Current portfolio shows strong momentum. Consider taking partial profits on Samsung Electronics...",
    "suggestedActions": [
      {
        "symbol": "005930",
        "action": "REDUCE",
        "currentWeight": 45.2,
        "targetWeight": 40.0,
        "suggestedQuantity": -20
      }
    ]
  },
  "timestamp": "2026-03-12T17:00:00.000000"
}
```
```

--------------------------------

### GET /api/v1/portfolios/{id}/analysis/rebalancing

Source: https://context7.com/oxix97/stockwellness/llms.txt

Provides actionable rebalancing suggestions to reach target weights for portfolio holdings.

```APIDOC
## GET /api/v1/portfolios/{id}/analysis/rebalancing

### Description
Calculates necessary buy/sell actions to align current portfolio weights with target allocations.

### Method
GET

### Endpoint
/api/v1/portfolios/{id}/analysis/rebalancing

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the portfolio.

### Response
#### Success Response (200)
- **needsRebalancing** (boolean) - Whether rebalancing is required.
- **totalDeviation** (number) - Total percentage deviation from targets.
- **suggestions** (array) - List of specific buy/sell recommendations.

### Response Example
{
  "needsRebalancing": true,
  "totalDeviation": 8.5,
  "suggestions": [{"symbol": "005930", "action": "BUY", "suggestedAmount": 448500}]
}
```

--------------------------------

### Get Portfolio Analysis Summary (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves a comprehensive summary of a portfolio's analysis, combining valuation, diversification, and rebalancing insights into a single response.

```bash
# Get full analysis summary
curl -X GET "http://localhost:8080/api/v1/portfolios/1/analysis/summary" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get Portfolio Detail

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves detailed information about a specific portfolio, including its constituent items and their performance.

```APIDOC
## Get Portfolio Detail

### Description
Retrieves detailed information about a specific portfolio, including its constituent items and their performance.

### Method
GET

### Endpoint
/api/v1/portfolios/{portfolioId}

### Parameters
#### Path Parameters
- **portfolioId** (integer) - Required - The unique identifier of the portfolio.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1/portfolios/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Response
#### Success Response (200)
- **data** (object) - The portfolio details.
  - **id** (integer) - Unique identifier for the portfolio.
  - **name** (string) - Name of the portfolio.
  - **description** (string) - Description of the portfolio.
  - **items** (array) - Array of portfolio items.
    - **symbol** (string) - Stock symbol.
    - **name** (string) - Name of the stock.
    - **quantity** (integer) - Number of shares held.
    - **purchasePrice** (number) - Purchase price per share.
    - **currentPrice** (number) - Current market price per share.
    - **currentValue** (number) - Current total value of the holding.
    - **returnRate** (number) - Return rate for the holding.
    - **weight** (number) - Current weight of the holding in the portfolio.
    - **targetWeight** (number) - Target weight for the holding.
  - **totalValue** (number) - Total current value of the portfolio.
  - **totalCost** (number) - Total cost basis of the portfolio.
  - **totalReturn** (number) - Total return percentage of the portfolio.
  - **createdAt** (string) - Timestamp when the portfolio was created.
- **timestamp** (string) - Timestamp of the API response.

#### Response Example
```json
{
  "data": {
    "id": 1,
    "name": "Tech Growth Portfolio",
    "description": "Focus on technology sector growth stocks",
    "items": [
      {
        "symbol": "005930",
        "name": "Samsung Electronics",
        "quantity": 100,
        "purchasePrice": 70000,
        "currentPrice": 73500,
        "currentValue": 7350000,
        "returnRate": 5.0,
        "weight": 37.7,
        "targetWeight": 40.0
      }
    ],
    "totalValue": 19500000,
    "totalCost": 18500000,
    "totalReturn": 5.4,
    "createdAt": "2026-01-15T10:00:00"
  },
  "timestamp": "2026-03-12T17:00:00.000000"
}
```
```

--------------------------------

### Get Latest AI Advice (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves the most recent AI-generated rebalancing recommendations for a portfolio. This endpoint requires the portfolio ID and an Authorization header. The response details market conditions, advice, and suggested actions.

```bash
# Get latest AI rebalancing advice
curl -X GET "http://localhost:8080/api/v1/portfolios/1/advice/latest" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response
{
  "data": {
    "generatedAt": "2026-03-12T09:00:00",
    "marketCondition": "BULLISH",
    "advice": "Current portfolio shows strong momentum. Consider taking partial profits on Samsung Electronics...",
    "suggestedActions": [
      {
        "symbol": "005930",
        "action": "REDUCE",
        "currentWeight": 45.2,
        "targetWeight": 40.0,
        "suggestedQuantity": -20
      }
    ]
  },
  "timestamp": "2026-03-12T17:00:00.000000"
}
```

--------------------------------

### Get New Listings

Source: https://context7.com/oxix97/stockwellness/llms.txt

Fetches a list of recently listed stocks on the KOSPI and KOSDAQ markets. Returns detailed information including ticker, name, and current market data.

```bash
curl -X GET "http://localhost:8080/api/v1/stocks/new-listings"
```

--------------------------------

### Get Portfolio Detail (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves detailed information about a specific portfolio identified by its ID. Requires an Authorization header. The response contains comprehensive details of the portfolio, including its constituent items.

```bash
# Get portfolio by ID
curl -X GET "http://localhost:8080/api/v1/portfolios/1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response
{
  "data": {
    "id": 1,
    "name": "Tech Growth Portfolio",
    "description": "Focus on technology sector growth stocks",
    "items": [
      {
        "symbol": "005930",
        "name": "Samsung Electronics",
        "quantity": 100,
        "purchasePrice": 70000,
        "currentPrice": 73500,
        "currentValue": 7350000,
        "returnRate": 5.0,
        "weight": 37.7,
        "targetWeight": 40.0
      }
    ],
    "totalValue": 19500000,
    "totalCost": 18500000,
    "totalReturn": 5.4,
    "createdAt": "2026-01-15T10:00:00"
  },
  "timestamp": "2026-03-12T17:00:00.000000"
}
```

--------------------------------

### GET /api/v1/portfolios/{id}/analysis/diversification

Source: https://context7.com/oxix97/stockwellness/llms.txt

Analyzes portfolio diversification across sectors, asset types, and countries.

```APIDOC
## GET /api/v1/portfolios/{id}/analysis/diversification

### Description
Analyzes portfolio diversification across sectors, asset types, and countries to assess concentration risk.

### Method
GET

### Endpoint
/api/v1/portfolios/{id}/analysis/diversification

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the portfolio.

### Response
#### Success Response (200)
- **sectorAllocation** (array) - List of sector weights and values.
- **assetTypeAllocation** (array) - List of asset type weights and values.
- **countryAllocation** (array) - List of country weights and values.
- **concentrationRisk** (object) - Metrics regarding top holdings and Herfindahl index.

### Response Example
{
  "sectorAllocation": [{"sector": "IT", "weight": 65.5, "value": 12772500}],
  "assetTypeAllocation": [{"assetType": "STOCK", "weight": 85.0, "value": 16575000}],
  "countryAllocation": [{"country": "KR", "weight": 100.0, "value": 19500000}],
  "concentrationRisk": {"topHolding": {"symbol": "005930", "weight": 37.7}, "top3Holdings": 82.5, "herfindahlIndex": 0.28}
}
```

--------------------------------

### GET /api/v1/stocks/search

Source: https://context7.com/oxix97/stockwellness/llms.txt

Unified search across all listed stocks with filtering options.

```APIDOC
## GET /api/v1/stocks/search

### Description
Searches for stocks by keyword with pagination and market filtering.

### Method
GET

### Endpoint
/api/v1/stocks/search

### Parameters
#### Query Parameters
- **keyword** (string) - Required - Search term.
- **marketType** (string) - Optional - Market filter (e.g., KOSPI).
- **page** (integer) - Optional - Page number.
- **size** (integer) - Optional - Page size.

### Response
#### Success Response (200)
- **content** (array) - List of matching stocks.
- **pageable** (object) - Pagination details.

### Response Example
{
  "content": [{"ticker": "005930", "name": "Samsung Electronics", "currentPrice": 73500}],
  "hasNext": true
}
```

--------------------------------

### Get Return Rates

Source: https://context7.com/oxix97/stockwellness/llms.txt

Calculates and retrieves period-based investment return rates for a stock, including benchmark comparison and risk metrics.

```APIDOC
## GET /api/v1/stocks/{ticker}/returns

### Description
Calculates and returns period-based investment return rates for a given stock ticker, comparing it against a benchmark and providing risk metrics.

### Method
GET

### Endpoint
`/api/v1/stocks/{ticker}/returns`

#### Path Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., `005930`).

#### Query Parameters
- **period** (string) - Required - The investment period for return calculation (e.g., `1D`, `1M`, `6M`, `1Y`, `3Y`, `5Y`).

### Request Example
```bash
# Get return rates for the last 1 year
curl -X GET "http://localhost:8080/api/v1/stocks/005930/returns?period=1Y"
```

### Response
#### Success Response (200)
- **object** - Return rate calculations.
  - **ticker** (string) - The stock ticker symbol.
  - **period** (string) - The calculated period.
  - **stockReturn** (number) - The total return percentage for the stock over the period.
  - **benchmarkReturn** (number) - The total return percentage for the benchmark over the period.
  - **outperformance** (number) - The difference between stock return and benchmark return.
  - **volatility** (number) - The annualized volatility of the stock's returns.
  - **maxDrawdown** (number) - The maximum peak-to-trough decline in the stock's value during the period.

#### Response Example
```json
{
  "ticker": "005930",
  "period": "1Y",
  "stockReturn": 15.2,
  "benchmarkReturn": 8.5,
  "outperformance": 6.7,
  "volatility": 22.5,
  "maxDrawdown": -18.3
}
```
```

--------------------------------

### Get Portfolio Diversification Analysis (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves an analysis of portfolio diversification across sectors, asset types, and countries. This endpoint requires authentication and returns detailed allocation and concentration risk metrics.

```bash
# Get diversification analysis
curl -X GET "http://localhost:8080/api/v1/portfolios/1/analysis/diversification" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get Return Rates

Source: https://context7.com/oxix97/stockwellness/llms.txt

Calculates performance metrics for a stock over a specific period, including return rates, volatility, and maximum drawdown compared to a benchmark.

```bash
curl -X GET "http://localhost:8080/api/v1/stocks/005930/returns?period=1Y"
```

--------------------------------

### Get Portfolio Correlation Matrix (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves the correlation coefficients between different holdings within a portfolio. This helps in understanding how assets move in relation to each other.

```bash
# Get correlation matrix
curl -X GET "http://localhost:8080/api/v1/portfolios/1/analysis/correlation" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get Portfolio Valuation (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves real-time portfolio valuation, including profit and loss calculations. This endpoint requires the portfolio ID and an Authorization header. It's part of the advanced analytics section for portfolio performance.

```bash
# Get portfolio valuation
curl -X GET "http://localhost:8080/api/v1/portfolios/1/analysis/valuation" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get Price History

Source: https://context7.com/oxix97/stockwellness/llms.txt

Provides historical price data for a specific stock over a defined period and frequency. Optionally includes benchmark data for comparative analysis.

```bash
curl -X GET "http://localhost:8080/api/v1/stocks/005930/prices/history?period=1Y&frequency=DAILY&includeBenchmark=true"
```

--------------------------------

### Get Popular Searches

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves a list of the top 10 trending search keywords across the platform. This is a public endpoint and does not require authentication.

```bash
curl -X GET "http://localhost:8080/api/v1/stocks/popular"
```

--------------------------------

### Get Sector Detail (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Fetches detailed information for a specific sector, including its overall performance and constituent stocks. The response includes top gainers and losers within the sector, along with market cap and average P/E ratio.

```bash
# Get sector detail
curl -X GET "http://localhost:8080/api/v1/sectors/G45?date=2026-03-12"
```

--------------------------------

### Fetch All Stock Prices (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Initiates a batch job to collect historical price data for all stocks within a specified date range. The `publishEvent` flag can be set to true to trigger downstream event processing. Requires a JSON payload with start and end dates.

```bash
# Fetch prices for all stocks
curl -X POST "http://localhost:8080/api/v1/admin/batch/fetch-prices?publishEvent=true" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "20260101",
    "endDate": "20260312"
  }'
```

--------------------------------

### Get Stock Detail

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves comprehensive fundamental and market data for a specific stock identified by its ticker symbol. Includes metrics like P/E ratio, market cap, and dividend yield.

```bash
curl -X GET "http://localhost:8080/api/v1/stocks/005930"
```

--------------------------------

### Get System Health (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves the current health status of all critical infrastructure components of the system. The response indicates whether the database, Redis, and Kafka services are operational ('UP' or 'DOWN').

```bash
# Get system health
curl -X GET "http://localhost:8080/api/v1/admin/health"
```

--------------------------------

### Get Top Sectors by Supply (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves sectors ranked by net buying or selling pressure from institutional and foreign investors. This endpoint helps in understanding market supply dynamics for different sectors on a given date and market type.

```bash
# Get top sectors by supply (institutional/foreign buying)
curl -X GET "http://localhost:8080/api/v1/sectors/ranking/supply?date=2026-03-12&marketType=KOSPI&limit=10"
```

--------------------------------

### Get Portfolio Health Diagnosis (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Performs an AI-powered health analysis of a portfolio, evaluating diversification and risk factors. Requires the portfolio ID and an Authorization header. The response includes scores and specific issues or recommendations.

```bash
# Get portfolio health diagnosis
curl -X GET "http://localhost:8080/api/v1/portfolios/1/health" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response
{
  "data": {
    "overallScore": 78,
    "diversificationScore": 65,
    "riskScore": 82,
    "performanceScore": 85,
    "issues": [
      {
        "type": "CONCENTRATION_RISK",
        "severity": "MEDIUM",
        "description": "Samsung Electronics exceeds 40% of portfolio"
      }
    ],
    "recommendations": [
      "Consider reducing Samsung Electronics position",
      "Add defensive sector stocks for balance"
    ]
  },
  "timestamp": "2026-03-12T17:00:00.000000"
}
```

--------------------------------

### Get Watchlist Items (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves all stocks within a specified watchlist group, including their current market data. Authentication is required, and the response provides details like ISIN, ticker, name, current price, and change rate.

```bash
# Get watchlist items
curl -X GET "http://localhost:8080/api/v1/watchlist/groups/1/items" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response
{
  "groupId": 1,
  "groupName": "Tech Favorites",
  "items": [
    {
      "isinCode": "KR7005930003",
      "ticker": "005930",
      "name": "Samsung Electronics",
      "currentPrice": 73500,
      "changeRate": 1.24,
      "addedAt": "2026-01-15T10:00:00"
    }
  ]
}
```

--------------------------------

### Initialize Swagger UI for API Documentation

Source: https://github.com/oxix97/stockwellness/blob/develop/stockwellness-api/src/main/resources/static/docs/index.html

This script initializes the Swagger UI bundle by pointing to the OpenAPI specification file. It includes custom sorting logic to organize API tags in a specific order (Auth, Member, Portfolio, System).

```javascript
window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "/docs/openapi3.yaml",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout",
    operationsSorter: (a, b) => {
      var order = { 'Auth': 1, 'Member': 2, 'Portfolio': 3, 'System': 99 };
      return (order[a.get("tag")] || 99) - (order[b.get("tag")] || 99);
    }
  });
  window.ui = ui;
};
```

--------------------------------

### Run Portfolio Backtest Simulation (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Performs historical backtesting for a portfolio using either Dollar-Cost Averaging (DCA) or lump-sum investment strategies. It requires specifying the strategy, investment amount, and a benchmark ticker.

```bash
# Run backtest simulation
curl -X POST "http://localhost:8080/api/v1/portfolios/1/analysis/backtest" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "DCA",
    "amount": 1000000,
    "benchmarkTicker": "KOSPI"
  }'
```

--------------------------------

### Get Stock Detail

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves comprehensive information for a specific stock using its ticker.

```APIDOC
## GET /api/v1/stocks/{ticker}

### Description
Retrieves comprehensive stock information including fundamentals for a given stock ticker.

### Method
GET

### Endpoint
`/api/v1/stocks/{ticker}`

#### Path Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., `005930`).

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1/stocks/005930"
```

### Response
#### Success Response (200)
- **object** - Detailed information about the stock.
  - **ticker** (string) - The stock ticker symbol.
  - **name** (string) - The name of the company.
  - **englishName** (string) - The English name of the company.
  - **marketType** (string) - The market type (e.g., KOSPI, KOSDAQ).
  - **sector** (string) - The industry sector.
  - **industry** (string) - The specific industry.
  - **currentPrice** (number) - The current trading price.
  - **previousClose** (number) - The closing price of the previous trading day.
  - **change** (number) - The absolute price change from the previous close.
  - **changeRate** (number) - The percentage change in price.
  - **volume** (number) - The trading volume for the current day.
  - **marketCap** (number) - The total market capitalization.
  - **per** (number) - Price-to-Earnings ratio.
  - **pbr** (number) - Price-to-Book ratio.
  - **eps** (number) - Earnings Per Share.
  - **dividend** (number) - Annual dividend per share.
  - **dividendYield** (number) - Dividend yield percentage.
  - **high52Week** (number) - The highest price in the last 52 weeks.
  - **low52Week** (number) - The lowest price in the last 52 weeks.

#### Response Example
```json
{
  "ticker": "005930",
  "name": "Samsung Electronics",
  "englishName": "Samsung Electronics Co Ltd",
  "marketType": "KOSPI",
  "sector": "IT",
  "industry": "Semiconductors",
  "currentPrice": 73500,
  "previousClose": 72600,
  "change": 900,
  "changeRate": 1.24,
  "volume": 12500000,
  "marketCap": 438000000000000,
  "per": 12.5,
  "pbr": 1.3,
  "eps": 5880,
  "dividend": 1444,
  "dividendYield": 1.96,
  "high52Week": 80000,
  "low52Week": 55000
}
```
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/oxix97/stockwellness/blob/develop/conductor/workflow.md

Commands used to execute project-wide pre-commit tasks such as formatting, linting, type checking, and unit testing. These commands ensure code quality before changes are committed to the repository.

```bash
# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests)
# e.g., for a Node.js project: npm run check
# e.g., for a Go project: make check (if a Makefile exists)
```

--------------------------------

### Create Investment Portfolio

Source: https://context7.com/oxix97/stockwellness/llms.txt

Creates a new portfolio for the user, including asset details such as symbol, quantity, purchase price, and target weight. Returns a 201 Created status upon success.

```bash
curl -X POST "http://localhost:8080/api/v1/portfolios" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Growth Portfolio",
    "description": "Focus on technology sector growth stocks",
    "items": [
      {"symbol": "005930", "quantity": 100, "purchasePrice": 70000, "currency": "KRW", "assetType": "STOCK", "targetWeight": 40.0},
      {"symbol": "000660", "quantity": 50, "purchasePrice": 120000, "currency": "KRW", "assetType": "STOCK", "targetWeight": 30.0},
      {"symbol": "035420", "quantity": 30, "purchasePrice": 180000, "currency": "KRW", "assetType": "STOCK", "targetWeight": 30.0}
    ]
  }'
```

--------------------------------

### Get Popular Searches

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves the top 10 trending stock search keywords across all users.

```APIDOC
## GET /api/v1/stocks/popular

### Description
Retrieves the top 10 trending stock search keywords.

### Method
GET

### Endpoint
`/api/v1/stocks/popular`

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1/stocks/popular"
```

### Response
#### Success Response (200)
- **Array of strings** - A list of popular search keywords.

#### Response Example
```json
["samsung electronics", "sk hynix", "naver", "kakao", "lg energy solution", "samsung sdi", "celltrion", "hyundai motor", "posco", "kb financial"]
```
```

--------------------------------

### List My Portfolios

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves all portfolios owned by the authenticated user. This endpoint provides a summary of each portfolio, including its name, total value, and return.

```APIDOC
## List My Portfolios

### Description
Retrieves all portfolios owned by the authenticated user. This endpoint provides a summary of each portfolio, including its name, total value, and return.

### Method
GET

### Endpoint
/api/v1/portfolios

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1/portfolios" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Response
#### Success Response (200)
- **data** (array) - An array of portfolio objects.
  - **id** (integer) - Unique identifier for the portfolio.
  - **name** (string) - Name of the portfolio.
  - **description** (string) - Description of the portfolio.
  - **totalValue** (number) - Total current value of the portfolio.
  - **totalReturn** (number) - Total return percentage of the portfolio.
  - **itemCount** (integer) - Number of items in the portfolio.
  - **createdAt** (string) - Timestamp when the portfolio was created.
- **timestamp** (string) - Timestamp of the API response.

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "name": "Tech Growth Portfolio",
      "description": "Focus on technology sector growth stocks",
      "totalValue": 19500000,
      "totalReturn": 5.2,
      "itemCount": 3,
      "createdAt": "2026-01-15T10:00:00"
    },
    {
      "id": 2,
      "name": "Dividend Income Portfolio",
      "description": "High dividend yield stocks",
      "totalValue": 25000000,
      "totalReturn": 3.8,
      "itemCount": 5,
      "createdAt": "2026-02-01T14:30:00"
    }
  ],
  "timestamp": "2026-03-12T17:00:00.000000"
}
```
```

--------------------------------

### Get Price History

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves historical daily or intraday price data for a stock, optionally including benchmark data.

```APIDOC
## GET /api/v1/stocks/{ticker}/prices/history

### Description
Retrieves historical price data for a stock, suitable for chart rendering. Allows specifying period, frequency, and inclusion of benchmark data.

### Method
GET

### Endpoint
`/api/v1/stocks/{ticker}/prices/history`

#### Path Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., `005930`).

#### Query Parameters
- **period** (string) - Optional - The historical period (e.g., `1D`, `5D`, `1M`, `6M`, `1Y`, `5Y`, `MAX`). Defaults to `1Y`.
- **frequency** (string) - Optional - The data frequency (e.g., `MINUTE`, `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`). Defaults to `DAILY`.
- **includeBenchmark** (boolean) - Optional - Whether to include benchmark data in the response. Defaults to `false`.

### Request Example
```bash
# Get price history (1 year, daily) with benchmark
curl -X GET "http://localhost:8080/api/v1/stocks/005930/prices/history?period=1Y&frequency=DAILY&includeBenchmark=true"
```

### Response
#### Success Response (200)
- **object** - Historical price data.
  - **ticker** (string) - The stock ticker symbol.
  - **period** (string) - The requested historical period.
  - **frequency** (string) - The requested data frequency.
  - **prices** (array) - Array of price data points.
    - **date** (string) - The date of the price data.
    - **open** (number) - The opening price.
    - **high** (number) - The highest price during the period.
    - **low** (number) - The lowest price during the period.
    - **close** (number) - The closing price.
    - **volume** (number) - The trading volume.
  - **benchmark** (object, optional) - Benchmark data if `includeBenchmark` is true.
    - **ticker** (string) - The benchmark ticker (e.g., `KOSPI`).
    - **prices** (array) - Array of benchmark price data points.
      - **date** (string) - The date of the benchmark price data.
      - **close** (number) - The closing price of the benchmark.

#### Response Example
```json
{
  "ticker": "005930",
  "period": "1Y",
  "frequency": "DAILY",
  "prices": [
    {"date": "2026-03-12", "open": 72800, "high": 73800, "low": 72500, "close": 73500, "volume": 12500000},
    {"date": "2026-03-11", "open": 72000, "high": 73000, "low": 71800, "close": 72600, "volume": 11000000}
  ],
  "benchmark": {
    "ticker": "KOSPI",
    "prices": [
      {"date": "2026-03-12", "close": 2650.5},
      {"date": "2026-03-11", "close": 2635.2}
    ]
  }
}
```
```

--------------------------------

### GET /api/v1/portfolios/{portfolioId}/health

Source: https://github.com/oxix97/stockwellness/blob/develop/conductor/tracks/portfolio_health_diagnosis_20260205/spec.md

Retrieves a comprehensive health diagnosis for a specific user portfolio, including category scores, AI-generated insights, and actionable recommendations.

```APIDOC
## GET /api/v1/portfolios/{portfolioId}/health

### Description
Calculates and returns the health diagnosis of a portfolio based on five key dimensions: Defense, Attack, Endurance, Agility, and Balance. The response includes weighted scores, AI-generated summaries, and actionable steps for the investor.

### Method
GET

### Endpoint
/api/v1/portfolios/{portfolioId}/health

### Parameters
#### Path Parameters
- **portfolioId** (string) - Required - The unique identifier of the portfolio to diagnose.

### Request Example
GET /api/v1/portfolios/user-123/health

### Response
#### Success Response (200)
- **overallScore** (integer) - The aggregate portfolio health score (0-100).
- **categories** (object) - Map of scores for attack, defense, endurance, agility, and balance.
- **stockContributions** (array) - List of objects containing name, mainContribution, score, and reason.
- **aiDiagnosis** (object) - Contains summary (e.g., "Growth Archer") and insight text.
- **nextSteps** (array) - List of actionable strings for portfolio improvement.

#### Response Example
{
  "overallScore": 78,
  "categories": {
    "defense": 80,
    "attack": 70,
    "endurance": 90,
    "agility": 60,
    "balance": 80
  },
  "stockContributions": [
    {
      "name": "TechCorp",
      "mainContribution": "Attack",
      "score": 85,
      "reason": "High RSI and positive MACD"
    }
  ],
  "aiDiagnosis": {
    "summary": "Growth Archer",
    "insight": "Your portfolio shows strong offensive capabilities but could benefit from more defensive large-cap stocks."
  },
  "nextSteps": [
    "Add 1 piece of KOSPI large-cap for defense"
  ]
}
```

--------------------------------

### Compare Sector vs Market (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Compares the performance of a specific sector against a market benchmark for a given date. It provides metrics such as sector return, market return, outperformance, correlation, and beta, indicating the sector's risk and return profile relative to the market.

```bash
# Compare sector with market
curl -X GET "http://localhost:8080/api/v1/sectors/G45/comparison?date=2026-03-12"
```

--------------------------------

### List Portfolios (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves all portfolios owned by the authenticated user. This endpoint requires an Authorization header with a Bearer token. The response includes a list of portfolios with their summary information.

```bash
# Get all portfolios
curl -X GET "http://localhost:8080/api/v1/portfolios" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response
{
  "data": [
    {
      "id": 1,
      "name": "Tech Growth Portfolio",
      "description": "Focus on technology sector growth stocks",
      "totalValue": 19500000,
      "totalReturn": 5.2,
      "itemCount": 3,
      "createdAt": "2026-01-15T10:00:00"
    },
    {
      "id": 2,
      "name": "Dividend Income Portfolio",
      "description": "High dividend yield stocks",
      "totalValue": 25000000,
      "totalReturn": 3.8,
      "itemCount": 5,
      "createdAt": "2026-02-01T14:30:00"
    }
  ],
  "timestamp": "2026-03-12T17:00:00.000000"
}
```

--------------------------------

### Authentication API

Source: https://context7.com/oxix97/stockwellness/llms.txt

Handles user authentication, including login, token reissue, and logout.

```APIDOC
## POST /api/v1/auth/login

### Description
Authenticates a user and returns JWT tokens for subsequent API calls. Supports OAuth2 login (Google, Kakao) and email-based login.

### Method
POST

### Endpoint
/api/v1/auth/login

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **nickname** (string) - Required - The user's nickname.
- **loginType** (string) - Required - The type of login (e.g., "KAKAO", "GOOGLE").

### Request Example
```json
{
  "email": "user@example.com",
  "nickname": "investor123",
  "loginType": "KAKAO"
}
```

### Response
#### Success Response (200)
- **accessToken** (string) - The JWT access token.
- **refreshToken** (string) - The JWT refresh token.
- **memberId** (integer) - The unique identifier for the member.
- **email** (string) - The user's email address.
- **nickname** (string) - The user's nickname.

#### Response Example
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "memberId": 1,
  "email": "user@example.com",
  "nickname": "investor123"
}
```

## POST /api/v1/auth/reissue

### Description
Reissues access and refresh tokens using a valid refresh token.

### Method
POST

### Endpoint
/api/v1/auth/reissue

### Parameters
#### Request Body
- **refreshToken** (string) - Required - The user's refresh token.

### Request Example
```json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Response
#### Success Response (200)
- **accessToken** (string) - The new JWT access token.
- **refreshToken** (string) - The new JWT refresh token.

#### Response Example
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

## POST /api/v1/auth/logout

### Description
Invalidates the user's refresh token and terminates the session. Requires authentication.

### Method
POST

### Endpoint
/api/v1/auth/logout

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- The response body is empty.

```

--------------------------------

### Search Stocks by Keyword (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Performs a unified search across all listed stocks based on a keyword. It supports filtering by market type and pagination, returning a list of matching stocks with key details.

```bash
# Search stocks by keyword
curl -X GET "http://localhost:8080/api/v1/stocks/search?keyword=samsung&marketType=KOSPI&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get Recent Stock Search History (Bash)

Source: https://context7.com/oxix97/stockwellness/llms.txt

Retrieves a user's recent stock search keywords. This endpoint is useful for providing quick access to previously searched items.

```bash
# Get recent searches
curl -X GET "http://localhost:8080/api/v1/stocks/search/history" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Authenticate User via Login

Source: https://context7.com/oxix97/stockwellness/llms.txt

Authenticates a user using email or OAuth credentials and returns JWT access and refresh tokens. This is the entry point for secure API access.

```bash
curl -X POST "http://localhost:8080/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "nickname": "investor123",
    "loginType": "KAKAO"
  }'
```