Skip to content

feat(trade): add risk_assessment API (all layers) - #625

Merged
hogan-yuan merged 6 commits into
mainfrom
feat/risk-assessment
Nov 17, 2026
Merged

hogan-yuan merged 6 commits into
mainfrom
feat/risk-assessment

Conversation

@hogan-yuan

Copy link
Copy Markdown
Member

Adds TradeContext.risk_assessment() for GET /v1/members/me/risk-assessment (Operation MemberAccount.GetUtStates), returning the current member's risk assessment (suitability questionnaire) result. RiskAssessment mirrors the server response field-for-field: risk, pi, approvals, re_authentication, pi_end_at, deadlines, risk_assessment_at, score, strategy_risk_levels.

  • Lenient decoding: integers accepted as JSON integers or integer strings (proto3 JSON sends int64 as strings), anything else → 0. String fields render non-string values as JSON text. Wrong-shaped maps/lists → empty. Maps are key-ordered (BTreeMap) in every language.
  • C: lb_trade_context_risk_assessment / lb_risk_assessment_t, with maps as key-sorted entry arrays. C++: std::map. Java: read-only Map (crosses JNI as JSON, parsed with gson). Node.js: plain object with Record maps. Python: dict, openapi.pyi updated.
  • nodejs/index.js is unchanged on purpose: RiskAssessment is a type-only interface.
  • No region restriction for now, because US-account behavior on this endpoint is unknown.

Testing: end-to-end against the test gateway from Rust, C/C++, Java, Node.js, Python (sync and async) and Go; all fields match the raw response. Unit tests cover decode edge cases. Prod verification is pending, because the route isn't deployed to prod yet (404000).

Companion: longbridge/openapi-go feat/risk-assessment.

Add `TradeContext.risk_assessment()` for `GET /v1/members/me/risk-assessment`,
returning the current member's risk assessment (suitability questionnaire)
result. `RiskAssessment` mirrors the server response field-for-field: risk,
pi, approvals, re_authentication, pi_end_at, deadlines, risk_assessment_at,
score and strategy_risk_levels.

Decoding is lenient so a change in how the gateway encodes a value cannot fail
the call: integers are accepted as JSON integers or integer strings (proto3
JSON sends int64 as strings), anything else becomes 0; string fields render
non-string values as JSON text; null maps/lists become empty. Maps are
key-ordered (BTreeMap) in every language.

- C: lb_trade_context_risk_assessment / lb_risk_assessment_t, maps as
  key-sorted entry arrays
- C++: TradeContext::risk_assessment, maps as std::map
- Java: TradeContext.getRiskAssessment(), maps as read-only Map (crossing
  JNI as JSON, parsed with gson)
- Node.js: ctx.riskAssessment(), plain object with Record maps
- Python: TradeContext / AsyncTradeContext.risk_assessment(), dict maps;
  openapi.pyi updated
A map or list field holding anything other than an object / array (e.g.
`"approvals": []`, a common empty-map encoding, or a scalar strategy list)
now decodes to empty instead of failing the whole risk_assessment() call,
matching the CHANGELOG promise that an encoding change cannot fail it.
`pi`, `pi_end_at` and `deadlines` are passed through raw because the server
documents neither the PI code values nor the time unit, and `risk` carries no
documented scale. Say so on the fields instead of leaving callers to guess,
and note that `approvals` values are strings (`is_corporate_client` arrives as
"true"/"false"), which is easy to misread as a boolean.

`pi_end_at` and `risk_assessment_at` deliberately break the SDK convention of
converting `*_at` to a timestamp and `yyyy-mm-dd` to a Date; the reason is now
recorded on the fields so the choice is reviewable rather than accidental.

Applies to all six layers plus the generated C header and Node typings.
hogan-yuan added a commit to longbridge/longbridge-terminal that referenced this pull request Nov 17, 2026
…ruct

Pin `[patch.crates-io]` to a rev instead of `branch = "feat/risk-assessment"`.
Once longbridge/openapi#625 merges its branch is deleted, and a branch-pinned
git source stops resolving in a clean checkout — CI and release builds would
break while a warm ~/.cargo/git cache kept working locally.

Also record in the comment that this patch is not only the new API: it moves
the SDK 5.3.0 -> 5.4.0 (oauth2 4.4 -> 5.0, reqwest 0.11 -> 0.12, PKCE, typed
`Error::OAuth`), which is where most of the Cargo.lock churn comes from.

The row-count assertion compared against the literal 9, so a field added to
`RiskAssessment` would be dropped from the table with the test still green.
Compare against the serialized struct instead.
hogan-yuan added a commit to longbridge/longbridge-mcp that referenced this pull request Nov 17, 2026
…implying eligibility

Pin `[patch.crates-io]` to a rev instead of `branch = "feat/risk-assessment"`.
Once longbridge/openapi#625 merges its branch is deleted, and a branch-pinned
git source stops resolving in a clean checkout — CI and release builds would
break while a warm ~/.cargo/git cache kept working locally. The comment also
corrects the target release (5.4.0 is already published and does not contain
the API) and records that this patch carries an SDK 5.3 -> 5.4 upgrade.

