Skip to content

Commit e3af0aa

Browse files
sunli829sunli829
committed
Improve documentation onboarding and troubleshooting
Add quickstart pointers, example links, minimal verification steps, and troubleshooting tips across language SDK READMEs.
1 parent 3670046 commit e3af0aa

9 files changed

Lines changed: 242 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,79 @@ LongPort OpenAPI provides programmatic quote trading interfaces for investors wi
3939
| LONGPORT_PRINT_QUOTE_PACKAGES | Print quote packages when connected, `true` or `false` (Default: `true`) |
4040
| LONGPORT_LOG_PATH | Set the path of the log files (Default: `no logs`) |
4141

42-
## SDK Documenation
42+
## Quickstart
43+
44+
- Pick a language SDK and follow its README for install + first request:
45+
- Rust: `rust/README.md`
46+
- Python: `python/README.md`
47+
- Node.js: `nodejs/README.md`
48+
- Java: `java/README.md`
49+
- C: `c/README.md`
50+
- C++: `cpp/README.md`
51+
- Go: https://github.com/longportapp/openapi-go
52+
- Full reference docs: https://longportapp.github.io/openapi
53+
54+
## SDK Documentation
4355

4456
https://longportapp.github.io/openapi
4557

58+
## Troubleshooting
59+
60+
- Environment variables not taking effect
61+
- macOS/Linux: `export ...` only affects the current shell session.
62+
- Windows: `setx ...` requires opening a new terminal/session to take effect.
63+
- Authentication errors (401/403)
64+
- Verify `LONGPORT_APP_KEY`, `LONGPORT_APP_SECRET`, `LONGPORT_ACCESS_TOKEN` are correct and not expired.
65+
- Ensure your OpenAPI app has the required permissions.
66+
- Network / connection errors
67+
- Check firewall/proxy rules for HTTPS/WSS.
68+
- If you use a custom endpoint, set `LONGPORT_HTTP_URL`, `LONGPORT_QUOTE_WS_URL`, `LONGPORT_TRADE_WS_URL`.
69+
- Quote subscription exits immediately
70+
- Keep the process running (event loop / sleep / blocking receive loop), otherwise you will not see push events.
71+
- Debugging
72+
- Enable logs via `LONGPORT_LOG_PATH`.
73+
- If quotes connect but look empty, keep `LONGPORT_PRINT_QUOTE_PACKAGES=true` to confirm opened quote packages.
74+
75+
## Minimal Verification
76+
77+
If you're not sure whether your environment / credentials are correct, start with the built-in HTTP client examples.
78+
79+
- Python:
80+
81+
```bash
82+
python examples/python/http_client.py
83+
```
84+
85+
- Node.js:
86+
87+
```bash
88+
node examples/nodejs/http_client.js
89+
```
90+
91+
- Rust:
92+
93+
```bash
94+
cargo run --manifest-path examples/rust/Cargo.toml -p http_client
95+
```
96+
97+
- Java (from the example module directory):
98+
99+
```bash
100+
cd examples/java/http_client
101+
mvn -q -DskipTests package
102+
mvn -q -DskipTests exec:java
103+
```
104+
105+
- C/C++:
106+
- Use the sources in `examples/c/http_client/main.c` and `examples/cpp/http_client/main.cpp`.
107+
- Build instructions depend on your toolchain; see the corresponding language SDK README.
108+
109+
Expected results:
110+
111+
- If credentials are valid and network is reachable, the HTTP call returns JSON.
112+
- If it returns 401/403, check your `LONGPORT_APP_KEY`, `LONGPORT_APP_SECRET`, `LONGPORT_ACCESS_TOKEN`.
113+
- If it times out / cannot connect, check proxy/firewall and your endpoint env vars.
114+
46115
## Resources
47116

