Financing and automatic currency conversion settings

These interfaces read or change financing, automatic currency conversion, and Japanese cross-currency rules for real securities accounts. They do not submit conversion, transfer, or funds-movement tasks. Real-device validation is not complete.

All interfaces require --enable-desktop-phase2-reads. Writes additionally require the independent, default-off FUTU_ACCOUNT_FUNDING_SETTINGS_WRITES setting.

Setting	REST POST read	REST POST write
Financing	/api/trd/get-account-financing-setting	/api/trd/set-account-financing-setting
Automatic conversion	/api/trd/get-account-auto-exchange-setting	/api/trd/set-account-auto-exchange-setting
Japanese foreign-currency conversion	/api/trd/get-account-foreign-exchange-setting	/api/trd/set-account-foreign-exchange-setting
Japanese local-currency conversion	/api/trd/get-account-local-exchange-setting	/api/trd/set-account-local-exchange-setting

CLI commands use the final path component and accept JSON through --c2s-stdin, with --rest-url or --rest-port. MCP tool names replace hyphens with underscores and add the futu_ prefix; pass the request as a c2s_json string. Native and gRPC interfaces use the corresponding protobuf requests. Safe state and receipts remain available in failed responses.

Reads require acc:read. Writes require both acc:read and trade:real. Every requested account and its actual market must be authorized for the caller. These rules apply to the whole securities-business account, so a market-restricted key must cover all relevant markets. Simulation or trade-unlock permission does not substitute for real-trading permission.

Reads require broker_id, a nonempty account_ids list, and extension_version: 1. Writes require broker_id, account_id, a nonempty intent_key, an explicit enabled boolean, and extension_version: 1. Automatic-conversion writes also require an explicit allow_enable_financing boolean. When it is false, the operation cannot enable financing as a prerequisite. Missing fields are not equivalent to false.

Accounts must come from current, valid account-query results. Select a proven universal-account ID or its securities-business account ID; futures, cryptocurrency, and other sibling-business IDs are not substitutes. Unresolved securities-account mapping, source qualification, or feature support produces an unavailable or unsupported result. Missing fields are not interpreted as disabled, and reading these settings does not implicitly refresh all accounts.

Receipts and retries

Reusing an intent_key for the same caller requires the same original account selection and setting parameters. The immutable plan, sent steps, and receipts are persisted. Concurrent reentry reuses the original operation or returns its existing receipt without duplicate dispatch. A setting whose dispatch outcome is unknown is not automatically resent; a later matching read alone cannot establish that the original write succeeded.

Disabling financing first disables automatic conversion and confirms the readback when automatic conversion is currently enabled. Enabling automatic conversion can first enable financing only when allow_enable_financing is true. Failed, unknown, or unconfirmed prerequisite steps prevent subsequent writes.

receipt.state distinguishes preparation, awaiting observation, unknown dispatch outcome, completion, rejection, and state mismatch. steps[].dispatch describes dispatch and acknowledgement, while steps[].observation describes the separate readback. A successful acknowledgement alone does not establish successful readback. Explicitly repeating the same intent while awaiting observation can read the original account again without resending the setting. is_noop records that valid initial observations already satisfied the target; it is not a synthetic backend acknowledgement.

If a new authoritative financing observation contradicts a prerequisite for an unsent continuation, the plan terminates with a state mismatch. terminal_observation preserves that observation without rewriting plan.initial or confirmed acknowledgements. A new intent can evaluate the current prerequisites again. This mechanism cannot release a sent step whose outcome remains unknown.

Financing reads expose raw fields separately from effective_enabled and effective_origin. A confirmed acknowledgement does not rewrite the raw account fields; a subsequent account refresh replaces the effective observation. Conversion readbacks preserve 0 (closed), 1 (waiting to close), 2 (open), unknown numeric values, and absent fields. Waiting to close is not closed.

Local structured tests do not establish live backend availability or release acceptance.