Finhay Portfolio
Read-only trading data via the Finhay Securities Open API. All endpoints use signed GET requests.
MANDATORY: Before any action, read and complete pre-flight checks. Required:FINHAY_API_KEY,FINHAY_API_SECRET,USER_ID, and the relevantSUB_ACCOUNT_*variable. Do not skip or defer.
Setup
If USER_ID or SUB_ACCOUNT_* variables are missing, run once:
./_shared/scripts/infer-sub-account.shThis writes USER_ID, SUB_ACCOUNT_NORMAL, and/or SUB_ACCOUNT_MARGIN to ~/.finhay/credentials/.env.
Making a Request
Always use request.sh. Resolve all path variables ({subAccountId}, {userId}) before calling — the signed path must be the final, fully resolved path.
source ~/.finhay/credentials/.env
./_shared/scripts/request.sh GET "/trading/accounts/$SUB_ACCOUNT_NORMAL/summary"
./_shared/scripts/request.sh GET "/users/v4/users/$USER_ID/assets/summary"
./_shared/scripts/request.sh GET "/trading/sub-accounts/$SUB_ACCOUNT_MARGIN/orders" "fromDate=2024-01-01&toDate=2024-01-31"
./_shared/scripts/request.sh GET "/trading/v2/sub-accounts/$SUB_ACCOUNT_NORMAL/portfolio"
./_shared/scripts/request.sh GET "/trading/pnl-today/$USER_ID"
./_shared/scripts/request.sh GET "/trading/market/session" "exchange=HOSE"Sub-account Selection
When {subAccountId} is required, ask the user whether to use NORMAL or MARGIN, then substitute the corresponding env variable:
- NORMAL →
$SUB_ACCOUNT_NORMAL - MARGIN →
$SUB_ACCOUNT_MARGIN
Endpoints
| Endpoint | Use when | Path param | Query params | Res key |
|---|---|---|---|---|
/trading/accounts/{subAccountId}/summary | Account detail, margin, debt | {subAccountId} → ask user | — | result |
/users/v4/users/{userId}/assets/summary | Balance, total assets, NAV | {userId} → $USER_ID | cache-control (default CACHE) | data |
/trading/sub-accounts/{subAccountId}/orders | Order history | {subAccountId} → ask user | fromDate, toDate (required) | result |
/trading/v1/accounts/{subAccountId}/order-book | Today's order book | {subAccountId} → ask user | — | result |
/trading/v1/accounts/{subAccountId}/order-book/{orderId} | Single order detail | {subAccountId} → ask user, {orderId} | — | data |
/trading/v2/sub-accounts/{subAccountId}/portfolio | Stock holdings | {subAccountId} → ask user | — | data |
/trading/pnl-today/{userId} | Today's P&L | {userId} → $USER_ID | — | data |
/trading/v5/account/{subAccountId}/user-rights | Trading permissions | {subAccountId} → ask user | — | result |
/trading/market/session | Market open/close | — | exchange (e.g. HOSE) | result |
Path versions (v1, v2, v4, v5) are fixed. Always use the exact versions listed above.
Parameter rules
- Each endpoint accepts only the parameters listed in its path and query columns above. Do not add extra parameters.
- All
{variables}in the URL are path variables — substitute them into the URL, never pass as query params.
Details & response schemas: references/endpoints.md. Enums: references/enums.md.
Constraints
See shared constraints, plus:
- Never substitute
{subAccountId}without first confirming the sub-account type with the user.