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/**GET /trading/securities/**- Toàn bộ
GET /fund-trading/public/**(quỹ mở)
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/v3/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}
X-FH-BODYHASH (có body) và X-FH-2FA-TOKEN (daily 2FA session):
POST /trading/oa/sub-accounts/{subAccountId}/ordersPUT /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}DELETE /trading/oa/sub-accounts/{subAccountId}/orders/{orderId}
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.
2FA session (X-FH-2FA-TOKEN)
Riêng các write operation thuộc nhóm Thực thi lệnh (preview — POST
/ PUT / DELETE dưới /trading/oa/**), ngoài 5 header HMAC client
còn phải gửi kèm X-FH-2FA-TOKEN — daily JWT session token do server
cấp sau khi user xác thực qua OTP.
- Token có tuổi thọ 1 ngày giao dịch, scope theo
apiKey. - Lưu vào memory hoặc secret store; tự re-init khi sang ngày mới.
- Khi token hết hạn / không hợp lệ / bị revoke, server trả
HTTP 403vớierror_codelà 1 trong:OTP_SESSION_REQUIREDOTP_SESSION_EXPIREDOTP_SESSION_INVALIDOTP_SESSION_REVOKED
- Bắt 1 trong 4 mã trên → chạy lại OTP flow để lấy token mới → retry request.
OTP flow để xin
X-FH-2FA-TOKEN không thuộc surface của tài liệu này.
Liên hệ team Finhay để biết chi tiết quy trình nội bộ.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.