The tool description told the model to use the profile to decide "whether a
product is allowed before recommending it", but the server documents neither
the risk-level scale nor the PI code values, and `approvals` values are
strings ("false" is truthy in most languages). A model would answer a
suitability question confidently either way. Report the values instead, and
say so in all four languages.

docs/architecture.md: trade tool count 16 -> 17.
The previous commit argued that undocumented server semantics should not be
guessed at, then guessed twice: it claimed `risk` and `risk_assessment_at` are
"empty when never assessed". Nothing establishes that — the only recorded
response has both populated — and it is wrong as a diagnostic, because lenient
decoding also renders null or a non-string as "". Say "may be empty; the
server does not document when", and note on `risk_assessment_at` that
emptiness does not by itself mean never assessed.

The same commit also only reached Rust with most of its notes while the
CHANGELOG described them as applying throughout. Carry the `risk` scale note,
the `deadlines` unit note and the `risk_assessment_at` rationale into C, C++,
Java, Node and Python, and the `approvals` string-not-boolean warning into C,
whose header a C user reads on its own.

In C and C++ the `pi_end_at` wording presupposed a convention those layers do
not have — every `*_at` there is already a bare int64. State the real point
instead: the other time fields are Unix seconds, this one's unit is unknown.

CHANGELOG: "passed through as the server returns them" contradicted the
leniency rule described in the same bullet (floats and out-of-range values
decode to 0). It is the interpretation and unit conversion that are skipped.
The `risk_assessment_at` note said lenient decoding renders "a null or
non-string value" as an empty string. Only null (or an absent field) does;
`lenient_string` renders every other non-string as its compact JSON text —
which the struct-level doc seven lines above and both CHANGELOGs already say.
The note contradicted them.

The C and C++ `pi_end_at` note claimed the other time fields in those layers
are Unix seconds. They are not: `created_at` in the same header is documented
as an RFC 3339 string, and several `*_at` fields are `const char *` /
`std::string`. Drop the comparison and state only what is known — the unit is
undocumented, so the SDK does not interpret it. Two rounds of review have now
caught an unverified assertion in these notes; this removes the last one
rather than replacing it with another.

Also: Node said `pi_end_at` where the TypeScript field is `piEndAt`; the
C entry struct `lb_risk_assessment_deadline_t.value` had no unit caveat even
though the aggregate field did; and the "emptiness is not proof of never
assessed" note now reaches all seven layers instead of only Rust and Go.
The MCP tool description and its four locale strings were changed to drop
"the levels the member may trade", on the grounds that the server never
documented what those levels permit. The same sentence was left on the field
itself in all nine SDK sites and in the MCP output schema the model reads
alongside that description, so the two repos asserted opposite things about
one field. Say "strategy risk levels of the member" everywhere, and state
that the server does not document what they permit.

Also: in the C layer "a null value" reads as a NULL pointer in a `const char *`
doc, where the pointer is never null. Say "a JSON null".
@hogan-yuan
hogan-yuan merged commit c573bc6 into main Nov 17, 2026
56 checks passed
@hogan-yuan
hogan-yuan deleted the feat/risk-assessment branch November 17, 2026 08:46
hogan-yuan added a commit to longbridge/longbridge-mcp that referenced this pull request Nov 19, 2026
Expose the member's risk assessment (suitability questionnaire) profile via
`TradeContext::risk_assessment()` (`GET /v1/members/me/risk-assessment`):
risk level, PI status, approval states, assessment date, score and the
strategy risk levels the member may trade. Read-only, no parameters.

The response is passed through verbatim rather than through `tool_json`'s
`_at` transform: `pi_end_at` is a raw server value whose "not set" value is
`0` (which the transform would render as 1970-01-01) and whose unit is
undocumented, while `risk_assessment_at` is already a date string.

Registered in the `account.read` scope next to margin_ratio and
account_balance, exposed on /v2, with zh-CN/zh-HK/ja descriptions and an
output schema.

The SDK method is not on crates.io yet, so Cargo.toml carries a temporary
[patch.crates-io] pointing longbridge/longbridge-proto at the SDK branch
(longbridge/openapi#625); remove it once that release ships.
hogan-yuan added a commit to longbridge/longbridge-mcp that referenced this pull request Nov 19, 2026
…implying eligibility

Pin `[patch.crates-io]` to a rev instead of `branch = "feat/risk-assessment"`.
Once longbridge/openapi#625 merges its branch is deleted, and a branch-pinned
git source stops resolving in a clean checkout — CI and release builds would
break while a warm ~/.cargo/git cache kept working locally. The comment also
corrects the target release (5.4.0 is already published and does not contain
the API) and records that this patch carries an SDK 5.3 -> 5.4 upgrade.

The tool description told the model to use the profile to decide "whether a
product is allowed before recommending it", but the server documents neither
the risk-level scale nor the PI code values, and `approvals` values are
strings ("false" is truthy in most languages). A model would answer a
suitability question confidently either way. Report the values instead, and
say so in all four languages.

docs/architecture.md: trade tool count 16 -> 17.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant