> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fhsc.com.vn/llms.txt
> Use this file to discover all available pages before exploring further.

# Tổng hợp mọi loại dữ liệu tài chính

> Endpoint tổng hợp giá vàng, bạc, crypto, lãi suất ngân hàng, tỷ giá USD
và US index trong 1 call duy nhất. Nên dùng các endpoint chuyên biệt nếu
chỉ cần 1 loại dữ liệu.




## OpenAPI

````yaml /openapi.yaml get /market/financial-data
openapi: 3.1.0
info:
  title: Finhay Securities Open API
  version: 0.2.0-preview.2
  description: |
    Đặc tả chính thức của Finhay Securities Open API, dùng chung cho SDK
    codegen, Redoc docs, và (sau này) mock server / contract test.

    ## Authentication — 2 tier

    - **Tier 1 — chỉ cần API key**: các endpoint đọc dữ liệu thị trường
      (`GET /market/**`, `GET /trading/market/**`). Gửi kèm header
      `X-FH-APIKEY` là đủ.
    - **Tier 2 — HMAC signing**: các endpoint liên quan đến account /
      trading / user. Gửi kèm 4 header `X-FH-APIKEY` + `X-FH-TIMESTAMP` +
      `X-FH-NONCE` + `X-FH-SIGNATURE`; thêm `X-FH-BODYHASH` khi request có
      body. Chi tiết thuật toán xem extension `x-finhay-signing` ở root
      spec hoặc phần README.

    ## Bootstrap flow

    Gọi 2 endpoint tag **Khởi tạo** (`GET /users/v1/users/me` và
    `GET /users/v1/users/{userId}/sub-accounts`) **1 lần khi khởi tạo
    client** để lấy thông tin `user_id` và `subAccountId`. Mọi endpoint thuộc
    tag **Tổng tài sản / Tiểu khoản / Danh mục đầu tư / Sổ lệnh / Lãi-lỗ /
    Quyền cổ đông** đều cần 2 giá trị này để truyền vào path parameter.
  contact: {}
servers:
  - url: https://open-api.fhsc.com.vn
    description: Production
security:
  - FinhayApiKey: []
tags:
  - name: Khởi tạo
    description: >-
      Khởi tạo client — lấy `user_id` và `subAccountId`. Gọi 1 lần khi khởi tạo
      SDK rồi cache lại.
  - name: Dữ liệu giao dịch
    description: >-
      Giá stock realtime và lịch sử OHLCV (dạng columnar, phục vụ charting /
      time-series).
  - name: Phân tích cơ bản
    description: >-
      Chỉ số tài chính cơ bản của doanh nghiệp — chỉ số tổng quan, phân tích
      theo kỳ và báo cáo tài chính chuẩn (income statement / balance sheet /
      cash flow).
  - name: Tin tức-sự kiện
    description: >-
      Sự kiện doanh nghiệp (cổ tức, quyền mua, ĐHCĐ, …), tin tức stock, tin tức
      tài chính toàn cầu (forex / commodities / economic-indicators /
      stock-market / cryptocurrency) và báo cáo khuyến nghị từ analyst.
  - name: Kinh tế vĩ mô
    description: >-
      Chỉ số kinh tế vĩ mô (CPI, PMI, PCE, GDP, …) và lãi suất tiền gửi ngân
      hàng.
  - name: Hàng hoá
    description: >-
      Hàng hoá và tài sản thay thế — vàng, bạc (spot / chart / theo nhà cung
      cấp) và crypto trending.
  - name: Tổng hợp đa loại
    description: >-
      Endpoint composite tổng hợp cross-domain (vàng / bạc / crypto / FX / lãi
      suất / US index) trong 1 call. Nên dùng endpoint chuyên biệt nếu chỉ cần 1
      loại.
  - name: Quỹ mở
    description: >-
      Quỹ mở (open-ended funds) — danh sách quỹ, công ty quản lý, NAV history,
      holdings, ranking và benchmark cross-fund.
  - name: Tổng tài sản
    description: >-
      Tổng quan tài sản cấp user — cross-product (stock, fund, bond, hay0) kèm
      cash, debt, PnL.
  - name: Tiểu khoản
    description: Thông tin tiểu khoản — số dư, margin, dư nợ và ngân hàng liên kết.
  - name: Danh mục đầu tư
    description: Danh mục stock đang nắm giữ kèm giá realtime và PnL theo vị thế.
  - name: Sổ lệnh
    description: >-
      Quản lý lệnh — sổ lệnh trong ngày, danh sách đầy đủ hoặc chi tiết theo
      `orderId`.
  - name: Lãi-lỗ
    description: PnL và analytics cá nhân — lãi / lỗ trong ngày tổng hợp theo user.
  - name: Quyền cổ đông
    description: Quyền cổ đông (cổ tức, quyền mua, bỏ phiếu, …) của tiểu khoản.
  - name: Phiên giao dịch
    description: >-
      Hạ tầng trading — trạng thái phiên giao dịch và order type khả dụng của
      mỗi exchange.
  - name: Thực thi lệnh
    description: |
      ⚠️ Nhóm endpoint này đang ở giai đoạn **preview**.

      Đặt / sửa / huỷ lệnh trên sàn — write operation nhạy cảm, yêu cầu
      Tier 2 HMAC đầy đủ + `X-FH-BODYHASH` + `X-FH-2FA-TOKEN` (daily 2FA
      session).
