> ## 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. # Chỉ số thị trường realtime > Giá trị realtime của 1 hoặc nhiều chỉ số thị trường chứng khoán Việt Nam (VNINDEX, HNXINDEX, UPCOMINDEX, VN30, HNX30) kèm thay đổi điểm, % thay đổi, tham chiếu và tổng khối lượng khớp. Truyền nhiều mã bằng cách phân tách dấu phẩy (`?index=VNINDEX,HNX30`). `result` **luôn là array** — 1 phần tử cho mỗi mã có dữ liệu; truyền mã đơn vẫn trả array 1 phần tử. ## OpenAPI ````yaml /openapi.yaml get /market/index-realtime openapi: 3.1.0 info: title: Finhay Securities Open API version: 0.2.0-preview.3 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/index-realtime: get: tags: - Dữ liệu giao dịch summary: Chỉ số thị trường realtime description: | Giá trị realtime của 1 hoặc nhiều chỉ số thị trường chứng khoán Việt Nam (VNINDEX, HNXINDEX, UPCOMINDEX, VN30, HNX30) kèm thay đổi điểm, % thay đổi, tham chiếu và tổng khối lượng khớp. Truyền nhiều mã bằng cách phân tách dấu phẩy (`?index=VNINDEX,HNX30`). `result` **luôn là array** — 1 phần tử cho mỗi mã có dữ liệu; truyền mã đơn vẫn trả array 1 phần tử. operationId: marketDataGetIndexRealtime parameters: - name: index in: query required: true description: | Mã chỉ số cần lấy. Truyền nhiều mã phân tách bằng dấu phẩy — ví dụ `VNINDEX,HNX30`. style: form explode: false schema: type: array minItems: 1 items: $ref: '#/components/schemas/MarketIndex' example: - VNINDEX responses: '200': description: Trả về mảng snapshot chỉ số trong `result` (1 phần tử / mã). content: application/json: schema: $ref: '#/components/schemas/IndexRealtimeResponse' example: error_code: '0' message: success result: - index: VNINDEX indexValue: 1792.6 allQuantity: 248009131 change: 2.07 changePercent: 0.12 reference: 1790.53 allValue: 6543210000000 advances: 245 declines: 168 nochanges: 52 ceiling: 9 floor: 5 values: - 1790.53 - 1791.84 - 1792.6 volumes: - 85230000 - 167450000 - 248009131 times: - 1780300800000 - 1780304400000 - 1780308000000 advancesArr: - 180 - 220 - 245 declinesArr: - 210 - 185 - 168 nochangesArr: - 60 - 58 - 52 ceilings: - 4 - 7 - 9 floors: - 9 - 7 - 5 sessionInExchange: PROGRESS name: VNINDEX '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/index-realtime?index=VNINDEX" components: schemas: MarketIndex: type: string description: | Mã chỉ số thị trường chứng khoán Việt Nam. | Giá trị | Ý nghĩa | |---------|---------| | `VNINDEX` | Chỉ số tổng hợp sàn HOSE | | `HNXINDEX` | Chỉ số tổng hợp sàn HNX | | `UPCOMINDEX` | Chỉ số thị trường UPCoM | | `VN30` | Rổ 30 mã vốn hoá lớn & thanh khoản cao trên HOSE | | `HNX30` | Rổ 30 mã vốn hoá lớn & thanh khoản cao trên HNX | enum: - VNINDEX - HNXINDEX - UPCOMINDEX - VN30 - HNX30 x-enum-varnames: - VNINDEX - HNXINDEX - UPCOMINDEX - VN30 - HNX30 IndexRealtimeResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - result properties: result: type: array description: > Mảng snapshot chỉ số — **1 phần tử cho mỗi mã** truyền vào `index`. Mã không hợp lệ / không có dữ liệu bị bỏ qua (không sinh lỗi), nên mảng có thể ngắn hơn số mã yêu cầu, hoặc rỗng. items: $ref: '#/components/schemas/IndexRealtime' 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 IndexRealtime: type: object description: | Snapshot realtime của 1 chỉ số thị trường (VNINDEX, HNX30, …). Lưu ý: - `change` / `reference` / `indexValue` tính theo **điểm chỉ số** (không phải VND). - `changePercent` đã ở **đơn vị phần trăm** (vd `0.12` nghĩa là 0.12%), không phải tỉ lệ 0–1. - Các field breadth (`advances` / `declines` / …) và chuỗi intraday (`values` / `volumes` / `times`) **chỉ trả về ở chế độ đầy đủ**; nhóm `*Arr` / `ceilings` / `floors` chỉ áp dụng cho index trên hệ thống KRX. Tuỳ phiên / sàn, một số field có thể vắng mặt. required: - index - indexValue - change - changePercent - reference properties: index: type: string description: Mã chỉ số được trả về (echo lại giá trị `index` đã truyền). example: VNINDEX indexValue: type: number description: Giá trị điểm hiện tại của chỉ số. example: 1792.6 change: type: number description: Thay đổi điểm so với `reference`. example: 2.07 changePercent: type: number description: '% thay đổi so với `reference` (đơn vị phần trăm).' example: 0.12 reference: type: number description: Giá trị tham chiếu — điểm đóng cửa phiên giao dịch trước. example: 1790.53 allQuantity: type: integer format: int64 description: Tổng khối lượng khớp toàn thị trường của chỉ số (số cổ phiếu). example: 248009131 allValue: type: number description: Tổng giá trị giao dịch khớp toàn thị trường của chỉ số (VND). advances: type: integer description: Số mã tăng giá. declines: type: integer description: Số mã giảm giá. nochanges: type: integer description: Số mã đứng giá. ceiling: type: integer description: Số mã tăng trần. floor: type: integer description: Số mã giảm sàn. values: type: array description: Chuỗi điểm chỉ số trong phiên (khớp vị trí với `times` / `volumes`). items: type: number volumes: type: array description: >- Chuỗi khối lượng khớp trong phiên (khớp vị trí với `times` / `values`). items: type: number times: type: array description: Chuỗi mốc thời gian trong phiên — Unix timestamp (mili-giây). items: type: integer format: int64 advancesArr: type: array description: >- Chuỗi số mã tăng giá theo thời gian trong phiên. Chỉ áp dụng cho index KRX. items: type: integer declinesArr: type: array description: >- Chuỗi số mã giảm giá theo thời gian trong phiên. Chỉ áp dụng cho index KRX. items: type: integer nochangesArr: type: array description: >- Chuỗi số mã đứng giá theo thời gian trong phiên. Chỉ áp dụng cho index KRX. items: type: integer ceilings: type: array description: >- Chuỗi số mã tăng trần theo thời gian trong phiên. Chỉ áp dụng cho index KRX. items: type: integer floors: type: array description: >- Chuỗi số mã giảm sàn theo thời gian trong phiên. Chỉ áp dụng cho index KRX. items: type: integer sessionInExchange: type: string description: >- Trạng thái phiên giao dịch hiện tại của sàn (tham chiếu giá trị `ExchangeSession`). name: type: string description: Tên chỉ số (hiện trùng với `index`). example: VNINDEX 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 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. ````