Wealth position reads

These endpoints read fund, bond and structured-note data for a real brokerage business account. They do not buy, redeem or move money. Live backend behavior remains unverified; Desktop Phase 2 reads default to off. The separate Native Bank contract is described below.

Operation	REST POST	MCP / CLI
Wealth holdings	/api/get-wealth-holdings	futu_get_wealth_holdings / get-wealth-holdings
Bond positions	/api/get-bond-account-positions	futu_get_bond_account_positions / get-bond-account-positions
Fund positions	/api/get-fund-account-positions	futu_get_fund_account_positions / get-fund-account-positions
Fund position details	/api/get-fund-position-details	futu_get_fund_position_details / get-fund-position-details

Gateway and generic gRPC use the corresponding public protocols. MCP and CLI forward the actual caller through REST and need its address.

For ordinary brokerage reads, all requests require extension_version: 1 and a complete header: real trd_env: 1, an actual business acc_id, and an authorized trd_market. Simulated accounts, aggregate parents and implicit hops to another associated business account are rejected. The verified account record supplies broker and business identity; callers cannot override them with a broker ID or UID.

The first three endpoints use existing acc:read and target-account rules. Fund details can contain other account information within the complete module response, so they require an authenticated, account-unrestricted acc:read key. Any account restriction, including an empty list, is rejected before dependency RPCs.

Bond/fund lists are limited to the supported Hong Kong/Singapore brokers. They require display_currency for this explicit view. Optional filter_currency and search are independent; empty or absent filter currency means no currency filter. Supported codes are USD, HKD, CNH, JPY, SGD and KRW; CNY and RMB are not silently rewritten. These inputs do not persist or synchronize another client's display preferences.

Fund details require stock_id. Eligibility and the true fund symbol come from one authoritative static snapshot, never from a guessed display code. Missing facts or an old cache awaiting backfill make the read unavailable. Fund cost basis comes from the user's existing configuration, cannot be overridden in the request, and is rechecked before publishing a result.

Amounts, quantities, costs and returns remain exact strings. Flat positions, currency groups and headings may represent the same data; do not add them together. These views do not alter ordinary securities asset totals. There are no pagination inputs or automatic page loops.

Responses preserve presence, unknown values and complete modules. Failed business responses may still carry raw data; inspect outer ret_type and the actual error_code. Missing-code semantics differ by endpoint. Missing detail modules are explicit failures, while an existing module with an absent optional payload retains that absence. The serialized backend body must be smaller than 1,024,000 bytes; REST also has a JSON body limit. Account, caller, connection, static facts and cost basis are rechecked. Returned transaction entries or links are data, not authorization to execute trades.

Native Bank reads

With a Native Bank source and its read features enabled, wealth holdings, fund positions and fund details use that source's verified accounts. Live backend behavior remains unverified. The bond-position list is unavailable for Native Bank; raw bond and note holdings remain available in the wealth-holdings payload.

All three Native Bank reads require an authenticated, account-unrestricted acc:read key. The header must identify a current verified account with a nonzero identifier and a currently enabled Hong Kong, US or fund market. Numeric identifiers alone never grant access.

Holdings and fund positions require native_bank_selection containing currency and complete valuation_options. A fund-list selection is:

{
  "currency": "USD",
  "valuation_options": {
    "currency": "USD",
    "use_before_price": false,
    "use_after_price": false,
    "use_overnight_price": false,
    "use_option_combo": false
  },
  "show_zero_qty": false
}

Bank currency accepts HKD, USD, CNY, EUR, JPY, GBP, CAD, AUD, NZD, SGD and CHF. Securities valuation replaces CNY with CNH and additionally accepts MYR and KRW. The current source supplies quote level and overnight entitlement; requests cannot override them.

For fund positions, display_currency must match the selected Bank currency, with display CNH corresponding to Bank CNY. filter_currency separately filters the original position currency. Search checks only ISIN and full fund name using ASCII case-insensitive substring matching. The required show_zero_qty: false uses the source's high-precision quantity test; very small nonzero text can count as zero. Holdings returns all raw fund, bond and note positions and rejects show_zero_qty. These choices do not change another client's preferences.

Optional s2c.bank_positions and s2c.bank_assets contain complete typed data with original numeric strings and field presence. They do not synthesize UI modules, grouping or totals. Native fund lists have an empty module_data_list; Native holdings leave the old flat fields empty. Fund details retain the existing detail response shape. Ordinary brokerage responses omit the new fields.