API chia 2 tier theo mức độ nhạy cảm của dữ liệu. Tier 1 là mặc định cho dữ liệu thị trường công khai; Tier 2 áp dụng cho các endpoint user-scoped (đánh dấu riêng trong API Reference).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.
Tier 1 — Chỉ cần API key
Chỉ cần gửi headerX-FH-APIKEY trên mọi request. Áp dụng cho các
endpoint dữ liệu thị trường công khai:
- Toàn bộ
GET /market/** GET /trading/market/**
Tier 2 — HMAC signing đầy đủ
Áp dụng cho các endpoint liên quan đến thông tin user / tài khoản / lệnh giao dịch / lãi-lỗ. Mỗi request cần đủ 4 header (cộngX-FH-BODYHASH
khi request có body):
| Header | Khi nào | Giá trị |
|---|---|---|
X-FH-APIKEY | Luôn luôn | Client API key (dài hạn) |
X-FH-TIMESTAMP | Tier 2 | Unix time hiện tại, đơn vị mili-giây |
X-FH-NONCE | Tier 2 | UUIDv4, duy nhất per request |
X-FH-SIGNATURE | Tier 2 | HMAC_SHA256(secret, payload) — hex lowercase |
X-FH-BODYHASH | Tier 2 và có body | SHA256(body) — hex lowercase |
GET /users/v1/users/meGET /users/v1/users/{userId}/sub-accountsGET /users/v4/users/{userId}/assets/summaryGET /trading/accounts/{subAccountId}/summaryGET /trading/v1/accounts/{subAccountId}/order-bookGET /trading/v1/accounts/{subAccountId}/order-book/{orderId}GET /trading/v2/sub-accounts/{subAccountId}/portfolioGET /trading/v5/account/{subAccountId}/user-rightsGET /trading/pnl-today/{userId}
Signing payload
Payload đầu vào cho HMAC được build theo template dưới (mỗi field nối bằng\n):
TIMESTAMP
Unix mili-giây, chuỗi số thập phân (ví dụ
"1714464000123"). Server
chấp nhận lệch tối đa ±30 giây so với giờ thực — đảm bảo client
đồng bộ NTP.PATH [?QUERY]
Path của request, ví dụ
/trading/accounts/0001234567/summary. Nếu
request có query string, nối thêm với prefix ? (ví dụ
/market/stock-realtime?symbol=VNM). Bỏ hoàn toàn segment ?
nếu không có query.x-finhay-signing ở root spec, để các tool
codegen tự sinh signing layer.
Signing middleware
Lưu ý về form “Try It”: form gọi thử endpoint tích hợp trong tab
API Reference KHÔNG tự tính HMAC signature. Để test endpoint Tier 2,
hãy dùng Postman (setup pre-request script để sign), hoặc tự tính
signature rồi paste vào header tương ứng.