Finhay Market

Finhay Market

Read-only market data via the Finhay Securities Open API.

MANDATORY: Ensure credentials are set (via environment variables FINHAY_API_KEY/FINHAY_API_SECRET or via ./finhay.sh auth). Run ./finhay.sh doctor to verify.

Usage Examples

# Get real-time stock quote
./finhay.sh request GET /market/stock-realtime "symbol=VNM"

# Get gold spot price
./finhay.sh request GET /market/financial-data/gold

# Get historical OHLCV chart data
./finhay.sh request GET /market/price-histories-chart "symbol=VNM&resolution=1D&from=1609459200&to=1704067200"

CLI Command Reference

Agent Attribution

REQUIRED: Export AGENT_NAME before making any request. Use your tool's canonical lowercase identifier in kebab-case (e.g. claude-code). Any value is accepted as long as it consistently identifies your tool.

export AGENT_NAME=claude-code
./finhay.sh request GET /market/stock-realtime "symbol=VNM"

Sent as X-FH-OPENAPI-AGENT and embedded in User-Agent.

Endpoints

Constraints

• Read-only: Execute GET requests only.
• Privacy: Mask sensitive credentials in all output.
• Credentials: If FINHAY_API_KEY or FINHAY_API_SECRET are missing, stop and ask the user to provide them or run ./finhay.sh auth.
• Parameters: Pass exactly one identifier for stock quotes (symbol, symbols, or exchange).
• Timeframes: Price history timestamps must be in seconds. Default to the last 5 years if range is not provided.

Market Endpoints

Signing: use ./finhay.sh request (or .\finhay.ps1 request).

Errors

400 = invalid request, 401 = auth failure, 429 = rate limited.

Common causes: missing API key, combining symbol/symbols/exchange, path mismatch in signature.

Response Keys

• result — stock-realtime, index-realtime
• data — all other endpoints

---

Stock

News

Financial Data — Precious Metals

Financial Data — Other

Financial Data — Market Indices & Assets

Financial Data — Economic Calendar

Funds

Reports

Price History

Company Financial

---

Choosing the Right Company Financial Endpoint

type values for statement endpoints: income-statement, balance-sheet, cash-flow period values: annual, quarterly

---

Choosing the Right Financial Data Endpoint

Bank Interest Rates

GET /market/financial-data/bank-interest-rates

Retrieve bank deposit interest rates.

---

OpenAPI Spec

/market/financial-data/bank-interest-rates:
  get:
    summary: Get bank interest rates
    operationId: getBankInterestRates
    tags:
      - Financial Data
    parameters: []
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: object
                  description: >
                    Bank interest rate data. Structure depends on cached data.
                    Returns empty object `{}` if data has not been cached yet.

Response Key

data

Notes

• Data is served from Redis cache (DATAFEED_FINANCIAL_DATA_BANK_INTEREST_RATES key).
• May return {} if no data has been cached yet.
• The exact structure of the cached data depends on the upstream sync job.

Company Financial Analysis

GET /market/company-financial/analysis

Retrieve historical financial metrics for a stock by period (annual or quarterly).

---

OpenAPI Spec

/market/company-financial/analysis:
  get:
    summary: Get company financial analysis over time
    operationId: getCompanyFinancialAnalysis
    tags:
      - Company Financial
    parameters:
      - name: symbol
        in: query
        required: true
        schema:
          type: string
          example: VNM
        description: Stock symbol (uppercase alphanumeric)
      - name: period
        in: query
        required: false
        schema:
          type: string
          enum: [annual, quarterly]
          example: annual
        description: Reporting period. Defaults to annual if omitted.
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code:
                  type: string
                  example: "0"
                message:
                  type: string
                  example: success
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/FinancialAnalysisEntry'

Components

components:
  schemas:
    FinancialAnalysisEntry:
      type: object
      description: >
        Financial metrics for one period. Contains `year` always;
        `quarter` is present only when period=quarterly.
        All other fields are dynamic metric codes (e.g. pe, roe, eps, pb) with numeric or null values.
      properties:
        year:
          type: integer
          example: 2023
        quarter:
          type: integer
          nullable: true
          description: Present only for quarterly period (1–4)
          example: 2
      additionalProperties:
        type: number
        nullable: true

Notes

• period values: annual or quarterly.
• Annual response: array of { year, <metricCode>: number | null, ... }.
• Quarterly response: array of { year, quarter, <metricCode>: number | null, ... }.
• Metric codes vary by company type (e.g. banks have nim, manufacturing has gross_margin).

Company Financial Overview

GET /market/company-financial/overview

Retrieve key financial ratios and metrics for a stock symbol.

---

OpenAPI Spec

/market/company-financial/overview:
  get:
    summary: Get company financial overview
    operationId: getCompanyFinancialOverview
    tags:
      - Company Financial
    parameters:
      - name: symbol
        in: query
        required: true
        schema:
          type: string
          example: VNM
        description: Stock symbol (uppercase alphanumeric, e.g. `VNM`)
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code:
                  type: string
                  example: "0"
                message:
                  type: string
                  example: success
                data:
                  $ref: '#/components/schemas/FinancialOverview'

Components

components:
  schemas:
    FinancialOverview:
      type: object
      properties:
        pe:
          type: number
          nullable: true
          description: Price-to-Earnings ratio
        pb:
          type: number
          nullable: true
          description: Price-to-Book ratio
        ev_ebitda:
          type: number
          nullable: true
          description: EV/EBITDA ratio
        industry:
          type: object
          description: Industry average ratios
          properties:
            pe:
              type: number
              nullable: true
            pb:
              type: number
              nullable: true
            ev_ebitda:
              type: number
              nullable: true
        gross_margin:
          type: number
          nullable: true
          description: Gross profit margin
        roe:
          type: number
          nullable: true
          description: Return on Equity
        eps:
          type: number
          nullable: true
          description: Earnings per Share
        dividend_yield:
          type: number
          nullable: true
        nim:
          type: number
          nullable: true
          description: Net Interest Margin (banks only)
        margin_loan_to_equity_ratio:
          type: number
          nullable: true
          description: Margin loan to equity ratio (securities firms only)
        roa:
          type: number
          nullable: true
          description: Return on Assets

Notes

• symbol is required and converted to uppercase.
• industry contains the sector-average values for the same ratios.
• nim and margin_loan_to_equity_ratio are only meaningful for banks and securities firms respectively.

Top Trending Cryptos

GET /market/financial-data/cryptos/top-trending

Retrieve top trending cryptocurrencies.

---

OpenAPI Spec

/market/financial-data/cryptos/top-trending:
  get:
    summary: Get top trending cryptocurrencies
    operationId: getTopTrendingCryptos
    tags:
      - Financial Data
    parameters: []
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/CryptoCurrency'

Response Key

data

Components