paths:
  /market/financial-data:
    get:
      tags:
        - Tổng hợp đa loại
      summary: Tổng hợp mọi loại dữ liệu tài chính
      description: |
        Endpoint tổng hợp giá vàng, bạc, crypto, lãi suất ngân hàng, tỷ giá USD
        và US index trong 1 call duy nhất. Nên dùng các endpoint chuyên biệt nếu
        chỉ cần 1 loại dữ liệu.
      operationId: aggregatedGetFinancialData
      responses:
        '200':
          description: Thành công.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialDataResponse'
              example:
                error_code: '0'
                message: success
                data:
                  - financial_type: GOLD
                    name: Giá vàng
                    values:
                      - index: SJC_GOLD_BAR
                        name: Vàng miếng SJC
                        description: 'Đơn vị: 1.000đ/chỉ'
                        icon_url: >-
                          https://cdn1.finhay.com.vn/vnsc-prod/1739437064948-gold.png
                        value_type: BUY_SELL
                        buy_value: 16750
                        sell_value: 17000
                      - index: PNJ_9999_GOLD_RING
                        name: Vàng nhẫn PNJ
                        description: 'Đơn vị: 1.000đ/chỉ'
                        icon_url: >-
                          https://cdn1.finhay.com.vn/vnsc-prod/1739437064948-gold.png
                        value_type: BUY_SELL
                        buy_value: 16670
                        sell_value: 16970
                    last_updated: '2026-04-22 23:09:12'
                  - financial_type: USD_EXCHANGE_RATE
                    name: Tỷ giá USD
                    values:
                      - index: USD_VND_EXCHANGE_RATE
                        name: Vietcombank
                        description: Giao dịch tiền mặt
                        icon_url: >-
                          https://cdn1.finhay.com.vn/vnsc-prod/1739846863045-vcb.png
                        value_type: BUY_SELL
                        buy_value: 26198
                        sell_value: 26448
                      - index: BLACK_MARKET_USD_VND_EXCHANGE_RATE
                        name: Chợ đen
                        description: Giao dịch tiền mặt
                        icon_url: >-
                          https://cdn1.finhay.com.vn/vnsc-prod/1739846837853-blackmarket.png
                        value_type: BUY_SELL
                        buy_value: 26484
                        sell_value: 26584
                    last_updated: '2025-09-23 16:00:03'
                  - financial_type: CRYPTO
                    name: Tài sản số
                    values:
                      - index: BITCOIN
                        name: BTC
                        description: ''
                        icon_url: >-
                          https://cdn1.finhay.com.vn/vnsc-prod/1739758983132-btc.png
                        value_type: SINGLE
                        value: 79283.83
                        change: 3324.45
                        change_percent: 4.377
                    last_updated: '2026-04-22 23:10:00'
                  - financial_type: US_INDEX
                    name: Chứng khoán Mỹ
                    values:
                      - index: SP_500
                        name: S&P 500
                        description: ''
                        icon_url: >-
                          https://cdn1.finhay.com.vn/vnsc-prod/1739774157905-sp500.png
                        value_type: SINGLE
                        value: 7124
                        change: 59.99
                        change_percent: 0.85
                      - index: NASDAQ
                        name: NASDAQ
                        description: ''
                        icon_url: >-
                          https://cdn1.finhay.com.vn/vnsc-prod/1739774139495-nasdaq.png
                        value_type: SINGLE
                        value: 24574.612
                        change: 314.647
                        change_percent: 1.3
                    last_updated: '2026-04-22 23:10:00'
                traceId: 5ecb0251-aa07-421c-876c-89d6a7c67461
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl -H "X-FH-APIKEY: $FINHAY_API_KEY" \
              "https://open-api.fhsc.com.vn/market/financial-data"
