> ## 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. # Giá stock realtime > Giá realtime của stock kèm các chỉ số cơ bản — giá hiện tại, % thay đổi, trần / sàn / tham chiếu, OHLC trong phiên, khối lượng / giá trị giao dịch, cap, P/E, P/B, ROE. **Phải truyền đúng 1** trong 3 query (mutually exclusive): `symbol` (1 mã), `symbols` (danh sách mã, comma-separated, tối đa 50 mã), hoặc `exchange` (toàn bộ stock thuộc 1 sàn). Truyền >1 sẽ bị reject với 400. Shape response thay đổi theo input — `symbol` → 1 object trong `result`; `symbols` / `exchange` → array trong `result`. Client cần xử lý cả 2 trường hợp. ## OpenAPI ````yaml /openapi.yaml get /market/stock-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/stock-realtime: get: tags: - Dữ liệu giao dịch summary: Giá stock realtime description: | Giá realtime của stock kèm các chỉ số cơ bản — giá hiện tại, % thay đổi, trần / sàn / tham chiếu, OHLC trong phiên, khối lượng / giá trị giao dịch, cap, P/E, P/B, ROE. **Phải truyền đúng 1** trong 3 query (mutually exclusive): `symbol` (1 mã), `symbols` (danh sách mã, comma-separated, tối đa 50 mã), hoặc `exchange` (toàn bộ stock thuộc 1 sàn). Truyền >1 sẽ bị reject với 400. Shape response thay đổi theo input — `symbol` → 1 object trong `result`; `symbols` / `exchange` → array trong `result`. Client cần xử lý cả 2 trường hợp. operationId: marketDataGetStockRealtime parameters: - name: symbol in: query required: false description: Mã stock đơn lẻ. Loại trừ lẫn với `symbols` và `exchange`. schema: type: string example: VNM - name: symbols in: query required: false description: >- Danh sách mã stock, phân tách bằng dấu phẩy. Loại trừ lẫn với `symbol` và `exchange`. schema: type: string example: VNM,FPT,VIC - name: exchange in: query required: false description: >- Mã exchange (trả về toàn bộ stock thuộc exchange này). Loại trừ lẫn với `symbol` và `symbols`. schema: $ref: '#/components/schemas/Exchange' responses: '200': description: >- Trả về snapshot giá realtime trong `result`. Là 1 object khi truyền `symbol`; là array khi truyền `symbols` / `exchange`. content: application/json: schema: $ref: '#/components/schemas/StockRealtimeResponse' example: error_code: '0' message: success result: symbol: VNM price: 72500 change: 500 changePercent: 0.69 ceiling: 77500 floor: 67500 reference: 72000 open: 72000 high: 73000 low: 71500 close: 72500 totalVolume: 1500000 totalValue: 108750000000 stockType: STOCK exchange: HOSE name: CTCP Sữa Việt Nam createdAt: 1713441600 pe: 16.8 pb: 4.2 roe: 0.25 marketCap: 150000000000000 marketCapCategory: Large Cap hasNewestNews: false '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/stock-realtime?symbol=VNM" components: schemas: Exchange: type: string description: | Mã sàn chứng khoán Việt Nam. | Giá trị | Ý nghĩa | |---------|---------| | `HOSE` | Sở Giao dịch Chứng khoán TP. HCM | | `HNX` | Sở Giao dịch Chứng khoán Hà Nội | | `UPCOM` | Thị trường công ty đại chúng chưa niêm yết | | `HCX` | Sàn hàng hoá TP. HCM (phái sinh) | enum: - HOSE - HNX - UPCOM - HCX x-enum-varnames: - HOSE - HNX - UPCOM - HCX StockRealtimeResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - result properties: 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' 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 StockRealtime: type: object description: | Giá realtime của 1 mã stock. Lưu ý: - `close` luôn bằng `price`. - `stockType` được chuẩn hoá: ETF bị hardcode thành `ETF`; `exchange` bị hardcode thành `HOSE` cho ETF bất kể giá trị trong DB. - `marketCapCategory` được tính từ `marketCap`: Micro (<100 tỷ), Small (<1 nghìn tỷ), Mid (<10 nghìn tỷ), Large (≥10 nghìn tỷ VND). - `symbolStatus`, `symbolStatusCode`, `floorCode` chỉ set cho stock KRX. properties: symbol: type: string example: VNM price: type: - number - 'null' example: 72500 volume: type: - number - 'null' change: type: - number - 'null' description: Price change from reference. changePercent: type: - number - 'null' description: Price change percentage from reference. ceiling: type: - number - 'null' description: Ceiling price. floor: type: - number - 'null' description: Floor price. reference: type: - number - 'null' description: Reference price. average: type: - number - 'null' description: Average (medium) price. high: type: - number - 'null' low: type: - number - 'null' open: type: - number - 'null' close: type: - number - 'null' description: Same as `price`. buyPrice1: type: - number - 'null' buyPrice2: type: - number - 'null' buyPrice3: type: - number - 'null' buyVol1: type: - number - 'null' buyVol2: type: - number - 'null' buyVol3: type: - number - 'null' sellPrice1: type: - number - 'null' sellPrice2: type: - number - 'null' sellPrice3: type: - number - 'null' sellVol1: type: - number - 'null' sellVol2: type: - number - 'null' sellVol3: type: - number - 'null' totalVolume: type: - number - 'null' totalValue: type: - number - 'null' foreignBought: type: - number - 'null' foreignSold: type: - number - 'null' foreignRemain: type: - number - 'null' remainBid: type: - number - 'null' remainAsk: type: - number - 'null' stockType: allOf: - $ref: '#/components/schemas/StockType' description: Normalized instrument type. exchange: allOf: - $ref: '#/components/schemas/Exchange' description: Normalized exchange code. name: type: string example: CTCP Sữa Việt Nam createdAt: type: number description: Unix timestamp (seconds). pe: type: - number - 'null' pb: type: - number - 'null' roe: type: - number - 'null' marketCap: type: - number - 'null' marketCapCategory: type: - string - 'null' enum: - Micro Cap - Small Cap - Mid Cap - Large Cap hasNewestNews: type: boolean stockSummary: type: - string - 'null' additionalInfo: type: - object - 'null' description: | Object chứa các thông tin bổ sung không có cấu trúc cố định. Shape thay đổi theo symbol và nguồn dữ liệu. symbolStatus: type: - string - 'null' description: Chỉ áp dụng cho stock niêm yết tại KRX. symbolStatusCode: type: - string - 'null' description: Chỉ áp dụng cho stock niêm yết tại KRX. floorCode: type: - string - 'null' description: KRX stocks only. influenceScore: type: - number - 'null' outstandingShares: type: - number - 'null' 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 StockType: type: string description: | Phân loại công cụ tài chính. | Giá trị | Ý nghĩa | |---------|---------| | `STOCK` | Cổ phiếu thường | | `ETF` | Quỹ ETF | | `BOND` | Trái phiếu | | `FUND_CERTIFICATE` | Chứng chỉ quỹ (mở / đóng) | | `WARRANT` | Chứng quyền có bảo đảm | | `CW` | Chứng quyền có bảo đảm (alias dùng trên realtime) | | `FUTURES` | Hợp đồng tương lai phái sinh | enum: - STOCK - ETF - BOND - FUND_CERTIFICATE - WARRANT - CW - FUTURES x-enum-varnames: - STOCK - ETF - BOND - FUND_CERTIFICATE - WARRANT - CW - FUTURES 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. ````