components:
  schemas:
    CryptoCurrency:
      type: object
      properties:
        name:
          type: string
          description: Cryptocurrency name
          example: Bitcoin
        symbol:
          type: string
          description: Cryptocurrency symbol
          example: BTC
        icon_url:
          type: string
          description: Icon URL
          example: https://example.com/btc.png
        price:
          type: number
          description: Current price in USD
          example: 67500.25
        formatted_price:
          type: string
          description: Price formatted in Vietnamese locale
          example: "67.500,25"
        percent_change_1h:
          type: number
          description: Price change in the last 1 hour (%)
          example: 0.5
        percent_change_24h:
          type: number
          description: Price change in the last 24 hours (%)
          example: -1.2
        percent_change_7d:
          type: number
          description: Price change in the last 7 days (%)
          example: 3.8
        percent_change_30d:
          type: number
          description: Price change in the last 30 days (%)
          example: 12.5
        market_cap:
          type: number
          description: Market capitalization in USD
          example: 1325000000000
        last_30d_chart:
          type: string
          description: URL or data for 30-day sparkline chart

Economic Calendar Events

GET /market/financial-data/economic-calendar-events

Retrieve upcoming global economic events (CPI releases, Fed meetings, PMI announcements, etc.).

---

OpenAPI Spec

/market/financial-data/economic-calendar-events:
  get:
    summary: Get upcoming economic calendar events
    operationId: getEconomicCalendarEvents
    tags:
      - Financial Data
    parameters:
      - name: weeks
        in: query
        required: false
        description: Number of weeks ahead to fetch events (default 1)
        schema:
          type: integer
          default: 1
          example: 2
      - name: country
        in: query
        required: false
        description: Filter by country name. Must match exactly one of the supported values.
        schema:
          type: string
          enum:
            - China
            - Euro Area
            - Japan
            - United States
            - United Kingdom
            - Vietnam
          example: China
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/EconomicCalendarEvent'

Response Key

data

Components

components:
  schemas:
    EconomicCalendarEvent:
      type: object
      properties:
        id:
          type: integer
          example: 1
        date:
          type: string
          description: Event date in `YYYY-MM-DD` format
          example: "2026-04-25"
        country:
          type: string
          description: Country name
          enum:
            - China
            - Euro Area
            - Japan
            - United States
            - United Kingdom
            - Vietnam
          example: "United States"
        event:
          type: string
          description: Event name
          example: "Fed Interest Rate Decision"
        actual:
          type: string
          description: Actual value (empty if not yet released)
          example: "5.50%"
        previous:
          type: string
          description: Previous period value
          example: "5.25%"
        consensus:
          type: string
          description: Market consensus forecast
          example: "5.50%"
        forecast:
          type: string
          description: Analyst forecast
          example: "5.50%"
        impact:
          type: integer
          description: Impact level (1 = low, 2 = medium, 3 = high)
          example: 3
        category:
          type: string
          description: Event category
          example: "Interest Rate"

Notes

• weeks defaults to 1 — returns events from today through the next 7 days.
• country is optional — omit to return events for all supported countries.
• Results are sorted ascending by date.
• Data is cached with a TTL of 1 hour.
• actual is empty string if the event has not yet occurred.
• Only events for the following countries are available: China, Euro Area, Japan, United States, United Kingdom, Vietnam.

Financial Data (All Types)

GET /market/financial-data

Retrieve all financial data: gold, silver, crypto, bank rates, USD exchange rates, etc.

---

OpenAPI Spec

/market/financial-data:
  get:
    summary: Get all financial data
    operationId: getFinancialData
    tags:
      - Financial Data
    parameters: []
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/FinancialData'

Response Key

data

Components

components:
  schemas:
    FinancialData:
      type: object
      properties:
        financial_type:
          type: string
          description: Type of financial data
          enum:
            - GOLD
            - SILVER
            - CRYPTO
            - BANK_INTEREST_RATE
            - USD_EXCHANGE_RATE
        name:
          type: string
          description: Display name of the financial type
        values:
          type: array
          description: >
            Array of financial data values. Shape varies by `financial_type`:
            single-value types use `FinancialDataSingleValue`,
            buy/sell types use `FinancialDataBuySellValue`,
            USD/VND types use `FinancialDataUSDVNDValue`.
          items:
            oneOf:
              - $ref: '#/components/schemas/FinancialDataSingleValue'
              - $ref: '#/components/schemas/FinancialDataBuySellValue'
              - $ref: '#/components/schemas/FinancialDataUSDVNDValue'
        last_updated:
          type: string
          description: ISO timestamp of last update

    FinancialDataSingleValue:
      type: object
      properties:
        name:
          type: string
        value:
          type: number
        change_percent:
          type: number

    FinancialDataBuySellValue:
      type: object
      properties:
        name:
          type: string
        buy_value:
          type: number
        sell_value:
          type: number
        change_percent:
          type: number

    FinancialDataUSDVNDValue:
      type: object
      properties:
        name:
          type: string
        usd_value:
          type: number
        vnd_value:
          type: number

Notes

• This is the all-in-one endpoint. For specific data types, use the dedicated endpoints (/gold, /silver, /bank-interest-rates, etc.).
• USD exchange rate values are sorted by sortValue.

Financial Statement V2

GET /market/v2/financial-statement/statement

Retrieve financial statement data in a normalized metric-value format. Each row represents one metric for one period, suitable for charting and comparison.

---

OpenAPI Spec

/market/v2/financial-statement/statement:
  get:
    summary: Get financial statement (v2 — metric-value format)
    operationId: getFinancialStatementV2
    tags:
      - Company Financial
    parameters:
      - name: symbol
        in: query
        required: true
        schema:
          type: string
          example: VNM
        description: Stock symbol (uppercase alphanumeric)
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum: [income-statement, balance-sheet, cash-flow]
          example: income-statement
        description: Statement type
      - name: period
        in: query
        required: false
        schema:
          type: string
          enum: [annual, quarterly]
          example: annual
        description: Reporting period
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 5
          default: 5
          example: 5
        description: Number of periods to return (1–5, default 5)
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code:
                  type: string
                  example: "0"
                message:
                  type: string
                  example: success
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/FinancialMetricValue'

Components

components:
  schemas:
    FinancialMetricValue:
      type: object
      description: One metric value for one period.
      properties:
        symbol:
          type: string
          example: VNM
        metricCode:
          type: string
          description: Metric identifier (e.g. "tongDoanhThu", "lnst")
          example: tongDoanhThu
        metricValue:
          type: number
          example: 12500000000000
        timeType:
          type: string
          description: Period type identifier
          example: annual
        year:
          type: integer
          example: 2023
        quarter:
          type: integer
          description: "0 for annual records"
          example: 0

Notes

• Same parameters as GET /financial-statement/statement but different response shape.
• V1 returns one object per period with all fields; V2 returns one row per metric per period.
• V2 is better suited for time-series queries (e.g. "show me net profit over 5 years").
• quarter is 0 for annual records.

Fund Benchmark

Two endpoints for comparing multiple funds side-by-side: investment growth simulation and NAV time series.

---

GET /fund-trading/public/fund-certificates/benchmark/growth

Simulate the projected return of a fixed VND investment across multiple funds over a period.

/fund-trading/public/fund-certificates/benchmark/growth:
  get:
    summary: Simulate growth of a VND investment across funds
    operationId: getGrowthBenchmark
    tags:
      - Funds
    parameters:
      - name: fund-names
        in: query
        required: true
        schema:
          type: string
          example: VESAF,DCDS
        description: Comma-separated fund short names.
      - name: amount
        in: query
        required: true
        schema:
          type: integer
          format: int64
          example: 10000000
        description: Investment amount in VND.
      - name: period
        in: query
        required: true
        schema:
          type: string
          enum: [BEGIN_THE_YEAR, ONE_MONTH, THREE_MONTHS, SIX_MONTHS, ONE_YEAR, THREE_YEARS, FIVE_YEARS, SEVEN_YEARS, TEN_YEARS, ALL_TIME]
          example: ONE_YEAR
        description: Time window over which to simulate growth.
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code: {type: string, example: "0"}
                message: {type: string, example: success}
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/GrowthBenchmark'

---

GET /fund-trading/public/fund-certificates/benchmark/nav

Compare NAV time series across funds (for charting on a shared axis).

/fund-trading/public/fund-certificates/benchmark/nav:
  get:
    summary: Compare NAV time series across funds
    operationId: getNavBenchmark
    tags:
      - Funds
    parameters:
      - name: fund-names
        in: query
        required: true
        schema:
          type: string
          example: VESAF,DCDS
        description: Comma-separated fund short names.
      - name: period
        in: query
        required: false
        schema:
          type: string
          enum: [BEGIN_THE_YEAR, ONE_MONTH, THREE_MONTHS, SIX_MONTHS, ONE_YEAR, THREE_YEARS, FIVE_YEARS, SEVEN_YEARS, TEN_YEARS, ALL_TIME]
          example: ONE_YEAR
        description: Either `period` OR both `from-month` + `to-month` must be provided.
      - name: from-month
        in: query
        required: false
        schema:
          type: string
          example: "2024-01"
        description: Start month (`yyyy-MM`). Required if `period` omitted.
      - name: to-month
        in: query
        required: false
        schema:
          type: string
          example: "2024-12"
        description: End month (`yyyy-MM`). Required if `period` omitted.
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code: {type: string, example: "0"}
                message: {type: string, example: success}
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/NavBenchmark'

Components

components:
  schemas:
    GrowthBenchmark:
      type: object
      properties:
        fund_name: {type: string, example: VESAF}
        profit_percent: {type: number, example: 18.4}
        current_amount:
          type: integer
          description: Projected portfolio value in VND.
          example: 11840000

    NavBenchmark:
      type: object
      properties:
        fund_name: {type: string, example: VESAF}
        nav_records:
          type: array
          items:
            type: object
            properties:
              date: {type: string, example: "2024-12-31"}
              navpf: {type: number, example: 18234.56}
              change_percent: {type: number, example: 1.24}

Notes

• fund-names is a comma-separated string parsed via split(","). No repeated-query syntax.
• benchmark/growth: period is required; does not accept from-month/to-month.
• benchmark/nav: must provide either period OR both from-month AND to-month. Server returns 400 otherwise.
• period semantics: BEGIN_THE_YEAR = year-to-date; ALL_TIME ≈ 20 years.
• All monetary fields are in VND.

Fund Companies

GET /fund-trading/public/fund-companies

List all fund management companies (used for the fund-company-id filter on /fund-certificates).

---

OpenAPI Spec

/fund-trading/public/fund-companies:
  get:
    summary: Get all fund management companies
    operationId: getFundCompanies
    tags:
      - Funds
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code: {type: string, example: "0"}
                message: {type: string, example: success}
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/FundCompany'

Components

components:
  schemas:
    FundCompany:
      type: object
      properties:
        id: {type: integer, example: 12}
        name: {type: string, example: "Công ty Quản lý quỹ Vietcombank"}
        short_name: {type: string, example: VCBF}
        image_url: {type: string, format: uri}

Notes

• No parameters; full list returned in one call.
• id is the value to pass as fund-company-id on the fund list endpoint.

Fund Details

Per-fund detail endpoint under /fund-trading/public/fund-certificates/{fundName}/.... Takes a single path param fundName.

---

GET /fund-trading/public/fund-certificates/{fundName}/suggestions

Similar funds suggested by criteria (NAV size or growth).

/fund-trading/public/fund-certificates/{fundName}/suggestions:
  get:
    summary: Get suggested similar funds
    operationId: getFundSuggestions
    tags:
      - Funds
    parameters:
      - name: fundName
        in: path
        required: true
        schema: {type: string, example: VESAF}
        description: Fund short name.
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code: {type: string, example: "0"}
                message: {type: string, example: success}
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/SuggestedFund'

Components

components:
  schemas:
    SuggestedFund:
      type: object
      properties:
        fund_name: {type: string, example: DCDS}
        criteria:
          type: string
          enum: [NET_ASSET_EQUIVALENT, GROWTH_EQUIVALENT]
          description: |
            How the fund was matched:
            - `NET_ASSET_EQUIVALENT`: similar AUM size.
            - `GROWTH_EQUIVALENT`: similar historical growth profile.

Notes

• SuggestedFund.criteria indicates which similarity heuristic produced each entry; results may include both criteria.

Fund Months

GET /market/funds/{fund}/months

Retrieve the list of available portfolio months for a specific fund.

---

OpenAPI Spec

/market/funds/{fund}/months:
  get:
    summary: Get available fund months
    operationId: getFundMonths
    tags:
      - Funds
    parameters:
      - name: fund
        in: path
        required: true
        description: Fund code
        schema:
          type: string
          example: DCDS
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  description: List of available months
                  items:
                    type: string
                  example:
                    - "2024-01"
                    - "2024-02"
                    - "2024-03"

Response Key

data

Notes

• Returns a simple array of month strings.
• Use these values as the month query param in /market/funds/{fund}/portfolio.

Fund NAV History

GET /fund-trading/public/fund-certificates/{fundName}/nav-histories

Historical NAV time series for a single fund, returned alongside the matching benchmark index series for charting.

---

OpenAPI Spec

