Phân tích theo chỉ số — /market/indices/** (5 endpoint)
GET /market/indices— bảng so sánh các chỉ số: điểm, thay đổi %, vốn hoá, độ rộng, dòng tiền; hỗ trợwindow,sort,fields, filter<field>_gt/<field>_lt, phân trang./{symbol}/breadth,/{symbol}/constituents,/{symbol}/trading/foreignvà/{symbol}/trading/foreign/historycho VNINDEX, HNXINDEX, UPCOMINDEX, VN30, HNX30.
Phân tích theo ngành — /market/sectors/** (7 endpoint)
GET /market/sectors— bảng so sánh ngành theo cây ICB (level,parent), cũng là nơi traslughợp lệ./{slug}/breadth,/{slug}/constituents,/{slug}/performance(+/history),/{slug}/trading/foreign(+/history).
Theo mã cổ phiếu
GET /market/stocks/{symbol}/events— sự kiện quyền (cổ tức tiền / cổ phiếu, phát hành thêm, ĐHCĐ, chuyển đổi trái phiếu, …);detailslàoneOftheoevent_type.GET /market/stocks/{symbol}/trading/insider— giao dịch nội bộ / cổ đông lớn, lọc theosidevàstatus.GET /market/stocks/{symbol}/analyst-reports— báo cáo phân tích của CTCK, lọc theosource,recommendation, khoảng ngày phát hành.GET /market/quotes/stocks/{symbol}/order-book/history— lịch sử sổ lệnh trong phiên.
Thay đổi khác
GET /market/company-financial/analysisvàGET /market/v2/financial-statement/statementthêmpage(lùi về quá khứ) vàyear(lọc một năm).GET /market/calendar:actual/previous/consensus/forecastgiờ là chuỗi số đã bỏ ký hiệu đơn vị ("5.50"thay vì"5.50%"), đơn vị tách ra field mớiunit(Percent,Thousand,USD Billion, …).
Bảng giá thống nhất — /market/quotes/** (30 endpoint)
- Một mô hình chung cho 8 loại tài sản:
stocks,indices,forex,cryptos,commodities,funds,bonds,etfs. Mỗi loại có catalog (/market/quotes/{loại}), quote realtime (/{symbol}) và lịch sử (/{symbol}/history);stocks/bonds/etfsthêm/order-book. - Hàng hoá có thêm 3 endpoint giá theo nhà cung cấp
(
/commodities/{symbol}/dealer-products/**) — thay chogold-providers/metal-providerscũ. symbolkhông phân biệt hoa thường;from/tocủa history là Unix timestamp tính bằng giây.
Screener và thống kê giao dịch — /market/stocks/** (15 endpoint)
GET /market/stocks— screener toàn thị trường: filter phạm vi (exchange/index/sector), filter số dạng<field>_gt/<field>_lt,sort,windowhoặcdate,fields, phân trang.- Thống kê theo mã: khối ngoại, tự doanh, thống kê lệnh mua / bán, room
ngoại và chỉ báo kỹ thuật — mỗi loại có bản snapshot và bản
/history. - Hồ sơ doanh nghiệp:
/profile,/listing,/ownership(tagPhân tích cơ bản).
Tin tức và vĩ mô
GET /market/market-news+/market/market-news/{id}— tin tức thị trường phân trang, lọc theotopic(kết hợpsymbolkhitopic=stock). Thay cho/market/newsvàfinancial-data/global-news.GET /market/macro/indicators+/{indicator}— catalog chỉ tiêu vĩ mô và chuỗi giá trị theo kỳ (yyyy,yyyy-Qn,yyyy-MM). Thay chofinancial-data/macrovàfinancial-data/trading-economics.GET /market/calendar— lịch sự kiện kinh tế của 6 nền kinh tế, thay chofinancial-data/economic-calendar-events.GET /market/financial-data/bank-interest-ratesgiữ nguyên path nhưng đổi shape:data.bank_interest_rateslà mảng ngân hàng, mỗi ngân hàng có mảngratestheo kỳ hạn.
Taxonomy
- 4 tag cũ (
Dữ liệu giao dịch,Hàng hoá,Tổng hợp đa loại,Quỹ mở) gộp thành 1 tagBảng giá thị trường. Nhóm quỹ mở giờ nằm trong/market/quotes/funds/**. - Nhóm
/market/**trả payload trongdata; nhóm tài khoản / giao dịch giữ nguyênresult. - Endpoint tài khoản, danh mục, sổ lệnh, PnL, quyền cổ đông, phiên giao dịch và thực thi lệnh không đổi.
Thay đổi
- Thêm header parameter bắt buộc
device-idchoordersPlace/ordersModify/ordersCancel— định danh thiết bị đặt lệnh do client cung cấp mỗi request (phục vụ tuân thủ quy định giao dịch), không lấy từ token / phiên xác thực. - Parameter dùng chung mới
DeviceId(components/parameters/DeviceId.yaml). - Không đổi cơ chế ký (
x-finhay-signinggiữ nguyên) —device_idchỉ để lưu vết, không nằm trong chữ ký.
Bổ sung 1 endpoint dữ liệu thị trường (tổng 50) dưới tag
Dữ liệu giao dịch.Endpoint mới
GET /market/index-realtime— giá trị realtime của chỉ số thị trường chứng khoán Việt Nam (VNINDEX,HNXINDEX,UPCOMINDEX,VN30,HNX30). Tier 1 — chỉ cầnX-FH-APIKEY. Truyền nhiều mã phân tách dấu phẩy (?index=VNINDEX,HNX30);resultluôn là array, 1 phần tử cho mỗi mã có dữ liệu.
Schema
- Schema mới
IndexRealtime— snapshot 1 chỉ số: điểm hiện tại (indexValue), thay đổi (change/changePercent), tham chiếu (reference), khối lượng / giá trị khớp (allQuantity/allValue), breadth (số mã tăng / giảm / đứng giá / trần / sàn) và chuỗi intraday (values/volumes/times). Nhóm*Arr/ceilings/floorschỉ áp dụng cho index KRX. - Enum mới
MarketIndex— 5 mã chỉ số thị trường Việt Nam.
Bổ sung 3 endpoint write đầu tiên dưới tag
Thực thi lệnh —
đang ở giai đoạn preview. Bump version 0.1.0 → 0.2.0-preview.1.Endpoint mới (preview)
POST /trading/oa/sub-accounts/{subAccountId}/orders— Đặt lệnh.PUT /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}— Sửa lệnh.DELETE /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}— Huỷ lệnh (DELETE có body — contract upstream).
Security mở rộng
- Security scheme mới
FinhayTwoFactor(X-FH-2FA-TOKEN) — daily JWT session cấp sau khi user xác thực qua OTP. - Response component mới
Forbidden(HTTP 403) — bao gồm các mãOTP_SESSION_REQUIRED|EXPIRED|INVALID|REVOKED. x-finhay-signing.appliesTo.twoFactorliệt kê 3 route preview cần 2FA token.
Cleanup tài liệu
- Fix drift tên tag trong
info.descriptioncủa root spec và 2 README:Bootstrap→Khởi tạo;Account / Portfolio / Orders / PnL / Corporate Actions→ tag tiếng Việt thực tế. - Đồng bộ danh sách
API_KEY_ONLYpatterns trong Mintlifyauthentication.mdx(TypeScript + Python middleware) vàintroduction.mdxvớix-finhay-signing.appliesTo.apiKeyOnly— thêm/trading/securities/**và/fund-trading/public/**.
Bổ sung 16 endpoint mới (tổng 46), giới thiệu nhóm chức năng mới
Quỹ mở dưới tab dữ liệu thị trường.
Endpoint mới
- Quỹ mở (14, tag
Quỹ mở): danh sách quỹ + công ty quản lý, NAV history + benchmark, holdings (portfolio / asset-allocation / sector-allocation / suggestions), ranking (top AUM / investor / fund-flow / holding-symbols), benchmark cross-fund (growth / nav / operation). Prefix path/fund-trading/public/**— Tier 1, chỉ cầnX-FH-APIKEY. - Tin tức tài chính toàn cầu (2, tag
Tin tức-sự kiện):/market/financial-data/global-news(paginated list lọc theo category) +/market/financial-data/global-news/{id}(chi tiết bài báo). Tier 1.
Description / schema tweaks
ProductsSummary.bond(/users/v3/users/{userId}/assets/summary): field này là sản phẩm HayBond, không phải trái phiếu doanh nghiệp / chính phủ thông thường — clarify trong description.assetGetSummarydescription: bổ sung guidance combine với/trading/accounts/{subAccountId}/summaryđể có NAV chính xác nhất.
Path version revert
/users/v4/users/{userId}/assets/summary→/users/v3/users/{userId}/assets/summary(sync về version hiện hành phía server).
Phiên bản đầu tiên công khai của Finhay Securities Open API. API hiện
cung cấp 30 endpoint chia 14 nhóm chức năng, bao trùm 4 mảng chính:
Khởi tạo (2 endpoint)
Bootstrap flow để lấyuserId và subAccountId — bắt buộc trước khi
gọi các endpoint user-scoped.Dữ liệu thị trường (20 endpoint)
Dữ liệu công khai về thị trường tài chính, chỉ cần API key Tier 1:- Dữ liệu giao dịch (2): giá stock realtime, lịch sử OHLCV.
- Phân tích cơ bản (3): chỉ số tài chính tổng quan, phân tích theo kỳ, báo cáo tài chính (income statement / balance sheet / cash flow).
- Tin tức & sự kiện (2): tin tức stock, báo cáo khuyến nghị từ analyst.
- Kinh tế vĩ mô (4): chỉ số CPI / PMI / GDP, lãi suất ngân hàng, chỉ số kinh tế lịch sử (Trading Economics), lịch sự kiện kinh tế.
- Hàng hoá (7): vàng, bạc (spot / chart / theo nhà cung cấp), top crypto trending.
- Tổng hợp đa loại (2): endpoint composite cross-domain, lịch sử giá instrument toàn cầu (US / Asian indices, Mag7, hàng hoá, forex).
Người dùng (1 endpoint)
Tổng tài sản — cross-product wealth summary của user (stock, fund, bond, cash, debt, PnL).Giao dịch (7 endpoint)
Thông tin tài khoản và lịch sử giao dịch của user, yêu cầu HMAC signing Tier 2:- Tiểu khoản (1): số dư, margin, dư nợ, ngân hàng liên kết.
- Danh mục đầu tư (1): stock đang nắm giữ kèm PnL theo vị thế.
- Sổ lệnh (2): lệnh trong ngày — full list hoặc detail theo
orderId. - Lãi/lỗ (1): PnL trong ngày tổng hợp qua mọi tiểu khoản.
- Quyền cổ đông (1): cổ tức, quyền mua, bỏ phiếu.
- Phiên giao dịch (1): trạng thái phiên + order type khả dụng.
Xác thực
API chia 2 tier:- Tier 1 — chỉ cần header
X-FH-APIKEY, dùng cho dữ liệu thị trường công khai. - Tier 2 — HMAC-SHA256 signing đầy đủ, dùng cho endpoint user-scoped.