> ## 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. # Lịch sử giá instrument toàn cầu (index / Mag7 / hàng hoá / forex) > Lịch sử giá đóng cửa của 1 instrument toàn cầu, phân loại qua param `type`. Cover 4 nhóm asset: - **Chỉ số chứng khoán Mỹ**: `SP500`, `DOW_JONES`, `NASDAQ`, `RUSSELL2000`, `VIX`, `DXY`. - **Chỉ số châu Á**: `KOSPI`, `HANGSENG`, `SHANGHAI`, `NIKKEI`. - **Cổ phiếu Mag7**: `APPLE`, `MICROSOFT`, `ALPHABET`, `AMAZON`, `META`, `NVIDIA`, `TESLA`. - **Hàng hoá**: `GOLD`, `SILVER`, `COPPER`, `CRUDE_OIL`, `BRENT_OIL`, `NATURAL_GAS`. - **Tỷ giá ngoại hối**: `EURUSD`, `USDJPY`, `GBPUSD`. Kết quả sort `date DESC` (mới nhất ở đầu mảng). `limit` mặc định `50`, tối đa `500`. ## OpenAPI ````yaml /openapi.yaml get /market/financial-data/market 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/market: get: tags: - Tổng hợp đa loại summary: Lịch sử giá instrument toàn cầu (index / Mag7 / hàng hoá / forex) description: | Lịch sử giá đóng cửa của 1 instrument toàn cầu, phân loại qua param `type`. Cover 4 nhóm asset: - **Chỉ số chứng khoán Mỹ**: `SP500`, `DOW_JONES`, `NASDAQ`, `RUSSELL2000`, `VIX`, `DXY`. - **Chỉ số châu Á**: `KOSPI`, `HANGSENG`, `SHANGHAI`, `NIKKEI`. - **Cổ phiếu Mag7**: `APPLE`, `MICROSOFT`, `ALPHABET`, `AMAZON`, `META`, `NVIDIA`, `TESLA`. - **Hàng hoá**: `GOLD`, `SILVER`, `COPPER`, `CRUDE_OIL`, `BRENT_OIL`, `NATURAL_GAS`. - **Tỷ giá ngoại hối**: `EURUSD`, `USDJPY`, `GBPUSD`. Kết quả sort `date DESC` (mới nhất ở đầu mảng). `limit` mặc định `50`, tối đa `500`. operationId: aggregatedGetGlobalMarket parameters: - name: type in: query required: true description: Mã instrument cần lấy lịch sử. schema: $ref: '#/components/schemas/GlobalMarketDataType' - name: limit in: query required: false description: Số điểm dữ liệu cần lấy (mặc định 50, tối đa 500). schema: type: integer default: 50 minimum: 1 maximum: 500 example: 50 responses: '200': description: >- Trả về `data` mảng các điểm dữ liệu lịch sử của instrument, sort theo `date` giảm dần. content: application/json: schema: $ref: '#/components/schemas/GlobalMarketDataResponse' example: error_code: '0' message: success data: - type: SP500 country: US date: '2026-04-22' year: 2026 month: 4 value: 5234.18 - type: SP500 country: US date: '2026-04-21' year: 2026 month: 4 value: 5210.55 '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/market?type=SP500&limit=50" components: schemas: GlobalMarketDataType: type: string description: | Mã instrument cho dữ liệu thị trường toàn cầu (chỉ số / cổ phiếu Mag7 / hàng hoá / tỷ giá ngoại hối). Dùng cho `/market/financial-data/market`. ### US Indices | Giá trị | Ý nghĩa | |---------|---------| | `SP500` | S&P 500 | | `DOW_JONES` | Dow Jones | | `NASDAQ` | Nasdaq Composite | | `RUSSELL2000` | Russell 2000 | | `VIX` | Chỉ số biến động VIX | | `DXY` | US Dollar Index | ### Asian Indices | Giá trị | Ý nghĩa | |---------|---------| | `KOSPI` | Hàn Quốc — KOSPI | | `HANGSENG` | Hong Kong — Hang Seng | | `SHANGHAI` | Trung Quốc — Shanghai Composite | | `NIKKEI` | Nhật Bản — Nikkei 225 | ### Big-tech stocks (Mag7) | Giá trị | Ý nghĩa | |---------|---------| | `APPLE` | Apple (AAPL) | | `MICROSOFT` | Microsoft (MSFT) | | `ALPHABET` | Alphabet / Google (GOOGL) | | `AMAZON` | Amazon (AMZN) | | `META` | Meta Platforms (META) | | `NVIDIA` | NVIDIA (NVDA) | | `TESLA` | Tesla (TSLA) | ### Commodities | Giá trị | Ý nghĩa | |---------|---------| | `GOLD` | Vàng (USD/oz) | | `SILVER` | Bạc (USD/oz) | | `COPPER` | Đồng | | `CRUDE_OIL` | Dầu thô WTI | | `BRENT_OIL` | Dầu Brent | | `NATURAL_GAS` | Khí tự nhiên | ### Forex | Giá trị | Ý nghĩa | |---------|---------| | `EURUSD` | EUR/USD | | `USDJPY` | USD/JPY | | `GBPUSD` | GBP/USD | enum: - SP500 - DOW_JONES - NASDAQ - RUSSELL2000 - VIX - DXY - KOSPI - HANGSENG - SHANGHAI - NIKKEI - APPLE - MICROSOFT - ALPHABET - AMAZON - META - NVIDIA - TESLA - GOLD - SILVER - COPPER - CRUDE_OIL - BRENT_OIL - NATURAL_GAS - EURUSD - USDJPY - GBPUSD x-enum-varnames: - SP500 - DOW_JONES - NASDAQ - RUSSELL2000 - VIX - DXY - KOSPI - HANGSENG - SHANGHAI - NIKKEI - APPLE - MICROSOFT - ALPHABET - AMAZON - META - NVIDIA - TESLA - GOLD - SILVER - COPPER - CRUDE_OIL - BRENT_OIL - NATURAL_GAS - EURUSD - USDJPY - GBPUSD GlobalMarketDataResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/GlobalMarketDataEntry' 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 GlobalMarketDataEntry: type: object description: >- 1 điểm dữ liệu lịch sử của instrument toàn cầu (index / Mag7 / commodity / forex). properties: type: allOf: - $ref: '#/components/schemas/GlobalMarketDataType' description: Mã instrument. country: allOf: - $ref: '#/components/schemas/GlobalMarketCountry' description: Mã 2 ký tự quốc gia phát hành instrument. date: type: string format: date description: Ngày dữ liệu, format `YYYY-MM-DD`. example: '2026-04-22' year: type: integer description: Năm tách rời từ `date`. example: 2026 month: type: integer minimum: 1 maximum: 12 description: Tháng tách rời từ `date`. example: 4 value: type: number description: Giá trị đóng cửa (close price) của instrument tại `date`. example: 5234.18 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 GlobalMarketCountry: type: string description: | Mã 2 ký tự ISO của quốc gia phát hành instrument toàn cầu trong response của `/market/financial-data/market`. Khác với `EconomicCountry` (dùng full-name) vì endpoint này trả `country` ở dạng mã 2 ký tự. | Giá trị | Ý nghĩa | |---------|---------| | `US` | Mỹ | | `KR` | Hàn Quốc | | `HK` | Hong Kong | | `CN` | Trung Quốc | | `JP` | Nhật Bản | | `UK` | Anh | enum: - US - KR - HK - CN - JP - UK x-enum-varnames: - US - KR - HK - CN - JP - UK 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. ````