/fund-trading/public/fund-certificates/{fundName}/nav-histories:
  get:
    summary: Get fund NAV history with benchmark
    operationId: getFundNavHistories
    tags:
      - Funds
    parameters:
      - name: fundName
        in: path
        required: true
        schema:
          type: string
          example: VESAF
        description: Fund short name.
      - name: period
        in: query
        required: false
        schema:
          type: string
          enum: [BEGIN_THE_YEAR, ONE_MONTH, THREE_MONTHS, SIX_MONTHS, ONE_YEAR, THREE_YEARS, FIVE_YEARS, SEVEN_YEARS, TEN_YEARS, ALL_TIME]
          default: ALL_TIME
          example: ONE_YEAR
        description: Time window. Defaults to `ALL_TIME` when omitted.
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code: {type: string, example: "0"}
                message: {type: string, example: success}
                data:
                  $ref: '#/components/schemas/NavHistories'

Components

components:
  schemas:
    NavHistories:
      type: object
      properties:
        nav_histories:
          type: array
          items:
            type: object
            properties:
              date: {type: string, example: "2025-04-30"}
              nav: {type: number, example: 18234.56}
              benchmark_value:
                type: number
                description: Benchmark index value on the same date.
                example: 1284.91
        benchmark_name:
          type: string
          description: Benchmark name (e.g. `VN-INDEX` for stock funds).
          example: VN-INDEX

Notes

• BEGIN_THE_YEAR = year-to-date.
• ALL_TIME ≈ 20 years; use only when a long history is genuinely needed.
• The server returns NAV records and the benchmark series clipped to the same date range so they can be charted on a shared X axis.

Fund Portfolio

GET /market/funds/{fund}/portfolio

Retrieve the portfolio holdings of a specific fund for a given month.

---

OpenAPI Spec

/market/funds/{fund}/portfolio:
  get:
    summary: Get fund portfolio
    operationId: getFundPortfolio
    tags:
      - Funds
    parameters:
      - name: fund
        in: path
        required: true
        description: Fund code
        schema:
          type: string
          example: DCDS
      - name: month
        in: query
        required: false
        description: Month in format to filter portfolio (e.g. `2024-01`). If omitted, returns the latest available month.
        schema:
          type: string
          example: "2024-01"
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  $ref: '#/components/schemas/PortfolioFund'

Response Key

data

Components

components:
  schemas:
    PortfolioFund:
      type: object
      properties:
        month:
          type: string
          description: Portfolio month
          example: "2024-01"
        entries:
          type: array
          description: Portfolio holdings sorted by per_nav descending
          items:
            $ref: '#/components/schemas/PortfolioFundEntry'
        stocks_info:
          type: array
          description: Realtime stock info for the holdings
          items:
            $ref: '#/components/schemas/StockInfoV1'

    PortfolioFundEntry:
      type: object
      properties:
        fund_code:
          type: string
          example: DCDS
        symbol:
          type: string
          example: FPT
        sector:
          type: string
          example: Technology
        per_nav:
          type: number
          description: Percentage of NAV
          example: 8.5
        month:
          type: string
          example: "2024-01"

    StockInfoV1:
      type: object
      properties:
        symbol:
          type: string
          example: FPT
        name:
          type: string
          example: CTCP FPT
        exchange:
          type: string
          enum: [HOSE, HNX, UPCOM]
        floor:
          type: number
          description: Floor price
        ceiling:
          type: number
          description: Ceiling price
        reference:
          type: number
          description: Reference price
        stock_type:
          type: string
          enum: [STOCK, ETF, BOND, CW, FUTURES]
        price:
          type: number
        price_change:
          type: number
        price_change_percent:
          type: number
        volume:
          type: number
          nullable: true
        total_volume:
          type: number
          nullable: true

Funds

GET /fund-trading/public/fund-certificates

List funds filtered by type (and optionally by management company), sorted by 1-year average profit (descending).

---

OpenAPI Spec

/fund-trading/public/fund-certificates:
  get:
    summary: Get fund list
    operationId: getFundCertificates
    tags:
      - Funds
    parameters:
      - name: fund-type
        in: query
        required: true
        schema:
          type: string
          enum: [STOCK_FUND, BOND_FUND, BALANCE_FUND]
          example: STOCK_FUND
        description: Fund category.
      - name: fund-company-id
        in: query
        required: false
        schema:
          type: integer
          format: int64
          example: 12
        description: Filter by management company ID. See `/fund-trading/public/fund-companies`.
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code: {type: string, example: "0"}
                message: {type: string, example: success}
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/FundCertificate'

Components

components:
  schemas:
    FundCertificate:
      type: object
      properties:
        id: {type: integer, example: 21}
        name: {type: string, example: VESAF}
        type:
          type: string
          enum: [STOCK_FUND, BOND_FUND, BALANCE_FUND]
        aum:
          type: integer
          description: Assets under management in VND.
          example: 1500000000000
        rating: {type: number, example: 4.5}

Notes

• fund-type is required.
• Manulife fund (id=36) is filtered server-side and never appears.
• Results sorted by 1-year average profit (desc).

Global News

GET /market/financial-data/global-news

Retrieve a paginated list of global financial news articles, optionally filtered by category.

---

OpenAPI Spec

/market/financial-data/global-news:
  get:
    summary: List global financial news
    operationId: getGlobalNewsList
    tags:
      - Financial Data
    parameters:
      - name: category
        in: query
        required: false
        description: Filter by news category
        schema:
          type: string
          enum:
            - forex
            - commodities
            - economic-indicators
            - stock-market
            - cryptocurrency
          example: stock-market
      - name: page
        in: query
        required: false
        description: Page number (min 1, default 1)
        schema:
          type: integer
          minimum: 1
          default: 1
          example: 1
      - name: page_size
        in: query
        required: false
        description: Number of items per page (min 1, max 50, default 20)
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
          example: 20
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code:
                  type: string
                  example: "0"
                message:
                  type: string
                  example: success
                data:
                  $ref: '#/components/schemas/GlobalNewsPage'

Response Key

data

Components

components:
  schemas:
    GlobalNewsPage:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/GlobalNewsListItem'
        page_total:
          type: integer
          description: Number of items in the current page
        total:
          type: integer
          description: Total number of matching articles
        current_page:
          type: integer
        next_page:
          type: integer
          nullable: true
        previous_page:
          type: integer
          nullable: true

    GlobalNewsListItem:
      type: object
      properties:
        id:
          type: integer
          description: Article ID (use for detail lookup)
        title:
          type: string
        url:
          type: string
          description: Original article URL
        description:
          type: string
          nullable: true
          description: Short summary of the article
        provider:
          type: string
          nullable: true
          description: News source/provider name
        published_at:
          type: string
          format: date-time
          description: Publication timestamp (ISO 8601)
        category:
          type: string
          enum:
            - forex
            - commodities
            - economic-indicators
            - stock-market
            - cryptocurrency

Notes

• All query parameters are optional.
• category must be one of the enum values exactly (lowercase, hyphenated).
• Default page size is 20; maximum is 50.
• Use the id field from list items to fetch full article content via the detail endpoint.