components:
  schemas:
    FinancialDataResponse:
      allOf:
        - $ref: '#/components/schemas/EnvelopeBase'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/FinancialData'
            traceId:
              type: string
              format: uuid
              description: Request trace ID do server sinh, dùng để debug và đối chiếu log.
              example: 5ecb0251-aa07-421c-876c-89d6a7c67461
    EnvelopeBase:
      type: object
      description: |
        Các field chung của envelope trong mọi response của Finhay API.

        - `error_code` là `"0"` (string) khi thành công, mã khác `"0"` khi lỗi.
        - `message` là thông điệp ngắn từ server.
      properties:
        error_code:
          type: string
          description: '`"0"` khi thành công, khác `"0"` khi lỗi.'
          example: '0'
        message:
          type: string
          description: Thông điệp trạng thái dễ đọc.
          example: success
    FinancialData:
      type: object
      description: |
        Row dữ liệu tài chính tổng hợp — bao gồm vàng, bạc, crypto, lãi suất
        ngân hàng, tỷ giá USD và US index.

        `financial_type` là loại; mỗi row trong `values` được phân biệt qua
        `value_type` (`BUY_SELL` → `FinancialDataBuySellValue`, `SINGLE` →
        `FinancialDataSingleValue`).
      properties:
        financial_type:
          type: string
          description: Category of financial data.
          enum:
            - GOLD
            - SILVER
            - CRYPTO
            - BANK_INTEREST_RATE
            - USD_EXCHANGE_RATE
            - US_INDEX
          x-enum-varnames:
            - GOLD
            - SILVER
            - CRYPTO
            - BANK_INTEREST_RATE
            - USD_EXCHANGE_RATE
            - US_INDEX
        name:
          type: string
          description: Display name of the category.
          example: Giá vàng
        values:
          type: array
          description: >
            Per-row data. Discriminated by `value_type`:

            `BUY_SELL` rows carry `buy_value` / `sell_value`; `SINGLE` rows
            carry

            `value` / `change` / `change_percent`.
          items:
            oneOf:
              - $ref: '#/components/schemas/FinancialDataBuySellValue'
              - $ref: '#/components/schemas/FinancialDataSingleValue'
            discriminator:
              propertyName: value_type
        last_updated:
          type: string
          description: |
            Last-update timestamp in `YYYY-MM-DD HH:MM:SS` format (local time,
            **not ISO 8601**).
          example: '2026-04-22 23:09:12'
      required:
        - financial_type
        - values
    ErrorBody:
      type: object
      description: Body của response khi 4xx / 5xx.
      properties:
        error_code:
          type: string
          description: >-
            Mã lỗi khác `"0"` (ví dụ `AUTH_SIGNATURE_INVALID`,
            `RATE_LIMIT_EXCEEDED`, …).
          example: '400'
        message:
          type: string
          description: Thông điệp lỗi (tiếng Anh, từ server).
          example: Invalid parameter
      required:
        - error_code
        - message
    FinancialDataBuySellValue:
      type: object
      description: |
        Row có cặp giá mua / giá bán — dùng cho vàng, bạc và tỷ giá USD tiền
        mặt. Nhận biết bằng `value_type: BUY_SELL`.
      properties:
        index:
          type: string
          description: >-
            Stable identifier for the row (e.g. `SJC_GOLD_BAR`,
            `USD_VND_EXCHANGE_RATE`).
          example: SJC_GOLD_BAR
        name:
          type: string
          description: Display name.
          example: Vàng miếng SJC
        description:
          type: string
          description: Short descriptive text. May be empty.
          example: 'Đơn vị: 1.000đ/chỉ'
        icon_url:
          type: string
          description: Icon URL.
          example: https://cdn1.finhay.com.vn/vnsc-prod/1739437064948-gold.png
        value_type:
          type: string
          description: Discriminator — always `BUY_SELL` for this shape.
          enum:
            - BUY_SELL
          x-enum-varnames:
            - BUY_SELL
        buy_value:
          type: number
          description: Buy price.
          example: 16750
        sell_value:
          type: number
          description: Sell price.
          example: 17000
      required:
        - index
        - name
        - value_type
        - buy_value
        - sell_value
    FinancialDataSingleValue:
      type: object
      description: |
        Row có 1 giá trị đơn — dùng cho crypto spot và US stock indices. Nhận
        biết bằng `value_type: SINGLE`.
      properties:
        index:
          type: string
          description: Stable identifier for the row (e.g. `BITCOIN`, `SP_500`).
          example: BITCOIN
        name:
          type: string
          description: Display name.
          example: BTC
        description:
          type: string
          description: Short descriptive text. May be empty.
          example: ''
        icon_url:
          type: string
          description: Icon URL.
          example: https://cdn1.finhay.com.vn/vnsc-prod/1739758983132-btc.png
        value_type:
          type: string
          description: Discriminator — always `SINGLE` for this shape.
          enum:
            - SINGLE
          x-enum-varnames:
            - SINGLE
        value:
          type: number
          description: Current spot / index level.
          example: 79283.83
        change:
          type: number
          description: Absolute change vs previous close.
          example: 3324.45
        change_percent:
          type: number
          description: Percentage change vs previous close.
          example: 4.377
      required:
        - index
        - name
        - value_type
        - value
  responses:
    BadRequest:
      description: Request không hợp lệ — thiếu hoặc sai tham số.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            error_code: '400'
            message: Invalid parameter
    Unauthorized:
      description: Không xác thực — thiếu, sai hoặc không hợp lệ chữ ký / API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            error_code: '401'
            message: Invalid signature
    RateLimited:
      description: >-
        Vượt giới hạn rate limit. Chờ đến thời điểm `X-RateLimit-Reset` rồi thử
        lại.
      headers:
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            error_code: '429'
            message: Too many requests
    InternalError:
      description: Lỗi server nội bộ.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            error_code: '500'
            message: Internal server error
  headers:
    XRateLimitReset:
      description: |
        Unix timestamp (giây) — thời điểm window rate limit reset. Client nhận
        `429 Too Many Requests` nên chờ đến thời điểm này rồi retry.
      schema:
        type: integer
        format: int64
        example: 1713441600
  securitySchemes:
    FinhayApiKey:
      type: apiKey
      in: header
      name: X-FH-APIKEY
      description: >
        API key dài hạn của client. Cấu hình 1 lần lúc khởi tạo; có thể wire
        thẳng

        vào static setter của SDK tự-gen. Đi kèm với `FINHAY_API_SECRET` —
        secret

        này chỉ dùng ở phía client để tính `X-FH-SIGNATURE`, **không** bao giờ

        gửi qua mạng.

````