48117
- [LongPort OpenAPI](https://open.longportapp.com/en/)

‎c/README.md‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,22 @@
11
# LongPort OpenAPI SDK for C
22

3-
`longport` provides an easy-to-use interface for invokes [`LongPort OpenAPI`](https://open.longportapp.com/en/).
3+
`longport` provides an easy-to-use interface for invoking [`LongPort OpenAPI`](https://open.longportapp.com/en/).
4+
5+
## Documentation
6+
7+
- SDK docs: https://longportapp.github.io/openapi/c/index.html
8+
- LongPort OpenAPI: https://open.longportapp.com/en/
9+
10+
## Examples
11+
12+
Runnable examples live in `examples/c/`:
13+
14+
- `examples/c/account_asset/main.c`
15+
- `examples/c/get_quote/main.c`
16+
- `examples/c/http_client/main.c`
17+
- `examples/c/subscribe_quote/main.c`
18+
- `examples/c/submit_order/main.c`
19+
- `examples/c/today_orders/main.c`
420

521
## Quickstart
622

@@ -44,8 +60,7 @@ on_quote(const struct lb_async_result_t* res)
4460
}
4561

4662
lb_security_quote_t* data = (lb_security_quote_t*)res->data;
47-
fop(int i = 0; i < res->length; i++)
48-
{
63+
for (int i = 0; i < res->length; i++) {
4964
const lb_security_quote_t* quote = &data[i];
5065
printf("%s timestamp=%ld last_done=%f open=%f high=%f low=%f volume=%ld "
5166
"turnover=%f\n",
@@ -72,7 +87,7 @@ on_quote_context_created(const struct lb_async_result_t* res)
7287
*((const lb_quote_context_t**)res->userdata) = res->ctx;
7388

7489
const char* symbols[] = { "700.HK", "AAPL.US", "TSLA.US", "NFLX.US" };
75-
lb_quote_context_quote(res->ctx, symbols, on_quote, NULL);
90+
lb_quote_context_quote(res->ctx, symbols, 4, on_quote, NULL);
7691
}
7792

7893
int
@@ -150,7 +165,7 @@ on_quote_context_created(const struct lb_async_result_t* res)
150165
151166
const char* symbols[] = { "700.HK", "AAPL.US", "TSLA.US", "NFLX.US" };
152167
lb_quote_context_subscribe(
153-
res->ctx, symbols, 4, LB_SUBFLAGS_QUOTE, true, on_subscrbe, NULL);
168+
res->ctx, symbols, 4, LB_SUBFLAGS_QUOTE, on_subscrbe, NULL);
154169
}
155170
156171
int
@@ -212,12 +227,18 @@ on_trade_context_created(const struct lb_async_result_t* res)
212227
*((const lb_quote_context_t**)res->userdata) = res->ctx;
213228

214229
lb_decimal_t* submitted_price = lb_decimal_from_double(50.0);
230+
lb_decimal_t* submitted_quantity = lb_decimal_from_double(200.0);
215231
lb_submit_order_options_t opts = {
216-
"700.HK", OrderTypeLO, OrderSideBuy, 200, TimeInForceDay, submitted_price,
217-
NULL, NULL, NULL, NULL, NULL, NULL,
232+
"700.HK", OrderTypeLO,
233+
OrderSideBuy, submitted_quantity,
234+
TimeInForceDay, submitted_price,
235+
NULL, NULL,
236+
NULL, NULL,
237+
NULL, NULL,
218238
NULL,
219239
};
220240
lb_decimal_free(submitted_price);
241+
lb_decimal_free(submitted_quantity);
221242
lb_trade_context_submit_order(res->ctx, &opts, on_submit_order, NULL);
222243
}
223244

@@ -245,9 +266,16 @@ main(int argc, char const* argv[])
245266
}
246267
```
247268
269+
## Troubleshooting
270+
271+
- Windows `setx` requires a new terminal; use `set` for the current `cmd.exe` session.
272+
- If you don't see callbacks, keep the process alive (examples use `getchar()`).
273+
- If building on Linux/macOS, ensure `ncurses` is installed (examples link it on non-Windows).
274+
- For debugging, set `LONGPORT_LOG_PATH` to enable SDK logs.
275+
248276
## License
249277
250278
Licensed under either of
251279
252-
* Apache License, Version 2.0,([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
253-
* MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.
280+
* Apache License, Version 2.0,([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
281+
* MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.

‎cpp/README.md‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,29 @@
11
# LongPort OpenAPI SDK for C++
22

3-
`longport` provides an easy-to-use interface for invokes [`LongPort OpenAPI`](https://open.longportapp.com/en/).
3+
`longport` provides an easy-to-use interface for invoking [`LongPort OpenAPI`](https://open.longportapp.com/en/).
4+
5+
## Documentation
6+
7+
- SDK docs: https://longportapp.github.io/openapi/cpp/index.html
8+
- LongPort OpenAPI: https://open.longportapp.com/en/
9+
10+
## Examples
11+
12+
Runnable examples live in `examples/cpp/`:
13+
14+
- `examples/cpp/get_quote/main.cpp`
15+
- `examples/cpp/history_candlesticks_by_offset/main.cpp`
16+
- `examples/cpp/http_client/main.cpp`
17+
- `examples/cpp/subscribe_candlesticks/main.cpp`
18+
- `examples/cpp/subscribe_quote/main.cpp`
19+
- `examples/cpp/submit_order/main.cpp`
20+
- `examples/cpp/today_orders/main.cpp`
421

522
## Quickstart
623

724
_Install LongPort OpenAPI SDK_
825

9-
[`Download C++ SDK`]([`Download C SDK`](https://github.com/longportapp/openapi/releases))
26+
[`Download C++ SDK`](https://github.com/longportapp/openapi/releases)
1027

1128
_Setting environment variables(MacOS/Linux)_
1229

@@ -209,9 +226,16 @@ main(int argc, char const* argv[])
209226
}
210227
```
211228
229+
## Troubleshooting
230+
231+
- Windows `setx` requires a new terminal; use `set` for the current `cmd.exe` session.
232+
- If you don't see push events, keep the process alive (examples use `std::cin.get()`).
233+
- If building on Linux/macOS, ensure `ncurses` is installed (examples link it on non-Windows).
234+
- For debugging, set `LONGPORT_LOG_PATH` to enable SDK logs.
235+
212236
## License
213237
214238
Licensed under either of
215239
216-
* Apache License, Version 2.0,([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
217-
* MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.
240+
* Apache License, Version 2.0,([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
241+
* MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.

‎examples/c/http_client/CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@ include_directories(../../../c/csrc/include)
33
add_executable(http_client_c main.c)
44
target_link_libraries(http_client_c longport_c)
55
if(NOT CMAKE_HOST_WIN32)
6-
target_link_libraries(get_quote_c ncurses)
6+
target_link_libraries(http_client_c ncurses)
77
endif()

‎java/README.md‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
11
# LongPort OpenAPI SDK for Java
22

3-
`longport` provides an easy-to-use interface for invokes [`LongPort OpenAPI`](https://open.longportapp.com/en/).
3+
`longport` provides an easy-to-use interface for invoking [`LongPort OpenAPI`](https://open.longportapp.com/en/).
4+
5+
## Documentation
6+
7+
- SDK docs: https://longportapp.github.io/openapi/java/index.html
8+
- LongPort OpenAPI: https://open.longportapp.com/en/
9+
10+
## Examples
11+
12+
Runnable examples live in `examples/java/`:
13+
14+
- `examples/java/account_asset/src/main/java/main.java`
15+
- `examples/java/history_candlesticks/src/main/java/Main.java`
16+
- `examples/java/subscribe_quote/src/main/java/Main.java`
17+
- `examples/java/submit_order/src/main/java/Main.java`
18+
- `examples/java/today_orders/src/main/java/main.java`
419

520
## Quickstart
621

@@ -94,9 +109,15 @@ public class Main {
94109
}
95110
```
96111

112+
## Troubleshooting
113+
114+
- Windows `setx` requires a new terminal; use `set` for the current `cmd.exe` session.
115+
- If you don't see push events, ensure the program keeps running (e.g. `Thread.sleep(...)`).
116+
- For debugging, set `LONGPORT_LOG_PATH` to enable SDK logs.
117+
97118
## License
98119

99120
Licensed under either of
100121

101-
* Apache License, Version 2.0,([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
102-
* MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.
122+
* Apache License, Version 2.0,([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
123+
* MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.

‎mcp/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
A [MCP](https://modelcontextprotocol.io/introduction) server implementation for [LongPort OpenAPI](https://open.longportapp.com), provides real-time stock market data, provides AI access analysis and trading capabilities through MCP.
44

5+
## Documentation
6+
7+
- LongPort OpenAPI: https://open.longportapp.com/en/
8+
- SDK docs: https://longportapp.github.io/openapi
9+
510
## Features
611

712
- Trading - Create, amend, cancel orders, query today’s/past orders and transaction details, etc.

‎nodejs/README.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,22 @@
11
# LongPort OpenAPI SDK for Node.js
22

3-
`longport` provides an easy-to-use interface for invokes [`LongPort OpenAPI`](https://open.longportapp.com/en/).
3+
`longport` provides an easy-to-use interface for invoking [`LongPort OpenAPI`](https://open.longportapp.com/en/).
4+
5+
## Documentation
6+
7+
- SDK docs: https://longportapp.github.io/openapi/nodejs/index.html
8+
- LongPort OpenAPI: https://open.longportapp.com/en/
9+
10+
## Examples
11+
12+
Runnable examples live in `examples/nodejs/`:
13+
14+
- `examples/nodejs/account_asset.js`
15+
- `examples/nodejs/http_client.js`
16+
- `examples/nodejs/subscribe_candlesticks.js`
17+
- `examples/nodejs/subscribe_quote.js`
18+
- `examples/nodejs/submit_order.js`
19+
- `examples/nodejs/today_orders.js`
420

521
## Quickstart
622

@@ -84,9 +100,15 @@ TradeContext.new(config)
84100
.then((resp) => console.log(resp.toString()));
85101
```
86102

103+
## Troubleshooting
104+
105+
- Windows `setx` requires a new terminal; use `set` for the current `cmd.exe` session.
106+
- If the script exits, you won't receive push events; keep Node running.
107+
- For debugging, set `LONGPORT_LOG_PATH` to enable SDK logs.
108+
87109
## License
88110

89111
Licensed under either of
90112

91-
* Apache License, Version 2.0,([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
92-
* MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.
113+
* Apache License, Version 2.0,([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
114+
* MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.

‎python/README.md‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,23 @@
11
# LongPort OpenAPI SDK for Python
22

3-
`longport` provides an easy-to-use interface for invokes [`LongPort OpenAPI`](https://open.longportapp.com/en/).
3+
`longport` provides an easy-to-use interface for invoking [`LongPort OpenAPI`](https://open.longportapp.com/en/).
4+
5+
## Documentation
6+
7+
- SDK docs: https://longportapp.github.io/openapi/python/index.html
8+
- LongPort OpenAPI: https://open.longportapp.com/en/
9+
10+
## Examples
11+
12+
Runnable examples live in `examples/python/`:
13+
14+
- `examples/python/account_asset.py`
15+
- `examples/python/history_candlesticks.py`
16+
- `examples/python/http_client.py`
17+
- `examples/python/subscribe_candlesticks.py`
18+
- `examples/python/subscribe_quote.py`
19+
- `examples/python/submit_order.py`
20+
- `examples/python/today_orders.py`
421

522
## References
623

@@ -98,9 +115,15 @@ resp = ctx.submit_order("700.HK", OrderType.LO, OrderSide.Buy, Decimal(
98115
print(resp)
99116
```
100117

118+
## Troubleshooting
119+
120+
- Windows `setx` requires a new terminal; use `set` for the current `cmd.exe` session.
121+
- If the program exits, you won't receive push events; keep the process alive (e.g. `sleep(...)`).
122+
- For debugging, set `LONGPORT_LOG_PATH` to enable SDK logs.
123+
101124
## License
102125

103126
Licensed under either of
104127

105-
* Apache License, Version 2.0,([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
106-
* MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.
128+
* Apache License, Version 2.0,([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
129+
* MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT) at your option.

0 commit comments

Comments
 (0)