---

GET /market/financial-data/global-news/:id

Retrieve full details of a single global news article by its ID.

---

OpenAPI Spec

/market/financial-data/global-news/{id}:
  get:
    summary: Get global news article detail
    operationId: getGlobalNewsDetail
    tags:
      - Financial Data
    parameters:
      - name: id
        in: path
        required: true
        description: Article ID (from list endpoint)
        schema:
          type: integer
          example: 12
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code:
                  type: string
                  example: "0"
                message:
                  type: string
                  example: success
                data:
                  $ref: '#/components/schemas/GlobalNewsDetail'
      '404':
        description: Article not found
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code:
                  type: string
                  example: "404"
                message:
                  type: string
                  example: Global news not found
                data:
                  nullable: true

Response Key

data

Components

components:
  schemas:
    GlobalNewsDetail:
      allOf:
        - $ref: '#/components/schemas/GlobalNewsListItem'
        - type: object
          properties:
            content:
              type: string
              nullable: true
              description: Full article body/content

Notes

• Returns 404 with error_code: "404" if the article ID does not exist.
• content contains the full article body; description is a short summary (both also present from list).

Gold Chart

GET /market/financial-data/gold-chart

Retrieve gold price chart data over N days.

---

OpenAPI Spec

/market/financial-data/gold-chart:
  get:
    summary: Get gold price chart data
    operationId: getGoldChartData
    tags:
      - Financial Data
    parameters:
      - name: days
        in: query
        required: false
        description: Number of days of history to return. Defaults to `30`.
        schema:
          type: integer
          default: 30
          example: 30
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  description: Chart data points
                  items:
                    type: object

Response Key

data

Notes

• If days is not provided or not a valid integer, defaults to 30.
• Chart data is fetched from the financial data repository cache.

Gold Providers

GET /market/financial-data/gold-providers

Retrieve gold prices grouped by provider (PNJ, DOJI, BTMC, SJC, etc.).

---

OpenAPI Spec

/market/financial-data/gold-providers:
  get:
    summary: Get gold prices by provider
    operationId: getGoldProviderData
    tags:
      - Financial Data
    parameters: []
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/CommodityIndexData'

Response Key

data

Components

Uses the same CommodityIndexData schema as `gold.md`.

Notes

• Returns gold prices from multiple providers: PNJ, DOJI, BTMC, SJC, etc.
• Each entry includes provider and provider_icon fields to identify the source.

Gold Data

GET /market/financial-data/gold

Retrieve SJC gold prices and global gold price.

---

OpenAPI Spec

/market/financial-data/gold:
  get:
    summary: Get gold price data
    operationId: getGoldData
    tags:
      - Financial Data
    parameters: []
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/CommodityIndexData'

Response Key

data

Components

components:
  schemas:
    CommodityIndexData:
      type: object
      properties:
        index:
          type: string
          description: Index identifier
          example: SJC_GOLD
        name:
          type: string
          description: Display name
          example: Vàng SJC
        short_name:
          type: string
          description: Short display name
          example: SJC
        buy_value:
          type: number
          description: Buy price
          example: 92500000
        sell_value:
          type: number
          description: Sell price
          example: 94500000
        usd_value:
          type: number
          description: USD equivalent value
        vnd_value:
          type: number
          description: VND value
        date:
          type: string
          description: Price date
        provider:
          type: string
          description: Data provider name
          example: SJC
        provider_icon:
          type: string
          nullable: true
          description: Provider icon URL
        updated_at:
          type: string
          description: Last update timestamp
        change_percent:
          type: number
          description: Price change percentage
        buy_value_change_percent:
          type: number
          description: Buy value change percentage
        sell_value_change_percent:
          type: number
          description: Sell value change percentage

Notes

• DOJI_9999_GOLD_RING index is renamed to Vàng nhẫn DOJI in the response.
• Same CommodityIndexData schema is shared with /silver, /gold-providers, and /metal-providers.

Index Realtime

GET /market/index-realtime

Retrieve realtime market index data (VNINDEX, HNX30, …). Accepts index — one or more index codes, comma-separated.

---

OpenAPI Spec

/market/index-realtime:
  get:
    summary: Get realtime market index data
    operationId: getIndexRealtime
    tags:
      - Stock
    parameters:
      - name: index
        in: query
        description: >
          Index code(s), comma-separated. Pass one (`VNINDEX`) or many
          (`VNINDEX,HNX30`). One result entry is returned per code.
        required: true
        schema:
          type: string
          enum: [VNINDEX, HNXINDEX, UPCOMINDEX, VN30, HNX30]
          example: VNINDEX
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                result:
                  description: Array of `IndexRealtime` — one entry per requested index code.
                  type: array
                  items:
                    $ref: '#/components/schemas/IndexRealtime'
      '400':
        description: Invalid request

Response Key

result (array). Along with stock-realtime, one of only two market endpoints that use result instead of data.

Components

components:
  schemas:
    IndexRealtime:
      type: object
      properties:
        index:
          type: string
          example: VNINDEX
          description: Index code (echoes the requested `index`).
        indexValue:
          type: number
          example: 1792.6
          description: Current index points value.
        change:
          type: number
          example: 2.07
          description: Point change from reference.
        changePercent:
          type: number
          example: 0.12
          description: Percent change from reference (already in percent units, e.g. 0.12 = 0.12%).
        reference:
          type: number
          example: 1790.53
          description: Reference value — previous session close.
        allQuantity:
          type: integer
          format: int64
          example: 248009131
          description: Total matched volume across the market (shares).
        allValue:
          type: number
          description: Total matched trading value across the market (VND).
        advances:
          type: integer
          description: Number of advancing symbols.
        declines:
          type: integer
          description: Number of declining symbols.
        nochanges:
          type: integer
          description: Number of unchanged symbols.
        ceiling:
          type: integer
          description: Number of symbols at ceiling price.
        floor:
          type: integer
          description: Number of symbols at floor price.
        values:
          type: array
          items:
            type: number
          description: Intraday index point series (index-aligned with times/volumes).
        volumes:
          type: array
          items:
            type: number
          description: Intraday volume series (index-aligned with times/values).
        times:
          type: array
          items:
            type: integer
            format: int64
          description: Intraday timestamp series — Unix ms.
        advancesArr:
          type: array
          items:
            type: integer
          description: Intraday advancing-symbol series. KRX indices only.
        declinesArr:
          type: array
          items:
            type: integer
          description: Intraday declining-symbol series. KRX indices only.
        nochangesArr:
          type: array
          items:
            type: integer
          description: Intraday unchanged-symbol series. KRX indices only.
        ceilings:
          type: array
          items:
            type: integer
          description: Intraday ceiling-count series. KRX indices only.
        floors:
          type: array
          items:
            type: integer
          description: Intraday floor-count series. KRX indices only.
        sessionInExchange:
          type: string
          description: Current trading session state of the exchange.
        name:
          type: string
          example: VNINDEX
          description: Index name (currently same as `index`).

