bitget-api 3.0.0 → 3.0.2

package/README.md

@@ -21,24 +21,67 @@
 
 Updated & performant JavaScript & Node.js SDK for the Bitget V2 REST APIs and WebSockets:
 
+- Professional, robust & performant Bitget SDK with extensive production use in live trading environments.
 - Complete integration with all Bitget APIs.
-  - [x] Supports V1 REST APIs & WebSockets
+  - [x] Supports V1 REST APIs & WebSockets (legacy)
   - [x] Supports V2 REST APIs & WebSockets
-  - [x] Supports V3/UTA REST APIs & WebSockets
+  - [x] Supports V3/UTA REST APIs & WebSockets (latest)
   - [x] Supports order placement via V3 WebSocket API
-- TypeScript support (with type declarations for most API requests & responses).
+- Complete TypeScript support (with type declarations for all API requests & responses).
+  - Strongly typed requests and responses.
+  - Automated end-to-end tests on most API calls, ensuring no breaking changes are released to npm.
+- Actively maintained with a modern, promise-driven interface.
 - Over 100 integration tests making real API calls & WebSocket connections, validating any changes before they reach npm.
 - Robust WebSocket integration with configurable connection heartbeats & automatic reconnect then resubscribe workflows.
+  - Event driven messaging.
+  - Smart WebSocket persistence with automatic reconnection handling.
+  - Emit `reconnected` event when dropped connection is restored.
+  - Optional beautification of WebSocket events for improved readability.
 - Officially listed Node.js SDK in [Bitget API docs](https://bitgetlimited.github.io/apidoc/en/spot/#sdk-code-example).
 - Browser support (via webpack bundle - see "Browser Usage" below).
 - Support all authentication methods supported by Bitget:
   - [x] HMAC
   - [x] RSA
+- Heavy automated end-to-end testing with real API calls.
+  - End-to-end testing before any release.
+  - Real API calls in e2e tests.
+- Proxy support via axios integration.
+- Active community support & collaboration in telegram: [Node.js Algo Traders](https://t.me/nodetraders).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Examples](#examples)
+- [Issues & Discussion](#issues--discussion)
+- [Related Projects](#related-projects)
+- [Documentation](#documentation)
+- [Structure](#structure)
+- [Usage](#usage)
+  - [REST API Clients](#rest-api-clients)
+    - [V3 REST APIs (Unified Trading Account)](#v3-rest-apis)
+    - [V2 REST APIs](#v2-rest-apis)
+  - [WebSockets](#websockets)
+    - [V3 Unified Trading Account](#v3-unified-trading-account)
+      - [Sending Orders via WebSockets](#sending-orders-via-websockets)
+      - [Receiving Realtime Data](#receiving-realtime-data)
+    - [V2 WebSockets](#v2-websockets)
+  - [Customise Logging](#logging)
+    - [Custom Logger](#customise-logging)
+    - [Debug HTTP Requests](#debug-http-requests)
+  - [Frontend Usage](#browser-usage)
+    - [Import](#import)
+    - [Webpack](#webpack)
+- [LLMs & AI](#use-with-llms--ai)
+- [Contributions & Thanks](#contributions--thanks)
 
 ## Installation
 
 `npm install --save bitget-api`
 
+## Examples
+
+Refer to the [examples](./examples) folder for implementation demos.
+
 ## Issues & Discussion
 
 - Issues? Check the [issues tab](https://github.com/tiagosiebler/bitget-api/issues).
@@ -69,11 +112,14 @@ Check out my related JavaScript/TypeScript/Node.js projects:
 
 ## Documentation
 
-Most methods pass values as-is into HTTP requests. These can be populated using parameters specified by Bitget's API documentation, or check the type definition in each class within this repository (see table below for convenient links to each class).
+Most methods accept JS objects. These can be populated using parameters specified by Bitget's API documentation, or check the type definition in each class within this repository (see table below for convenient links to each class).
 
-- [Bitget API V2 Documentation](https://www.bitget.com/api-doc/common/intro).
-- [Bitget API V3/UTA Documentation](https://www.bitget.com/api-doc/uta/intro).
+- Bitget API Documentation
+  - [V3/UTA API Documentation](https://www.bitget.com/api-doc/uta/intro) (Latest - Unified Trading Account)
+  - [V2 API Documentation](https://www.bitget.com/api-doc/common/intro)
+  - [Legacy V1 API Documentation](https://bitgetlimited.github.io/apidoc/en/spot/#introduction) (deprecated)
 - [REST Endpoint Function List](./docs/endpointFunctionList.md)
+- [TSDoc Documentation (autogenerated using typedoc)](https://tsdocs.dev/docs/bitget-api)
 
 ## Structure
 
@@ -88,6 +134,13 @@ The version on npm is the output from the `build` command and can be used in pro
 
 ---
 
+# Usage
+
+Create API credentials at Bitget:
+
+- [Livenet API Management](https://www.bitget.com/en/support/articles/360011132814-How-to-create-API)
+- [Demo Trading Environment](https://www.bitget.com/en/demo-trading)
+
 ## REST API Clients
 
 Each REST API group has a dedicated REST client. To avoid confusion, here are the available REST clients and the corresponding API groups:
@@ -110,12 +163,18 @@ Examples for using each client can be found in:
 
 If you're missing an example, you're welcome to request one. Priority will be given to [github sponsors](https://github.com/sponsors/tiagosiebler).
 
-### Usage
-
-First, create API credentials on Bitget's website.
+### Getting Started
 
 All REST APIs are integrated in each dedicated Rest Client class. See the above table for which REST client to use. If you've upgraded to the Unified Trading Account, you should use the V3 REST APIs and WebSockets.
 
+There are several REST API modules as there are some differences in each API group:
+
+1. `RestClientV3` for the latest V3/UTA APIs (Unified Trading Account) - recommended for new projects.
+2. `RestClientV2` for V2 APIs - use if you haven't upgraded to UTA yet.
+3. Legacy V1 clients (`SpotClient`, `FuturesClient`, `BrokerClient`) - deprecated, migrate to V2 or V3.
+
+More Node.js & JavaScript examples for Bitget's REST APIs & WebSockets can be found in the [examples](./examples) folder on GitHub.
+
 #### V3 REST APIs
 
 These are only available if you have upgraded to the Unified Trading Account. If not, use the V2 APIs instead.
@@ -127,9 +186,9 @@ import { RestClientV3 } from 'bitget-api';
 
 // note the single quotes, preventing special characters such as $ from being incorrectly passed
 const client = new RestClientV3({
-  apiKey: process.env.API_KEY_COM || 'insert_api_key_here',
-  apiSecret: process.env.API_SECRET_COM || 'insert_api_secret_here',
-  apiPass: process.env.API_PASS_COM || 'insert_api_pass_here',
+  apiKey: process.env.API_KEY_COM || 'insert_api_key_here',
+  apiSecret: process.env.API_SECRET_COM || 'insert_api_secret_here',
+  apiPass: process.env.API_PASS_COM || 'insert_api_pass_here',
 });
 
 (async () => {
@@ -198,21 +257,30 @@ client
   });
 ```
 
-#### WebSockets
+## WebSockets
 
 All WebSocket functionality is supported via the WebsocketClient. Since there are currently 3 generations of Bitget's API, there are 3 WebsocketClient classes in this Node.js, JavaScript & TypeScript SDK for Bitget.
 
 Use the following guidance to decide which one to use:
 
-- Unified Trading Account / V3 (latest generation):
+- **Unified Trading Account / V3** (latest generation):
   - For receiving data, use the [WebsocketClientV3](./src/websocket-client-v3.ts).
   - For sending orders via WebSockets, use the [WebsocketAPIClient](./src/websocket-api-client.ts).
-- V2 (not upgraded to Unified Trading Account yet)
+- **V2** (not upgraded to Unified Trading Account yet)
   - Use the [WebsocketClientV2](./src/websocket-client-v2.ts).
-- V1 (deprecated)
+- **V1** (deprecated)
   - This is the oldest API group supported by Bitget. You should migrate to V3 or V2 as soon as possible.
   - If you're not ready to migrate, you can use the [WebsocketClientLegacyV1](./src/websocket-client-legacy-v1.ts) class in the meantime.
 
+All WebSocket clients support:
+
+- Event driven messaging
+- Smart WebSocket persistence with automatic reconnection
+- Heartbeat mechanisms to detect disconnections
+- Automatic resubscription after reconnection
+- Error handling and connection monitoring
+- Optional data beautification
+
 Higher level examples below, while more thorough examples can be found in the examples folder on GitHub.
 
 ##### V3 Unified Trading Account
@@ -407,6 +475,51 @@ wsClient.subscribe(
 
 For more examples, including how to use websockets with Bitget, check the [examples](./examples/) and [test](./test/) folders.
 
+### V2 WebSockets
+
+If you haven't upgraded to the Unified Trading Account, use the V2 WebSocket client:
+
+```javascript
+import { WebsocketClientV2 } from 'bitget-api';
+// or if you prefer require:
+// const { WebsocketClientV2 } = require('bitget-api');
+
+const API_KEY = 'xxx';
+const API_SECRET = 'yyy';
+const API_PASS = 'zzz';
+
+const wsClient = new WebsocketClientV2({
+  apiKey: API_KEY,
+  apiSecret: API_SECRET,
+  apiPass: API_PASS,
+  // Optional: connect to demo trading environment
+  // demoTrading: true,
+});
+
+// Handle incoming messages
+wsClient.on('update', (data) => {
+  console.log('WS update received: ', data);
+});
+
+wsClient.on('open', (data) => {
+  console.log('WS connection opened: ', data.wsKey);
+});
+
+wsClient.on('reconnected', (data) => {
+  console.log('WS reconnected: ', data?.wsKey);
+});
+
+wsClient.on('exception', (data) => {
+  console.log('WS error: ', data);
+});
+
+// Subscribe to public data streams
+wsClient.subscribeTopic('SPOT', 'ticker', symbol);
+
+// Subscribe to private data streams (requires authentication)
+wsClient.subscribeTopic('SPOT', 'account');
+```
+
 ---
 
 ## Logging
@@ -480,6 +593,12 @@ Build a bundle using webpack:
 
 The bundle can be found in `dist/`. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO - contributions welcome.
 
+## Use with LLMs & AI
+
+This SDK includes a bundled `llms.txt` file in the root of the repository. If you're developing with LLMs, use the included `llms.txt` with your LLM - it will significantly improve the LLMs understanding of how to correctly use this SDK.
+
+This file contains AI optimised structure of all the functions in this package, and their parameters for easier use with any learning models or artificial intelligence.
+
 ---
 
 <!-- template_contributions -->