Repository navigation
docs(trade): add US account asset APIs and mark AP-only asset APIs - #1297
Merged
Merged
Conversation
Add pages for the US data-center account asset endpoints in en, zh-CN and zh-HK, plus their openapi.yaml entries: - US Cash and Buying Power (GET /v1/us/assets/cash-and-buy-power) - US Available Holding (GET /v1/us/assets/available-holding) - US Transaction History (POST /v1/us/assets/transaction-history) - US Exchange Rates (GET /v1/us/assets/exchange-rates) Mark Account Assets, Stock Positions, Fund Positions, Cash Flow, Margin Ratio and Exchange Rates as AP (Longbridge HK/SG) only and point US accounts to the matching US APIs. Note in Getting Started that US accounts use us_asset_overview / us_cash_and_buy_power instead of account_balance.
Add Node.js and Go SDK example tabs to the US Cash and Buying Power, US Available Holding, US Transaction History and US Exchange Rates pages in en, zh-CN and zh-HK, using the method and type names from the SDK bindings.
Use real field types, enum values and key names observed from LBUS production: transaction create_at/done_at are numeric strings, items carry counter_id alongside symbol, biz_code values such as LVASAD, exchange-rate keys are the account channel and rate type with numeric rates, and asset overview stock/crypto symbols are bare tickers.
Add an OAuth scopes and token revocation section to getting started, add 403308 to the error codes, cross-link scopes and 403308 from the MCP page, and note that Longbridge US accounts have no paper accounts.
/oauth2/revoke only blocks refresh; a revoked access token keeps working until it expires, so documenting it as a way to end a session is misleading.
hogan-yuan
added a commit
to longbridge/openapi
that referenced
this pull request
Oct 23, 2026
## Why LBUS (US data-center) accounts can't read balances, cash flow or exchange rates through the SDK: the generic `/v1/asset/*` and `/v1/risk/margin-ratio` endpoints are AP-only. On US they return `code 12 internal server error`, because the gateway reports `unknown service PortfolioAsset` (the backend isn't deployed in US). This was found in the US UAT (items 3.3 / 4.3 / 5.4). ## What New `TradeContext` methods for US accounts (`dc_restrict(DcRegion::Us)`): | Method | Endpoint | |---|---| | `us_cash_and_buy_power(currency)` | `GET /v1/us/assets/cash-and-buy-power` | | `us_available_holding(opts)` | `GET /v1/us/assets/available-holding` | | `us_transaction_history(opts)` | `POST /v1/us/assets/transaction-history` | | `us_exchange_rates()` | `GET /v1/us/assets/exchange-rates` | - Response types follow the live `lb-portfolio-liberty` schemas (read via inner-gateway reflection). The exchange-rate response is a two-level map keyed by account channel (e.g. `us_lb_apex`) and rate type (`am` / `reference`). The SDK flattens it into `exchanges[]` and keeps both keys on each entry. - `fund_positions` and `margin_ratio` are now AP-only (`dc_restrict(DcRegion::Ap)`), so US accounts get a clear region error instead of `code 12`. US accounts have no fund holdings or margin-ratio data. - Bindings: Rust (async + blocking), Python (sync + async + `openapi.pyi`), Node.js (napi; `index.d.ts` regenerated with `@napi-rs/cli` 3.8.0), Java JNI layer. - Java classes and C/C++ are not included, following the precedent of the existing US methods (`us_asset_overview` etc.), which are not exposed there either. - CHANGELOG updated. ## Gateway All four routes are deployed to prod. `transaction-history` (559) and `exchange-rates` (558) are new. `available-holding` (440) now has `symbol2CounterID`, so callers pass `AAPL.US`. The routes are also bound to MCP scopes (`account.read` / `trade.read`) on the HK and US registries. ## Testing - `cargo test -p longbridge --lib`: 76 passed. Clippy shows no new warnings. Python and Node built locally, and the new methods were checked by importing them. - Against US prod with an LBUS API key: all four endpoints return data. The real responses deserialize into the new types. This caught a bug, fixed in `f8877d2ab`: the gateway returns both `symbol` and `counter_id`, so the earlier `counter_id` alias caused a duplicate-field error. ## Related - Go SDK: longbridge/openapi-go#135 - Docs: longbridge/developers#1297 - Consumers (draft until this is released): longbridge/longbridge-terminal#337, longbridge/longbridge-mcp#173 ## Updated after real-data review Checked against masked US prod responses (overview, cash-and-buy-power, available-holding, transaction-history, exchange-rates). The new types match. One gap fixed in cab7903: `USCryptoEntry` (used by `us_asset_overview`) kept only 5 of the fields prod returns for a crypto holding, so it had no `quantity`. It now has the same fields as `USStockEntry` (`quantity`, `market`, `name`, prices, `today_pl`, `position_side`, ...) in Rust, Python and Node.js. The `symbol` doc now says it is the bare pair code (`BTCUSD`), and the user-facing symbol is `<symbol>.<market>`. Also added a test using the prod response shapes (`current_page` as a number, `us_lb_apex`/`am`/`reference` keys, numeric-string timestamps). `cargo test -p longbridge --lib` passes (77 tests). `index.d.ts` was regenerated with `@napi-rs/cli@3.8.0`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
LBUS users follow the asset docs and get
code 12: the generic asset endpoints are AP-only, and the docs don't say so or point to the US endpoints (US UAT 3.3).What
trade/asset/: Cash and Buying Power, Available Holding, Transaction History, Exchange Rates (US). The API reference (openapi.yaml) gets the 4 endpoints too. Examples are in Python, Python async, Node.js, Rust and Go. Java is not included because the Java SDK does not expose these methods yet.us_asset_overview/us_cash_and_buy_powerfor balances.SDK: longbridge/openapi#613. The endpoints are already live on the prod gateway.
Testing
autocorrect --lintpasses.openapi.yamlparses. The Node.js and Go examples type-check against the SDK branches.bun run build:canaryshould be run before merge).Also in this PR
Doc fixes from the LBUS UAT replies:
us_order_detail. Today Orders and History Orders recommendus_query_ordersfor US accounts (UAT 3.4).403308(scope not authorized), with the fix and the no-securities-account/no-permission case. The MCP troubleshooting section links to it (UAT 3.x / 5.5).watchlist,account.read,trade.read,trade.write, and the production ids4/6/10/11from longbridge-mcp; other ids are treated as opaque) and a Sign Out section (delete the stored token file, orlongbridge auth logout) (UAT 2.3).order/grid: replaced "prompts for confirmation" /-y/--dry-runwith the actual preview +--execute <CODE>flow (UAT 5.5).portfolio/assets/cash-flow/exchange-rate: one-line note that LBUS should usepositionsfor now, with US support coming in feat(trade): route asset commands to US APIs for US accounts longbridge-terminal#337 (UAT 4.3 / 5.4).🤖 Generated with Claude Code