Notes

• result is always an array — one entry per requested code; a single index=VNINDEX still returns a 1-element array. Unknown/invalid codes are silently skipped (shorter array, possibly empty).
• indexValue / change / reference are in index points, not VND.
• changePercent is already in percent units (e.g. 0.12 = 0.12%), not a 0–1 ratio.
• Breadth fields (advances / declines / nochanges / ceiling / floor) and intraday series (values / volumes / times) are only present in full mode.
• The *Arr / ceilings / floors intraday series apply to KRX-system indices only.

Macro Data

GET /market/financial-data/macro

Retrieve macroeconomic data for Vietnam or the US.

---

OpenAPI Spec

/market/financial-data/macro:
  get:
    summary: Get macroeconomic data
    operationId: getMacroData
    tags:
      - Financial Data
    parameters:
      - name: type
        in: query
        required: true
        description: Macro data type
        schema:
          type: string
          enum:
            - IIP
            - CPI
            - PMI
            - PCE
            - CORE_PCE
            - NFP
            - FED_FUNDS_RATE
            - INTERBANK_RATE
            - GOVERNMENT_10Y_BOND_YIELD
            - UNEMPLOYMENT_RATE
      - name: country
        in: query
        required: true
        description: Country code. Most types support VN and US only. JP and DE are only valid for GOVERNMENT_10Y_BOND_YIELD.
        schema:
          type: string
          enum:
            - VN
            - US
            - JP
            - DE
      - name: period
        in: query
        required: false
        description: Time period filter
        schema:
          type: string
          enum:
            - ONE_MONTH
            - ONE_YEAR
            - YTD
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/MacroData'

Response Key

data

Components

components:
  schemas:
    MacroData:
      type: object
      properties:
        type:
          type: string
          description: Macro data type
          enum: [IIP, CPI, PMI, PCE, CORE_PCE, NFP, GOODS_RETAIL, SERVICE_RETAIL, TOTAL_EXPORT, FDI_EXPORT, DOMESTIC_EXPORT, FED_FUNDS_RATE, INTERBANK_RATE, GOVERNMENT_10Y_BOND_YIELD, UNEMPLOYMENT_RATE]
          example: CPI
        country:
          type: string
          enum: [VN, US]
          example: VN
        month:
          type: string
          description: Year-month in `YYYY-MM` format
          example: "2024-03"
        value:
          type: number
          description: Macro indicator value
          example: 3.5
        date:
          type: string
          nullable: true
          description: Exact date in `YYYY-MM-DD` format (if available)
          example: "2024-03-15"

Notes

• type and country are required. period is optional.
• JP (Japan) and DE (Germany) are only valid when type=GOVERNMENT_10Y_BOND_YIELD. All other types only support VN and US.
• Data is cached with a TTL of 360 seconds.
• month is formatted as YYYY-MM from year/month stored in DB.
• date is only present when the exact date is available in the source data.

Market Data (Indices, Stocks, Commodities, Forex)

GET /market/financial-data/market

Retrieve historical data points for a global market index, big-tech stock, commodity, or forex pair.

---

OpenAPI Spec

/market/financial-data/market:
  get:
    summary: Get global market data by type
    operationId: getMarketData
    tags:
      - Financial Data
    parameters:
      - name: type
        in: query
        required: true
        description: Market data type
        schema:
          type: string
          enum:
            # US Indices
            - SP500
            - DOW_JONES
            - NASDAQ
            - RUSSELL2000
            - VIX
            - DXY
            # Asian Indices
            - KOSPI
            - HANGSENG
            - SHANGHAI
            - NIKKEI
            # Big-tech stocks
            - APPLE
            - MICROSOFT
            - ALPHABET
            - AMAZON
            - META
            - NVIDIA
            - TESLA
            # Commodities
            - GOLD
            - SILVER
            - COPPER
            - CRUDE_OIL
            - BRENT_OIL
            - NATURAL_GAS
            # Forex
            - EURUSD
            - USDJPY
            - GBPUSD
      - name: limit
        in: query
        required: false
        description: Number of data points to return (default 50, max 500)
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 500
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/MarketData'

Response Key

data

Components

components:
  schemas:
    MarketData:
      type: object
      properties:
        type:
          type: string
          example: "SP500"
        country:
          type: string
          enum: [US, KR, HK, CN, JP, UK]
          example: "US"
        date:
          type: string
          description: Date in YYYY-MM-DD format
          example: "2026-04-22"
        year:
          type: integer
          example: 2026
        month:
          type: integer
          example: 4
        value:
          type: number
          example: 5234.18

Notes

• type is required. Results are ordered descending by date (most recent first).
• limit defaults to 50; maximum is 500.

Metal Providers

GET /market/financial-data/metal-providers

Retrieve both gold and silver prices grouped by provider.

---

OpenAPI Spec

/market/financial-data/metal-providers:
  get:
    summary: Get gold and silver prices by provider
    operationId: getMetalProviderData
    tags:
      - Financial Data
    parameters: []
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/CommodityIndexData'

Response Key

data

Components

Uses the same CommodityIndexData schema as `gold.md`.

Notes

• Superset of /gold-providers — includes both gold and silver entries from all providers.

News (Stock Events)

GET /market/news

Retrieve stock corporate events (rights issues, dividends, AGM dates, etc.) filtered by symbol(s) and/or date range.

---

OpenAPI Spec

/market/news:
  get:
    summary: Get stock events / corporate actions
    operationId: getStockEvents
    tags:
      - News
    parameters:
      - name: stock
        in: query
        required: false
        description: Single stock symbol (e.g. VNM)
        schema:
          type: string
          example: VNM
      - name: stocks
        in: query
        required: false
        description: Comma-separated list of stock symbols (e.g. VNM,VIC,HPG)
        schema:
          type: string
          example: VNM,VIC,HPG
      - name: from_date
        in: query
        required: false
        description: Start date filter in DD/MM/YYYY format. Defaults to 1 year ago from today when omitted.
        schema:
          type: string
          example: 01/01/2024
      - name: to_date
        in: query
        required: false
        description: End date filter in DD/MM/YYYY format. Only applied when both from_date and to_date are provided.
        schema:
          type: string
          example: 31/12/2024
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                error_code:
                  type: string
                  example: "0"
                message:
                  type: string
                  example: success
                result:
                  type: array
                  items:
                    $ref: '#/components/schemas/StockEventResponse'

Response Key

result

Components

components:
  schemas:
    StockEventResponse:
      type: object
      properties:
        id:
          type: integer
          nullable: true
          description: Event ID
        path:
          type: string
          nullable: true
          description: Internal path/slug of the event
        title:
          type: string
          nullable: true
          description: Event title
        stock:
          type: string
          description: Stock symbol
          example: VNM
        body:
          type: string
          nullable: true
          description: Event body/content
        createdDate:
          type: string
          description: Formatted creation date (DD/MM - HH:mm)
          example: "15/07 - 08:30"
        actionDate:
          type: string
          nullable: true
          description: Date the corporate action takes effect
        gdkhqDate:
          type: string
          nullable: true
          description: Ex-rights date (ngày GDKHQ)
        eventType:
          type: string
          nullable: true
          description: Event type code
        eventTypeName:
          type: string
          nullable: true
          description: Human-readable event type name
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        url:
          type: string
          nullable: true
          description: Full URL to the event detail page

Notes

• Pass stock for a single symbol or stocks for multiple (comma-separated). Both are optional — omitting both returns all events within the date range.
• from_date and to_date must be in DD/MM/YYYY format.
• When both from_date and to_date are provided, results are filtered by that exact range.
• When either is omitted, the service defaults to 1 year ago from today as the start with no upper bound.
• gdkhqDate is the ex-rights date relevant for dividend/rights-issue events.
• Returns an empty array when no events match the filters.

Price Histories Chart

GET /market/price-histories-chart

Retrieve historical price data for charting. Returns columnar arrays for efficient rendering.

---

OpenAPI Spec

/market/price-histories-chart:
  get:
    summary: Get price history chart data
    operationId: getPriceHistoriesChart
    tags:
      - Price History
    parameters:
      - name: symbol
        in: query
        required: true
        description: Stock symbol
        schema:
          type: string
          example: VNM
      - name: resolution
        in: query
        required: true
        description: Chart resolution. Defaults to `1D`.
        schema:
          type: string
          enum:
            - 1D
            - 5
            - 15
            - 30
            - 1H
            - 4H
      - name: from
        in: query
        required: true
        description: Start timestamp in **seconds** (Unix epoch). Not milliseconds.
        schema:
          type: integer
          minimum: 0
          example: 1704067200
      - name: to
        in: query
        required: true
        description: End timestamp in **seconds** (Unix epoch). Not milliseconds.
        schema:
          type: integer
          minimum: 0
          example: 1711929600
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  $ref: '#/components/schemas/PriceHistoriesChart'
      '400':
        description: Validation error
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 400
                error_code:
                  type: string
                  example: "400"
                message:
                  type: string
                  example: Invalid symbol

Response Key

data

Components

components:
  schemas:
    PriceHistoriesChart:
      type: object
      description: >
        Columnar arrays — all arrays are the same length.
        `time[i]`, `open[i]`, `close[i]`, `high[i]`, `low[i]`, `volume[i]`
        represent one data point.
      properties:
        symbol:
          type: string
          example: VNM
        resolution:
          type: string
          enum: [1D, 5, 15, 30, 1H, 4H]
          example: 1D
        time:
          type: array
          description: Unix timestamps (seconds)
          items:
            type: number
          example: [1704067200, 1704153600]
        open:
          type: array
          description: Open prices
          items:
            type: number
          example: [72000, 72500]
        close:
          type: array
          description: Close prices
          items:
            type: number
          example: [72500, 73000]
        high:
          type: array
          description: High prices
          items:
            type: number
          example: [73000, 73500]
        low:
          type: array
          description: Low prices
          items:
            type: number
          example: [71500, 72000]
        volume:
          type: array
          description: Trading volumes
          items:
            type: number
          example: [1500000, 1800000]

Validation Rules

All parameters are validated before reaching the controller:

Notes

• from and to are in seconds, not milliseconds.
• All response arrays have the same length — index i across all arrays represents one candle.
• Data is served from cache when available, falling back to the database and then external API.

Recommendation Reports

GET /market/recommendation-reports/{symbol}

Retrieve recommendation reports for a specific stock symbol (sourced from Vietstock).

---

OpenAPI Spec

/market/recommendation-reports/{symbol}:
  get:
    summary: Get recommendation reports by symbol
    operationId: getRecommendationReportsBySymbol
    tags:
      - Reports
    parameters:
      - name: symbol
        in: path
        required: true
        description: Stock symbol
        schema:
          type: string
          example: VNM
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  oneOf:
                    - type: array
                      items: {}
                      description: Empty array when no reports found
                      example: []
                    - $ref: '#/components/schemas/RecommendationReportResponse'

Response Key

data

Components

components:
  schemas:
    RecommendationReportResponse:
      type: object
      properties:
        recommendation:
          type: string
          nullable: true
          description: Latest recommendation description (from the first/most recent report)
        recommendationReports:
          type: array
          items:
            $ref: '#/components/schemas/IndexRecommendationReport'

    IndexRecommendationReport:
      type: object
      properties:
        stock:
          type: string
          description: Stock symbol
          example: VNM
        title:
          type: string
          nullable: true
          description: Report title
        source:
          type: string
          nullable: true
          description: Report source, defaults to `VietStock`
          example: VietStock
        recommendation_price:
          type: number
          nullable: true
          description: Recommended entry price (currently always `null`)
        target_price:
          type: number
          nullable: true
          description: Target price
          example: 85000
        publish_date:
          type: string
          format: date-time
          nullable: true
          description: Report publish date
        description:
          type: string
          nullable: true
          description: Report description/summary
        download_url:
          type: string
          nullable: true
          description: URL to download the full report PDF
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true

Notes

• Returns [] (empty array) if no reports are found for the symbol.
• Returns a RecommendationReportResponse object (not an array) when reports exist.
• recommendation is extracted from the first report's description field.
• recommendation_price is currently always null in the implementation.
• Data is synced from Vietstock (vietstock_recommendation_report table).

Silver Chart

GET /market/financial-data/silver-chart

Retrieve silver price chart data over N days.

---

OpenAPI Spec

/market/financial-data/silver-chart:
  get:
    summary: Get silver price chart data
    operationId: getSilverChartData
    tags:
      - Financial Data
    parameters:
      - name: days
        in: query
        required: false
        description: Number of days of history to return. Defaults to `30`.
        schema:
          type: integer
          default: 30
          example: 30
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  description: Chart data points
                  items:
                    type: object

Response Key

data

Notes

• Same behavior and shape as /market/financial-data/gold-chart, but for silver prices.
• If days is not provided or not a valid integer, defaults to 30.

Silver Data

GET /market/financial-data/silver

Retrieve silver price data.

---

OpenAPI Spec

/market/financial-data/silver:
  get:
    summary: Get silver price data
    operationId: getSilverData
    tags:
      - Financial Data
    parameters: []
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/CommodityIndexData'

Response Key

data

Components

Uses the same CommodityIndexData schema as `gold.md`.

Notes

• Same response shape as /market/financial-data/gold.

Stock Realtime

GET /market/stock-realtime

Retrieve realtime stock price data. Accepts exactly one of: symbol, symbols, or exchange.

---

OpenAPI Spec

/market/stock-realtime:
  get:
    summary: Get realtime stock data
    operationId: getStockRealtime
    tags:
      - Stock
    parameters:
      - name: symbol
        in: query
        description: Single stock symbol (e.g. `VNM`). Mutually exclusive with `symbols` and `exchange`.
        required: false
        schema:
          type: string
          example: VNM
      - name: symbols
        in: query
        description: Comma-separated stock symbols (e.g. `VNM,FPT,VIC`). Mutually exclusive with `symbol` and `exchange`.
        required: false
        schema:
          type: string
          example: VNM,FPT,VIC
      - name: exchange
        in: query
        description: Exchange code to get all stocks in an exchange. Mutually exclusive with `symbol` and `symbols`.
        required: false
        schema:
          type: string
          enum: [HOSE, HNX, UPCOM]
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                result:
                  description: >
                    Single `StockRealtime` object when `symbol` is used;
                    array of `StockRealtime` when `symbols` or `exchange` is used.
                  oneOf:
                    - $ref: '#/components/schemas/StockRealtime'
                    - type: array
                      items:
                        $ref: '#/components/schemas/StockRealtime'
      '400':
        description: Invalid request — more than one of `symbol`, `symbols`, `exchange` provided

Response Key

result (not data) — only stock-realtime and index-realtime use result; every other market endpoint uses data.

Components

components:
  schemas:
    StockRealtime:
      type: object
      properties:
        symbol:
          type: string
          example: VNM
        price:
          type: number
          nullable: true
          example: 72500
        volume:
          type: number
          nullable: true
        change:
          type: number
          nullable: true
          description: Price change from reference
        changePercent:
          type: number
          nullable: true
          description: Price change percentage from reference
        ceiling:
          type: number
          nullable: true
          description: Ceiling price
        floor:
          type: number
          nullable: true
          description: Floor price
        reference:
          type: number
          nullable: true
          description: Reference price
        average:
          type: number
          nullable: true
          description: Average (medium) price
        high:
          type: number
          nullable: true
        low:
          type: number
          nullable: true
        open:
          type: number
          nullable: true
        close:
          type: number
          nullable: true
          description: Same as `price`
        buyPrice1:
          type: number
          nullable: true
        buyPrice2:
          type: number
          nullable: true
        buyPrice3:
          type: number
          nullable: true
        buyVol1:
          type: number
          nullable: true
        buyVol2:
          type: number
          nullable: true
        buyVol3:
          type: number
          nullable: true
        sellPrice1:
          type: number
          nullable: true
        sellPrice2:
          type: number
          nullable: true
        sellPrice3:
          type: number
          nullable: true
        sellVol1:
          type: number
          nullable: true
        sellVol2:
          type: number
          nullable: true
        sellVol3:
          type: number
          nullable: true
        totalVolume:
          type: number
          nullable: true
        totalValue:
          type: number
          nullable: true
        foreignBought:
          type: number
          nullable: true
        foreignSold:
          type: number
          nullable: true
        foreignRemain:
          type: number
          nullable: true
        remainBid:
          type: number
          nullable: true
        remainAsk:
          type: number
          nullable: true
        stockType:
          type: string
          enum: [STOCK, ETF, BOND, CW, FUTURES]
          description: Normalized stock type
        exchange:
          type: string
          enum: [HOSE, HNX, UPCOM]
          description: Normalized exchange code
        name:
          type: string
          example: CTCP Sữa Việt Nam
        createdAt:
          type: number
          description: Unix timestamp
        pe:
          type: number
          nullable: true
        pb:
          type: number
          nullable: true
        roe:
          type: number
          nullable: true
        marketCap:
          type: number
          nullable: true
        marketCapCategory:
          type: string
          nullable: true
          enum: [Micro Cap, Small Cap, Mid Cap, Large Cap]
        hasNewestNews:
          type: boolean
        stockSummary:
          type: string
          nullable: true
        additionalInfo:
          type: object
          nullable: true
        symbolStatus:
          type: string
          nullable: true
          description: KRX stocks only
        symbolStatusCode:
          type: string
          nullable: true
          description: KRX stocks only
        floorCode:
          type: string
          nullable: true
          description: KRX stocks only
        influenceScore:
          type: number
          nullable: true  
        outstandingShares:
          type: number
          nullable: true
        

Notes

• close is always equal to price.
• stockType is normalized: ETF symbols are hardcoded to return ETF regardless of DB value.
• exchange is normalized: ETF symbols are hardcoded to return HOSE.
• marketCapCategory is computed from marketCap thresholds: Micro (<100B), Small (<1T), Mid (<10T), Large (>=10T VND).
• symbolStatus, symbolStatusCode, floorCode only present for KRX stocks.

Trading Economics Data

GET /market/financial-data/trading-economics

Retrieve historical economic indicator data by country and category, sourced from Trading Economics.

---

OpenAPI Spec

/market/financial-data/trading-economics:
  get:
    summary: Get Trading Economics indicator data
    operationId: getTradingEconomicsData
    tags:
      - Financial Data
    parameters:
      - name: country
        in: query
        required: true
        description: Country name
        schema:
          type: string
          enum:
            - China
            - Euro Area
            - Japan
            - United States
            - United Kingdom
            - Vietnam
          example: China
      - name: category
        in: query
        required: false
        description: Indicator category filter
        schema:
          type: string
          enum:
            - GDP
            - Labour
            - Prices
            - Money
            - Trade
            - Government
            - Business
            - Consumer
            - Housing
          example: Prices
      - name: year
        in: query
        required: false
        description: Filter by year (2000–2100)
        schema:
          type: integer
          minimum: 2000
          maximum: 2100
          example: 2024
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  example: 200
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/TradingEconomicsData'

Response Key

data

Components

components:
  schemas:
    TradingEconomicsData:
      type: object
      properties:
        indicator:
          type: string
          description: Indicator name
          example: "Inflation Rate"
        country:
          type: string
          description: Country name
          enum:
            - China
            - Euro Area
            - Japan
            - United States
            - United Kingdom
            - Vietnam
          example: "China"
        category:
          type: string
          description: Indicator category
          enum: [GDP, Labour, Prices, Money, Trade, Government, Business, Consumer, Housing]
          example: "Prices"
        lastValue:
          type: number
          nullable: true
          description: Most recent value
          example: 0.1
        previousValue:
          type: number
          nullable: true
          description: Prior period value
          example: -0.1
        year:
          type: integer
          description: Year of the data point
          example: 2024
        month:
          type: integer
          description: Month of the data point (1–12)
          example: 3
        unit:
          type: string
          description: Unit of measurement
          example: "%"

Notes

• country is required. All other params are optional.
• Results are ordered by year DESC, month DESC.
• lastValue and previousValue may be null if data is not yet available.