Back to Details

finhay-portfolio

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Finhay Portfolio

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 relevant 
SUB_ACCOUNT_*
variable. Do not skip or defer.
通过Finhay证券开放API获取只读交易数据。所有端点均使用带签名的
GET
请求。
强制要求：执行任何操作前，请阅读并完成预检检查。需要配置：
FINHAY_API_KEY
、
FINHAY_API_SECRET
、
USER_ID
以及相关的
SUB_ACCOUNT_*
变量。请勿跳过或推迟该步骤。

Setup

配置

If 
USER_ID
or 
SUB_ACCOUNT_*
variables are missing, run once:
bash
./_shared/scripts/infer-sub-account.sh
This writes 
USER_ID
, 
SUB_ACCOUNT_NORMAL
, and/or 
SUB_ACCOUNT_MARGIN
to 
~/.finhay/credentials/.env
.
如果缺少
USER_ID
或
SUB_ACCOUNT_*
变量，请执行一次以下命令：
bash
./_shared/scripts/infer-sub-account.sh
该命令会将
USER_ID
、
SUB_ACCOUNT_NORMAL
和/或
SUB_ACCOUNT_MARGIN
写入
~/.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.
bash
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"
始终使用
request.sh
脚本。调用前请解析所有路径变量（
{subAccountId}
、
{userId}
）——签名路径必须是最终的完全解析后的路径。
bash
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
当需要传入
{subAccountId}
时，询问用户要使用NORMAL还是MARGIN账户，然后替换为对应的环境变量：
  • NORMAL → 
    $SUB_ACCOUNT_NORMAL
  • MARGIN → 
    $SUB_ACCOUNT_MARGIN

Endpoints

端点

EndpointUse whenPath paramQuery paramsRes 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.
端点使用场景路径参数查询参数响应键
/trading/accounts/{subAccountId}/summary
账户详情、保证金、负债
{subAccountId}
→ 询问用户		—
result
/users/v4/users/{userId}/assets/summary
余额、总资产、资产净值
{userId}
→ 
$USER_ID
cache-control
（默认值
CACHE
）
data
/trading/sub-accounts/{subAccountId}/orders
订单历史
{subAccountId}
→ 询问用户
fromDate
、
toDate
（必填）
result
/trading/v1/accounts/{subAccountId}/order-book
当日订单簿
{subAccountId}
→ 询问用户		—
result
/trading/v1/accounts/{subAccountId}/order-book/{orderId}
单个订单详情
{subAccountId}
→ 询问用户, 
{orderId}
—
data
/trading/v2/sub-accounts/{subAccountId}/portfolio
股票持仓
{subAccountId}
→ 询问用户		—
data
/trading/pnl-today/{userId}
当日盈亏
{userId}
→ 
$USER_ID
—
data
/trading/v5/account/{subAccountId}/user-rights
交易权限
{subAccountId}
→ 询问用户		—
result
/trading/market/session
市场开闭市状态—
exchange
（例如
HOSE
）
result
路径版本（
v1
、
v2
、
v4
、
v5
）是固定的，请始终使用上方列出的准确版本。

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.
  • 每个端点仅接受上方路径和查询列中列出的参数，请勿添加额外参数。
  • URL中的所有
    {variables}
    都是路径变量——请将其替换到URL中，切勿作为查询参数传递。
详情与响应结构：references/endpoints.md。枚举值：references/enums.md。

Constraints

约束

See shared constraints, plus:
  • Never substitute 
    {subAccountId}
    without first confirming the sub-account type with the user.
请参见通用约束，同时额外遵循以下规则：
  • 未先向用户确认子账户类型的情况下，切勿替换
    {subAccountId}
    参数。