From eb93a844ffd2b9b0f6ad39d74c18a97eca74eb9f Mon Sep 17 00:00:00 2001 From: tiagosiebler Date: Fri, 4 Sep 2026 12:12:37 +0100 Subject: [PATCH 01/10] chore(docs): improve Bybit EU and x-site-id guidance --- .gitignore | 1 + README.md | 43 +++++++++++++++- docs/BYBIT_SDK_QUICKSTART_GUIDE.md | 36 ++++++++++++- llms.txt | 81 ++++++++++++++++++++++++++++-- src/util/requestUtils.ts | 7 ++- 5 files changed, 161 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index 5fefec58..6ef6df23 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,4 @@ examples/ts-testnet-trade.ts examples/ts-testnet.ts *.pem .issue* +docs/research diff --git a/README.md b/README.md index a312a894..19d5b5ee 100644 --- a/README.md +++ b/README.md @@ -86,8 +86,9 @@ Professional Node.js, JavaScript & TypeScript SDK for the Bybit REST APIs, WebSo - [Websocket API - Sending Orders via WebSockets](#websocket-api---sending-orders-via-websockets) - [Consumer Load Balancing](#balancing-load-across-multiple-connections) -## Bybit EU & Other Regions +## Bybit EU and Other Regions +- [`apiRegion` and `x-site-id`](#bybit-eu-and-other-regions-apiregion-and-x-site-id) - [REST API Usage with Bybit EU](#rest-api-usage-with-bybit-eu) ## Additional Features @@ -242,6 +243,12 @@ const restClientOptions = { // apiRegion: 'bytick', + /** + * Add the x-site-id header for an eligible international account that uses + * the global API domain, e.g. BRA_BTL for Brazil or ARG_BTL for Argentina. + */ + // siteId: 'BRA_BTL', + /** Default: false. Enable to parse/include per-API/endpoint rate limits in responses. */ // parseAPIRateLimits: true, @@ -563,7 +570,21 @@ Important: do not subscribe to the same topics on both clients or you will recei --- -## Bybit EU & Other Regions +## Bybit EU and Other Regions: apiRegion and x-site-id + +Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: + +| Account setup | REST API endpoint | SDK configuration | +| --- | --- | --- | +| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | + +`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. + +See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. + +### Dedicated Regional REST API Domains with apiRegion By default, this Node.js, JavaScript & TypeScript SDK uses the Bybit Global API & WebSocket domains. For regions where Bybit has dedicated regional domains, including the alternative Bybit Global domain (bytick), these can be configured in the REST Client using the `apiRegion` property. @@ -582,6 +603,24 @@ The following values are currently supported in this option: New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. +### Brazil and Argentina International Accounts with x-site-id + +Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: + +```typescript +import { RestClientV5 } from 'bybit-api'; + +const client = new RestClientV5({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); +``` + +Use `siteId: 'ARG_BTL'` for an Argentina international account. + +The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). + ### REST API Usage with Bybit EU Below is an example for using this Node.js, TypeScript & JavaScript SDK for Bybit's APIs, using an account registered on the Bybit EU domain: diff --git a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md index 5193fa4b..20176767 100644 --- a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md +++ b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md @@ -1155,6 +1155,8 @@ See also: Live is the default environment: ```typescript +import { RestClientV5 } from 'bybit-api'; + const client = new RestClientV5({ key: process.env.BYBIT_API_KEY!, secret: process.env.BYBIT_API_SECRET!, @@ -1207,7 +1209,21 @@ ws.subscribeV5(['order', 'execution', 'position', 'wallet'], 'linear'); Do not combine `testnet: true` with `demoTrading: true`. Bybit's demo trading docs also note that WebSocket API commands are not supported in demo trading, so use REST API demo trading or private demo streams for demo workflows, and use testnet for WebSocket API command testing. -### Regional REST API domains +### Regional REST API access: apiRegion and x-site-id + +Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: + +| Account setup | REST API endpoint | SDK configuration | +| --- | --- | --- | +| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | + +`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. + +See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. + +#### Dedicated regional domains with apiRegion By default, REST API calls use the global Bybit domain. If your account belongs to a regional Bybit domain, set `apiRegion`: @@ -1233,6 +1249,24 @@ Supported API region values in this SDK: New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. +#### Brazil and Argentina international accounts with x-site-id + +Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: + +```typescript +import { RestClientV5 } from 'bybit-api'; + +const client = new RestClientV5({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); +``` + +Use `siteId: 'ARG_BTL'` for an Argentina international account. + +The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). + You can also pass `baseUrl` for a custom REST API domain, or `wsUrl` for a custom WebSocket URL when needed. See also: [custom REST API URL example](../examples/Rest/rest-v5-custom-url.ts) diff --git a/llms.txt b/llms.txt index 766890c7..c1bcbebe 100644 --- a/llms.txt +++ b/llms.txt @@ -12900,6 +12900,8 @@ See also: Live is the default environment: ```typescript +import { RestClientV5 } from 'bybit-api'; + const client = new RestClientV5({ key: process.env.BYBIT_API_KEY!, secret: process.env.BYBIT_API_SECRET!, @@ -12911,6 +12913,8 @@ const client = new RestClientV5({ Testnet uses separate credentials and separate API domains: ```typescript +import { RestClientV5 } from 'bybit-api'; + const client = new RestClientV5({ key: process.env.BYBIT_API_KEY!, secret: process.env.BYBIT_API_SECRET!, @@ -12952,7 +12956,21 @@ ws.subscribeV5(['order', 'execution', 'position', 'wallet'], 'linear'); Do not combine `testnet: true` with `demoTrading: true`. Bybit's demo trading docs also note that WebSocket API commands are not supported in demo trading, so use REST API demo trading or private demo streams for demo workflows, and use testnet for WebSocket API command testing. -### Regional REST API domains +### Regional REST API access: apiRegion and x-site-id + +Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: + +| Account setup | REST API endpoint | SDK configuration | +| --- | --- | --- | +| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | + +`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. + +See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. + +#### Dedicated regional domains with apiRegion By default, REST API calls use the global Bybit domain. If your account belongs to a regional Bybit domain, set `apiRegion`: @@ -12978,6 +12996,24 @@ Supported API region values in this SDK: New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. +#### Brazil and Argentina international accounts with x-site-id + +Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: + +```typescript +import { RestClientV5 } from 'bybit-api'; + +const client = new RestClientV5({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); +``` + +Use `siteId: 'ARG_BTL'` for an Argentina international account. + +The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). + You can also pass `baseUrl` for a custom REST API domain, or `wsUrl` for a custom WebSocket URL when needed. See also: [custom REST API URL example](../examples/Rest/rest-v5-custom-url.ts) @@ -21987,8 +22023,9 @@ Professional Node.js, JavaScript & TypeScript SDK for the Bybit REST APIs, WebSo - [Websocket API - Sending Orders via WebSockets](#websocket-api---sending-orders-via-websockets) - [Consumer Load Balancing](#balancing-load-across-multiple-connections) -## Bybit EU & Other Regions +## Bybit EU and Other Regions +- [`apiRegion` and `x-site-id`](#bybit-eu-and-other-regions-apiregion-and-x-site-id) - [REST API Usage with Bybit EU](#rest-api-usage-with-bybit-eu) ## Additional Features @@ -22143,6 +22180,12 @@ const restClientOptions = { // apiRegion: 'bytick', + /** + * Add the x-site-id header for an eligible international account that uses + * the global API domain, e.g. BRA_BTL for Brazil or ARG_BTL for Argentina. + */ + // siteId: 'BRA_BTL', + /** Default: false. Enable to parse/include per-API/endpoint rate limits in responses. */ // parseAPIRateLimits: true, @@ -22464,7 +22507,21 @@ Important: do not subscribe to the same topics on both clients or you will recei --- -## Bybit EU & Other Regions +## Bybit EU and Other Regions: apiRegion and x-site-id + +Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: + +| Account setup | REST API endpoint | SDK configuration | +| --- | --- | --- | +| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | + +`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. + +See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. + +### Dedicated Regional REST API Domains with apiRegion By default, this Node.js, JavaScript & TypeScript SDK uses the Bybit Global API & WebSocket domains. For regions where Bybit has dedicated regional domains, including the alternative Bybit Global domain (bytick), these can be configured in the REST Client using the `apiRegion` property. @@ -22483,6 +22540,24 @@ The following values are currently supported in this option: New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. +### Brazil and Argentina International Accounts with x-site-id + +Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: + +```typescript +import { RestClientV5 } from 'bybit-api'; + +const client = new RestClientV5({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); +``` + +Use `siteId: 'ARG_BTL'` for an Argentina international account. + +The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). + ### REST API Usage with Bybit EU Below is an example for using this Node.js, TypeScript & JavaScript SDK for Bybit's APIs, using an account registered on the Bybit EU domain: diff --git a/src/util/requestUtils.ts b/src/util/requestUtils.ts index 80e807f6..81c8da13 100644 --- a/src/util/requestUtils.ts +++ b/src/util/requestUtils.ts @@ -77,7 +77,12 @@ export interface RestClientOptions { apiRegion?: APIRegion; - /** Site ID header for regional access (e.g. 'ARG_BTL' for Argentina) */ + /** + * Site ID sent as the `x-site-id` header on every REST request. + * Required for eligible international accounts that use the global API domain, + * e.g. `BRA_BTL` for Brazil or `ARG_BTL` for Argentina. + * @see https://bybit-exchange.github.io/docs/v5/guide#authentication + */ siteId?: string; /** Default: true. whether to try and post-process request exceptions. */ From 6aab848a55748433a444b14eaad47695580f5a93 Mon Sep 17 00:00:00 2001 From: tiagosiebler Date: Fri, 4 Sep 2026 12:14:34 +0100 Subject: [PATCH 02/10] chore(docs): sync documented Bybit regions --- README.md | 5 +++-- docs/BYBIT_SDK_QUICKSTART_GUIDE.md | 1 + llms.txt | 6 ++++-- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 19d5b5ee..d1951513 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,7 @@ const restClientOptions = { /** * Optionally override API domain used: - * apiRegion: 'default' | 'bytick' | 'NL' | 'HK' | 'TK', + * apiRegion: 'default' | 'bytick' | 'NL' | 'TK' | 'KZ' | 'HK' | 'GE' | 'UAE' | 'EU' | 'JP', **/ // apiRegion: 'bytick', @@ -593,13 +593,14 @@ The following values are currently supported in this option: - `apiRegion: undefined`: if missing or undefined, this SDK will default to the Bybit Global domain `api.bybit.com`. - `apiRegion: "default"`: the Bybit Global domain (same behaviour as above). - `apiRegion: "bytick"`: the alternative Bybit Global domain `api.bytick.com`. -- `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bytick.nl`. +- `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bybit.nl`. - `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit-tr.com`. - `apiRegion: "KZ"`: the dedicated Bybit Kazakhstan domain `api.bybit.kz`. - `apiRegion: "HK"`: the dedicated Bybit HK domain `api.byhkbit.com`. - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. - `apiRegion: "UAE"`: the dedicated Bybit United Arab Emirates domain `api.bybit.ae`. - `apiRegion: "EU"`: the dedicated Bybit EU/EEA domain `api.bybit.eu`. +- `apiRegion: "JP"`: the dedicated Bybit Japan domain `api.manepa.jp`. Testnet uses `api-testnet.manepa.jp`. New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. diff --git a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md index 20176767..e391e8f9 100644 --- a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md +++ b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md @@ -1246,6 +1246,7 @@ Supported API region values in this SDK: - `GE` - `UAE` - `EU` +- `JP` New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. diff --git a/llms.txt b/llms.txt index c1bcbebe..fb2bcca9 100644 --- a/llms.txt +++ b/llms.txt @@ -12993,6 +12993,7 @@ Supported API region values in this SDK: - `GE` - `UAE` - `EU` +- `JP` New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. @@ -22175,7 +22176,7 @@ const restClientOptions = { /** * Optionally override API domain used: - * apiRegion: 'default' | 'bytick' | 'NL' | 'HK' | 'TK', + * apiRegion: 'default' | 'bytick' | 'NL' | 'TK' | 'KZ' | 'HK' | 'GE' | 'UAE' | 'EU' | 'JP', **/ // apiRegion: 'bytick', @@ -22530,13 +22531,14 @@ The following values are currently supported in this option: - `apiRegion: undefined`: if missing or undefined, this SDK will default to the Bybit Global domain `api.bybit.com`. - `apiRegion: "default"`: the Bybit Global domain (same behaviour as above). - `apiRegion: "bytick"`: the alternative Bybit Global domain `api.bytick.com`. -- `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bytick.nl`. +- `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bybit.nl`. - `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit-tr.com`. - `apiRegion: "KZ"`: the dedicated Bybit Kazakhstan domain `api.bybit.kz`. - `apiRegion: "HK"`: the dedicated Bybit HK domain `api.byhkbit.com`. - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. - `apiRegion: "UAE"`: the dedicated Bybit United Arab Emirates domain `api.bybit.ae`. - `apiRegion: "EU"`: the dedicated Bybit EU/EEA domain `api.bybit.eu`. +- `apiRegion: "JP"`: the dedicated Bybit Japan domain `api.manepa.jp`. Testnet uses `api-testnet.manepa.jp`. New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. From def5b3e9974c6a80f2d5ff1edef625abc2c81220 Mon Sep 17 00:00:00 2001 From: tiagosiebler Date: Fri, 4 Sep 2026 12:16:32 +0100 Subject: [PATCH 03/10] fix: update Bybit Turkey API domain --- README.md | 2 +- examples/Rest/rest-v5-custom-url.ts | 2 +- llms.txt | 4 ++-- src/util/requestUtils.ts | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d1951513..d2ef8542 100644 --- a/README.md +++ b/README.md @@ -594,7 +594,7 @@ The following values are currently supported in this option: - `apiRegion: "default"`: the Bybit Global domain (same behaviour as above). - `apiRegion: "bytick"`: the alternative Bybit Global domain `api.bytick.com`. - `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bybit.nl`. -- `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit-tr.com`. +- `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit.tr`. - `apiRegion: "KZ"`: the dedicated Bybit Kazakhstan domain `api.bybit.kz`. - `apiRegion: "HK"`: the dedicated Bybit HK domain `api.byhkbit.com`. - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. diff --git a/examples/Rest/rest-v5-custom-url.ts b/examples/Rest/rest-v5-custom-url.ts index 8e10fe98..a0524985 100644 --- a/examples/Rest/rest-v5-custom-url.ts +++ b/examples/Rest/rest-v5-custom-url.ts @@ -42,7 +42,7 @@ const client = new RestClientV5({ // apiRegion: 'HK', // // - // TK: routes to api.bybit-tr.com (for Turkey users) + // TK: routes to api.bybit.tr (for Turkey users) // apiRegion: 'TK', }); diff --git a/llms.txt b/llms.txt index fb2bcca9..12238059 100644 --- a/llms.txt +++ b/llms.txt @@ -3818,7 +3818,7 @@ import { RestClientV5 } from '../../src/index'; // apiRegion: 'HK', // // -// TK: routes to api.bybit-tr.com (for Turkey users) +// TK: routes to api.bybit.tr (for Turkey users) // apiRegion: 'TK', ================ @@ -22532,7 +22532,7 @@ The following values are currently supported in this option: - `apiRegion: "default"`: the Bybit Global domain (same behaviour as above). - `apiRegion: "bytick"`: the alternative Bybit Global domain `api.bytick.com`. - `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bybit.nl`. -- `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit-tr.com`. +- `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit.tr`. - `apiRegion: "KZ"`: the dedicated Bybit Kazakhstan domain `api.bybit.kz`. - `apiRegion: "HK"`: the dedicated Bybit HK domain `api.byhkbit.com`. - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. diff --git a/src/util/requestUtils.ts b/src/util/requestUtils.ts index 81c8da13..c7106b79 100644 --- a/src/util/requestUtils.ts +++ b/src/util/requestUtils.ts @@ -149,7 +149,7 @@ export function getRestBaseUrl( default: 'https://api.bybit.com', bytick: 'https://api.bytick.com', NL: 'https://api.bybit.nl', - TK: 'https://api.bybit-tr.com', + TK: 'https://api.bybit.tr', KZ: 'https://api.bybit.kz', HK: 'https://api.byhkbit.com', GE: 'https://api.bybitgeorgia.ge', From 44e320c4bc101648971e26658951fc0c142cf6e9 Mon Sep 17 00:00:00 2001 From: tiagosiebler Date: Fri, 4 Sep 2026 12:19:06 +0100 Subject: [PATCH 04/10] fix: update Bybit Hong Kong REST routing incl testnet --- README.md | 2 +- docs/BYBIT_SDK_QUICKSTART_GUIDE.md | 2 ++ examples/Rest/rest-v5-custom-url.ts | 3 ++- llms.txt | 7 +++++-- src/util/BaseRestClient.ts | 3 +++ src/util/requestUtils.ts | 5 ++++- 6 files changed, 17 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d2ef8542..4ceb5be8 100644 --- a/README.md +++ b/README.md @@ -596,7 +596,7 @@ The following values are currently supported in this option: - `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bybit.nl`. - `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit.tr`. - `apiRegion: "KZ"`: the dedicated Bybit Kazakhstan domain `api.bybit.kz`. -- `apiRegion: "HK"`: the dedicated Bybit HK domain `api.byhkbit.com`. +- `apiRegion: "HK"`: the dedicated Bybit Hong Kong domain `api.spark-fintech.com`. The SDK also adds `x-refer-site-id: HKG`. Testnet uses `api-testnet.spark-fintech.com`. - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. - `apiRegion: "UAE"`: the dedicated Bybit United Arab Emirates domain `api.bybit.ae`. - `apiRegion: "EU"`: the dedicated Bybit EU/EEA domain `api.bybit.eu`. diff --git a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md index e391e8f9..8014bf12 100644 --- a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md +++ b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md @@ -1248,6 +1248,8 @@ Supported API region values in this SDK: - `EU` - `JP` +For a Hong Kong account, `apiRegion: 'HK'` selects `api.spark-fintech.com` on mainnet or `api-testnet.spark-fintech.com` on testnet. The SDK adds the required `x-refer-site-id: HKG` header automatically. This is separate from the `siteId` option used for Brazil and Argentina international accounts. + New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. #### Brazil and Argentina international accounts with x-site-id diff --git a/examples/Rest/rest-v5-custom-url.ts b/examples/Rest/rest-v5-custom-url.ts index a0524985..2248d69c 100644 --- a/examples/Rest/rest-v5-custom-url.ts +++ b/examples/Rest/rest-v5-custom-url.ts @@ -38,7 +38,8 @@ const client = new RestClientV5({ // apiRegion: 'NL', // // - // HK: routes to api.byhkbit.com (for Hong Kong users) + // HK: routes to api.spark-fintech.com and adds x-refer-site-id: HKG + // Testnet routes to api-testnet.spark-fintech.com // apiRegion: 'HK', // // diff --git a/llms.txt b/llms.txt index 12238059..dc856c14 100644 --- a/llms.txt +++ b/llms.txt @@ -3814,7 +3814,8 @@ import { RestClientV5 } from '../../src/index'; // apiRegion: 'NL', // // -// HK: routes to api.byhkbit.com (for Hong Kong users) +// HK: routes to api.spark-fintech.com and adds x-refer-site-id: HKG +// Testnet routes to api-testnet.spark-fintech.com // apiRegion: 'HK', // // @@ -12995,6 +12996,8 @@ Supported API region values in this SDK: - `EU` - `JP` +For a Hong Kong account, `apiRegion: 'HK'` selects `api.spark-fintech.com` on mainnet or `api-testnet.spark-fintech.com` on testnet. The SDK adds the required `x-refer-site-id: HKG` header automatically. This is separate from the `siteId` option used for Brazil and Argentina international accounts. + New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. #### Brazil and Argentina international accounts with x-site-id @@ -22534,7 +22537,7 @@ The following values are currently supported in this option: - `apiRegion: "NL"`: the dedicated Bybit Netherlands domain `api.bybit.nl`. - `apiRegion: "TK"`: the dedicated Bybit Turkey domain `api.bybit.tr`. - `apiRegion: "KZ"`: the dedicated Bybit Kazakhstan domain `api.bybit.kz`. -- `apiRegion: "HK"`: the dedicated Bybit HK domain `api.byhkbit.com`. +- `apiRegion: "HK"`: the dedicated Bybit Hong Kong domain `api.spark-fintech.com`. The SDK also adds `x-refer-site-id: HKG`. Testnet uses `api-testnet.spark-fintech.com`. - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. - `apiRegion: "UAE"`: the dedicated Bybit United Arab Emirates domain `api.bybit.ae`. - `apiRegion: "EU"`: the dedicated Bybit EU/EEA domain `api.bybit.eu`. diff --git a/src/util/BaseRestClient.ts b/src/util/BaseRestClient.ts index c1d178d2..26a15c01 100644 --- a/src/util/BaseRestClient.ts +++ b/src/util/BaseRestClient.ts @@ -149,6 +149,9 @@ export default abstract class BaseRestClient { headers: { ...networkOptions.headers, 'x-referer': isEUAPIRegion(this.options) ? APIIDEU : APIID, + ...(this.options.apiRegion === 'HK' + ? { 'x-refer-site-id': 'HKG' } + : undefined), ...(this.options.siteId ? { 'x-site-id': this.options.siteId } : undefined), diff --git a/src/util/requestUtils.ts b/src/util/requestUtils.ts index c7106b79..c36cb3ad 100644 --- a/src/util/requestUtils.ts +++ b/src/util/requestUtils.ts @@ -151,7 +151,7 @@ export function getRestBaseUrl( NL: 'https://api.bybit.nl', TK: 'https://api.bybit.tr', KZ: 'https://api.bybit.kz', - HK: 'https://api.byhkbit.com', + HK: 'https://api.spark-fintech.com', GE: 'https://api.bybitgeorgia.ge', UAE: 'https://api.bybit.ae', EU: 'https://api.bybit.eu', @@ -176,6 +176,9 @@ export function getRestBaseUrl( if (restClientOptions.apiRegion === 'JP') { return 'https://api-testnet.manepa.jp'; } + if (restClientOptions.apiRegion === 'HK') { + return 'https://api-testnet.spark-fintech.com'; + } return exchangeBaseUrls.testnet; } From bdf2688f7e1a513f40a9c06eb46b3aceca0e0d41 Mon Sep 17 00:00:00 2001 From: tiagosiebler Date: Fri, 4 Sep 2026 12:21:11 +0100 Subject: [PATCH 05/10] feat: add Bybit Indonesia REST region --- README.md | 3 ++- docs/BYBIT_SDK_QUICKSTART_GUIDE.md | 1 + examples/Rest/rest-v5-custom-url.ts | 4 ++++ llms.txt | 8 +++++++- src/util/requestUtils.ts | 2 ++ 5 files changed, 16 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4ceb5be8..acea2db7 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,7 @@ const restClientOptions = { /** * Optionally override API domain used: - * apiRegion: 'default' | 'bytick' | 'NL' | 'TK' | 'KZ' | 'HK' | 'GE' | 'UAE' | 'EU' | 'JP', + * apiRegion: 'default' | 'bytick' | 'NL' | 'TK' | 'KZ' | 'HK' | 'GE' | 'UAE' | 'EU' | 'ID' | 'JP', **/ // apiRegion: 'bytick', @@ -600,6 +600,7 @@ The following values are currently supported in this option: - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. - `apiRegion: "UAE"`: the dedicated Bybit United Arab Emirates domain `api.bybit.ae`. - `apiRegion: "EU"`: the dedicated Bybit EU/EEA domain `api.bybit.eu`. +- `apiRegion: "ID"`: the dedicated Bybit Indonesia domain `api.bybit.id`. - `apiRegion: "JP"`: the dedicated Bybit Japan domain `api.manepa.jp`. Testnet uses `api-testnet.manepa.jp`. New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. diff --git a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md index 8014bf12..ddef7a32 100644 --- a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md +++ b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md @@ -1246,6 +1246,7 @@ Supported API region values in this SDK: - `GE` - `UAE` - `EU` +- `ID` - `JP` For a Hong Kong account, `apiRegion: 'HK'` selects `api.spark-fintech.com` on mainnet or `api-testnet.spark-fintech.com` on testnet. The SDK adds the required `x-refer-site-id: HKG` header automatically. This is separate from the `siteId` option used for Brazil and Argentina international accounts. diff --git a/examples/Rest/rest-v5-custom-url.ts b/examples/Rest/rest-v5-custom-url.ts index 2248d69c..dccf5c68 100644 --- a/examples/Rest/rest-v5-custom-url.ts +++ b/examples/Rest/rest-v5-custom-url.ts @@ -45,6 +45,10 @@ const client = new RestClientV5({ // // TK: routes to api.bybit.tr (for Turkey users) // apiRegion: 'TK', + // + // + // ID: routes to api.bybit.id (for Indonesian users) + // apiRegion: 'ID', }); (async () => { diff --git a/llms.txt b/llms.txt index dc856c14..ce397b4d 100644 --- a/llms.txt +++ b/llms.txt @@ -3821,6 +3821,10 @@ import { RestClientV5 } from '../../src/index'; // // TK: routes to api.bybit.tr (for Turkey users) // apiRegion: 'TK', +// +// +// ID: routes to api.bybit.id (for Indonesian users) +// apiRegion: 'ID', ================ File: examples/Rest/rest-v5-next-cursor.ts @@ -12994,6 +12998,7 @@ Supported API region values in this SDK: - `GE` - `UAE` - `EU` +- `ID` - `JP` For a Hong Kong account, `apiRegion: 'HK'` selects `api.spark-fintech.com` on mainnet or `api-testnet.spark-fintech.com` on testnet. The SDK adds the required `x-refer-site-id: HKG` header automatically. This is separate from the `siteId` option used for Brazil and Argentina international accounts. @@ -22179,7 +22184,7 @@ const restClientOptions = { /** * Optionally override API domain used: - * apiRegion: 'default' | 'bytick' | 'NL' | 'TK' | 'KZ' | 'HK' | 'GE' | 'UAE' | 'EU' | 'JP', + * apiRegion: 'default' | 'bytick' | 'NL' | 'TK' | 'KZ' | 'HK' | 'GE' | 'UAE' | 'EU' | 'ID' | 'JP', **/ // apiRegion: 'bytick', @@ -22541,6 +22546,7 @@ The following values are currently supported in this option: - `apiRegion: "GE"`: the dedicated Bybit Georgia domain `api.bybitgeorgia.ge`. - `apiRegion: "UAE"`: the dedicated Bybit United Arab Emirates domain `api.bybit.ae`. - `apiRegion: "EU"`: the dedicated Bybit EU/EEA domain `api.bybit.eu`. +- `apiRegion: "ID"`: the dedicated Bybit Indonesia domain `api.bybit.id`. - `apiRegion: "JP"`: the dedicated Bybit Japan domain `api.manepa.jp`. Testnet uses `api-testnet.manepa.jp`. New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. diff --git a/src/util/requestUtils.ts b/src/util/requestUtils.ts index c36cb3ad..0fd97e9a 100644 --- a/src/util/requestUtils.ts +++ b/src/util/requestUtils.ts @@ -12,6 +12,7 @@ export type APIRegion = | 'GE' | 'UAE' | 'EU' + | 'ID' | 'JP'; export interface RestClientOptions { @@ -155,6 +156,7 @@ export function getRestBaseUrl( GE: 'https://api.bybitgeorgia.ge', UAE: 'https://api.bybit.ae', EU: 'https://api.bybit.eu', + ID: 'https://api.bybit.id', JP: 'https://api.manepa.jp', }; From 8cf3b39c299f9c8e2e51a1456c7fa1c576482d65 Mon Sep 17 00:00:00 2001 From: tiagosiebler Date: Fri, 4 Sep 2026 14:08:07 +0100 Subject: [PATCH 06/10] feat: add WebSocket siteId header support --- README.md | 12 ++++++++-- docs/BYBIT_SDK_QUICKSTART_GUIDE.md | 12 ++++++++-- llms.txt | 35 ++++++++++++++++++++++++++---- src/types/websockets/ws-general.ts | 11 ++++++++++ src/util/BaseWSClient.ts | 21 +++++++++++++----- src/util/requestUtils.ts | 1 + 6 files changed, 78 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index acea2db7..3d6bba56 100644 --- a/README.md +++ b/README.md @@ -610,18 +610,26 @@ New regions will be supported when they become available in the Bybit API. If yo Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: ```typescript -import { RestClientV5 } from 'bybit-api'; +import { RestClientV5, WebsocketClient } from 'bybit-api'; const client = new RestClientV5({ key: process.env.BYBIT_API_KEY!, secret: process.env.BYBIT_API_SECRET!, siteId: 'BRA_BTL', }); + +const ws = new WebsocketClient({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); ``` Use `siteId: 'ARG_BTL'` for an Argentina international account. -The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). +The REST client sends `x-site-id` on every request. In Node.js, `WebsocketClient` and `WebsocketAPIClient` send it during the WebSocket handshake using the same top-level `siteId` option. Both use the global Bybit endpoint. Browser WebSocket connections cannot set custom handshake headers. + +See Bybit's [WebSocket connection guidance](https://bybit-exchange.github.io/docs/v5/ws/connect) for the regional requirement. ### REST API Usage with Bybit EU diff --git a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md index ddef7a32..a071bbca 100644 --- a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md +++ b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md @@ -1258,18 +1258,26 @@ New API regions will be supported as they become available. If you're looking fo Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: ```typescript -import { RestClientV5 } from 'bybit-api'; +import { RestClientV5, WebsocketClient } from 'bybit-api'; const client = new RestClientV5({ key: process.env.BYBIT_API_KEY!, secret: process.env.BYBIT_API_SECRET!, siteId: 'BRA_BTL', }); + +const ws = new WebsocketClient({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); ``` Use `siteId: 'ARG_BTL'` for an Argentina international account. -The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). +The REST client sends `x-site-id` on every request. In Node.js, `WebsocketClient` and `WebsocketAPIClient` send it during the WebSocket handshake using the same top-level `siteId` option. Both use the global Bybit endpoint. Browser WebSocket connections cannot set custom handshake headers. + +See Bybit's [WebSocket connection guidance](https://bybit-exchange.github.io/docs/v5/ws/connect) for the regional requirement. You can also pass `baseUrl` for a custom REST API domain, or `wsUrl` for a custom WebSocket URL when needed. diff --git a/llms.txt b/llms.txt index ce397b4d..00f26b35 100644 --- a/llms.txt +++ b/llms.txt @@ -13010,18 +13010,26 @@ New API regions will be supported as they become available. If you're looking fo Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: ```typescript -import { RestClientV5 } from 'bybit-api'; +import { RestClientV5, WebsocketClient } from 'bybit-api'; const client = new RestClientV5({ key: process.env.BYBIT_API_KEY!, secret: process.env.BYBIT_API_SECRET!, siteId: 'BRA_BTL', }); + +const ws = new WebsocketClient({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); ``` Use `siteId: 'ARG_BTL'` for an Argentina international account. -The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). +The REST client sends `x-site-id` on every request. In Node.js, `WebsocketClient` and `WebsocketAPIClient` send it during the WebSocket handshake using the same top-level `siteId` option. Both use the global Bybit endpoint. Browser WebSocket connections cannot set custom handshake headers. + +See Bybit's [WebSocket connection guidance](https://bybit-exchange.github.io/docs/v5/ws/connect) for the regional requirement. You can also pass `baseUrl` for a custom REST API domain, or `wsUrl` for a custom WebSocket URL when needed. @@ -15074,6 +15082,17 @@ export interface WSClientConfigurableOptions { /** Delay in milliseconds before respawning the connection */ reconnectTimeout?: number; + /** + * Site ID sent as `x-site-id` during the Node.js WebSocket handshake. + * Required for eligible international accounts that use the global stream domain, + * e.g. `BRA_BTL` for Brazil or `ARG_BTL` for Argentina. + */ + siteId?: string; + + /** + * REST options reused for WebSocket routing. + * `restOptions.siteId` is retained as a fallback; prefer top-level `siteId`. + */ restOptions?: RestClientOptions; requestOptions?: AxiosRequestConfig; @@ -22556,18 +22575,26 @@ New regions will be supported when they become available in the Bybit API. If yo Brazil and Argentina international accounts use the global REST API domain with a site-specific request header. Pass the matching value through the REST client's `siteId` option: ```typescript -import { RestClientV5 } from 'bybit-api'; +import { RestClientV5, WebsocketClient } from 'bybit-api'; const client = new RestClientV5({ key: process.env.BYBIT_API_KEY!, secret: process.env.BYBIT_API_SECRET!, siteId: 'BRA_BTL', }); + +const ws = new WebsocketClient({ + key: process.env.BYBIT_API_KEY!, + secret: process.env.BYBIT_API_SECRET!, + siteId: 'BRA_BTL', +}); ``` Use `siteId: 'ARG_BTL'` for an Argentina international account. -The `siteId` option currently configures REST requests only. Bybit documents `x-site-id` separately for [mainnet WebSocket connections](https://bybit-exchange.github.io/docs/v5/ws/connect). +The REST client sends `x-site-id` on every request. In Node.js, `WebsocketClient` and `WebsocketAPIClient` send it during the WebSocket handshake using the same top-level `siteId` option. Both use the global Bybit endpoint. Browser WebSocket connections cannot set custom handshake headers. + +See Bybit's [WebSocket connection guidance](https://bybit-exchange.github.io/docs/v5/ws/connect) for the regional requirement. ### REST API Usage with Bybit EU diff --git a/src/types/websockets/ws-general.ts b/src/types/websockets/ws-general.ts index 14eb46c4..2f56b28a 100644 --- a/src/types/websockets/ws-general.ts +++ b/src/types/websockets/ws-general.ts @@ -120,6 +120,17 @@ export interface WSClientConfigurableOptions { /** Delay in milliseconds before respawning the connection */ reconnectTimeout?: number; + /** + * Site ID sent as `x-site-id` during the Node.js WebSocket handshake. + * Required for eligible international accounts that use the global stream domain, + * e.g. `BRA_BTL` for Brazil or `ARG_BTL` for Argentina. + */ + siteId?: string; + + /** + * REST options reused for WebSocket routing. + * `restOptions.siteId` is retained as a fallback; prefer top-level `siteId`. + */ restOptions?: RestClientOptions; requestOptions?: AxiosRequestConfig; diff --git a/src/util/BaseWSClient.ts b/src/util/BaseWSClient.ts index 0e6db8a2..52f7bfc5 100644 --- a/src/util/BaseWSClient.ts +++ b/src/util/BaseWSClient.ts @@ -1,6 +1,7 @@ /* eslint-disable max-len */ /* eslint-disable @typescript-eslint/no-explicit-any */ import EventEmitter from 'events'; +import type { ClientRequestArgs } from 'http'; import WebSocket from 'isomorphic-ws'; import { @@ -726,12 +727,20 @@ export abstract class BaseWebsocketClient< const legacyAgent = (this.options.requestOptions as any)?.agent; const { protocols = [], ...wsOptions } = wsOptionsConfig; - - // Merge legacy agent if wsOptions doesn't have one - const finalWsOptions = - !wsOptions.agent && legacyAgent - ? { ...wsOptions, agent: legacyAgent } - : wsOptions; + const siteId = this.options.siteId ?? this.options.restOptions?.siteId; + + const finalWsOptions = { + ...wsOptions, + ...(!wsOptions.agent && legacyAgent ? { agent: legacyAgent } : undefined), + ...(siteId + ? { + headers: { + ...wsOptions.headers, + 'x-site-id': siteId, + }, + } + : undefined), + } as WebSocket.ClientOptions | ClientRequestArgs; const ws: WebSocket & { wsKey?: string } = new WebSocket( url, diff --git a/src/util/requestUtils.ts b/src/util/requestUtils.ts index 0fd97e9a..1b419c07 100644 --- a/src/util/requestUtils.ts +++ b/src/util/requestUtils.ts @@ -80,6 +80,7 @@ export interface RestClientOptions { /** * Site ID sent as the `x-site-id` header on every REST request. + * WebSocket clients expose the same top-level `siteId` option. * Required for eligible international accounts that use the global API domain, * e.g. `BRA_BTL` for Brazil or `ARG_BTL` for Argentina. * @see https://bybit-exchange.github.io/docs/v5/guide#authentication From 2890955b0eef98b13b54b2c6c930901fc060d5ba Mon Sep 17 00:00:00 2001 From: "Tiago Siebler @ Siebly.io" Date: Fri, 4 Sep 2026 14:24:39 +0100 Subject: [PATCH 07/10] feat: add regional WebSocket routing --- README.md | 55 +++++++++++---- docs/BYBIT_SDK_QUICKSTART_GUIDE.md | 32 ++++++--- llms.txt | 97 ++++++++++++++++++++------- src/types/websockets/ws-general.ts | 12 +++- src/util/BaseWSClient.ts | 9 ++- src/util/websockets/websocket-util.ts | 72 +++++++++++--------- 6 files changed, 195 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index 3d6bba56..ec6fc8e0 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ Professional Node.js, JavaScript & TypeScript SDK for the Bybit REST APIs, WebSo ## Bybit EU and Other Regions - [`apiRegion` and `x-site-id`](#bybit-eu-and-other-regions-apiregion-and-x-site-id) -- [REST API Usage with Bybit EU](#rest-api-usage-with-bybit-eu) +- [REST and WebSocket API Usage with Bybit EU](#rest-and-websocket-api-usage-with-bybit-eu) ## Additional Features @@ -361,6 +361,12 @@ const wsConfig = { /** Delay in milliseconds before respawning the connection */ // reconnectTimeout: 500, + /** Select WebSocket routing using the same region values as REST */ + // apiRegion: 'TK', + + /** Add x-site-id for an eligible Brazil or Argentina international account */ + // siteId: 'BRA_BTL', + // override which URL to use for websocket connections // wsUrl: 'wss://stream.bytick.com/realtime' @@ -572,21 +578,21 @@ Important: do not subscribe to the same topics on both clients or you will recei ## Bybit EU and Other Regions: apiRegion and x-site-id -Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: +Bybit uses two regional API access models. Use the configuration that matches the site where your account is registered: -| Account setup | REST API endpoint | SDK configuration | -| --- | --- | --- | -| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | -| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | -| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | +| Account setup | REST API endpoint | WebSocket endpoint | SDK configuration | +| --- | --- | --- | --- | +| Account with a dedicated regional domain | Matching regional API domain | Regional mainnet stream when Bybit lists one, otherwise the global stream | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'ARG_BTL'` | -`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. +`apiRegion` selects the regional REST domain and, where Bybit lists one, the regional mainnet WebSocket domain. `siteId` keeps the default global domains and adds the `x-site-id` header to REST requests and Node.js WebSocket handshakes. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. -### Dedicated Regional REST API Domains with apiRegion +### Dedicated Regional API Domains with apiRegion -By default, this Node.js, JavaScript & TypeScript SDK uses the Bybit Global API & WebSocket domains. For regions where Bybit has dedicated regional domains, including the alternative Bybit Global domain (bytick), these can be configured in the REST Client using the `apiRegion` property. +By default, this Node.js, JavaScript & TypeScript SDK uses the Bybit Global API and WebSocket domains. For regions where Bybit has dedicated regional domains, including the alternative Bybit Global domain (bytick), pass `apiRegion` directly to the REST or WebSocket client. The following values are currently supported in this option: @@ -603,6 +609,24 @@ The following values are currently supported in this option: - `apiRegion: "ID"`: the dedicated Bybit Indonesia domain `api.bybit.id`. - `apiRegion: "JP"`: the dedicated Bybit Japan domain `api.manepa.jp`. Testnet uses `api-testnet.manepa.jp`. +For WebSocket clients, the same option selects these mainnet stream domains: + +| `apiRegion` | WebSocket domain | +| --- | --- | +| `TK` | `stream.bybit.tr` | +| `KZ` | `stream.bybit.kz` | +| `HK` | `stream.spark-fintech.com` | +| `GE` | `stream.bybitgeorgia.ge` | +| `ID` | `stream.bybit.id` | +| `JP` | `stream.manepa.jp` | + +For `default`, `bytick`, `NL`, `UAE`, and `EU`, WebSocket connections continue to use the global stream because Bybit does not list a dedicated V5 trading stream for those values. This means `apiRegion: 'EU'` selects `api.bybit.eu` for REST and keeps `stream.bybit.com` for WebSocket. Testnet WebSocket connections use `stream-testnet.bybit.com`. For Hong Kong mainnet WebSocket connections, the SDK also adds `x-refer-site-id: HKG` automatically. + +```typescript +const ws = new WebsocketClient({ apiRegion: 'TK' }); +ws.subscribeV5('tickers.BTCUSDT', 'linear'); +``` + New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. ### Brazil and Argentina International Accounts with x-site-id @@ -631,14 +655,14 @@ The REST client sends `x-site-id` on every request. In Node.js, `WebsocketClient See Bybit's [WebSocket connection guidance](https://bybit-exchange.github.io/docs/v5/ws/connect) for the regional requirement. -### REST API Usage with Bybit EU +### REST and WebSocket API Usage with Bybit EU -Below is an example for using this Node.js, TypeScript & JavaScript SDK for Bybit's APIs, using an account registered on the Bybit EU domain: +Below is an example for using REST and WebSocket APIs with an account registered on Bybit EU: ```typescript -const { RestClientV5 } = require('bybit-api'); +const { RestClientV5, WebsocketClient } = require('bybit-api'); // or -// import { RestClientV5 } from 'bybit-api'; +// import { RestClientV5, WebsocketClient } from 'bybit-api'; const client = new RestClientV5({ key: API_KEY, @@ -656,6 +680,9 @@ client .catch((err) => { console.error('getAccountInfo error: ', err); }); + +const ws = new WebsocketClient({ apiRegion: 'EU' }); +ws.subscribeV5('tickers.BTCUSDT', 'linear'); ``` --- diff --git a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md index a071bbca..d8463149 100644 --- a/docs/BYBIT_SDK_QUICKSTART_GUIDE.md +++ b/docs/BYBIT_SDK_QUICKSTART_GUIDE.md @@ -1209,23 +1209,23 @@ ws.subscribeV5(['order', 'execution', 'position', 'wallet'], 'linear'); Do not combine `testnet: true` with `demoTrading: true`. Bybit's demo trading docs also note that WebSocket API commands are not supported in demo trading, so use REST API demo trading or private demo streams for demo workflows, and use testnet for WebSocket API command testing. -### Regional REST API access: apiRegion and x-site-id +### Regional REST and WebSocket API access: apiRegion and x-site-id -Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: +Bybit uses two regional API access models. Use the configuration that matches the site where your account is registered: -| Account setup | REST API endpoint | SDK configuration | -| --- | --- | --- | -| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | -| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | -| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | +| Account setup | REST API endpoint | WebSocket endpoint | SDK configuration | +| --- | --- | --- | --- | +| Account with a dedicated regional domain | Matching regional API domain | Regional mainnet stream when Bybit lists one, otherwise the global stream | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'ARG_BTL'` | -`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. +`apiRegion` selects the regional REST domain and, where Bybit lists one, the regional mainnet WebSocket domain. `siteId` keeps the default global domains and adds the `x-site-id` header to REST requests and Node.js WebSocket handshakes. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. #### Dedicated regional domains with apiRegion -By default, REST API calls use the global Bybit domain. If your account belongs to a regional Bybit domain, set `apiRegion`: +By default, REST and WebSocket clients use the global Bybit domains. If your account belongs to a regional Bybit domain, set `apiRegion` directly on each client: ```typescript const client = new RestClientV5({ @@ -1233,6 +1233,9 @@ const client = new RestClientV5({ secret: process.env.BYBIT_API_SECRET!, apiRegion: 'EU', }); + +const ws = new WebsocketClient({ apiRegion: 'EU' }); +ws.subscribeV5('tickers.BTCUSDT', 'linear'); ``` Supported API region values in this SDK: @@ -1251,6 +1254,17 @@ Supported API region values in this SDK: For a Hong Kong account, `apiRegion: 'HK'` selects `api.spark-fintech.com` on mainnet or `api-testnet.spark-fintech.com` on testnet. The SDK adds the required `x-refer-site-id: HKG` header automatically. This is separate from the `siteId` option used for Brazil and Argentina international accounts. +On WebSocket clients, these mainnet routes are selected automatically: + +- `TK`: `stream.bybit.tr` +- `KZ`: `stream.bybit.kz` +- `HK`: `stream.spark-fintech.com`, with `x-refer-site-id: HKG` +- `GE`: `stream.bybitgeorgia.ge` +- `ID`: `stream.bybit.id` +- `JP`: `stream.manepa.jp` + +For `default`, `bytick`, `NL`, `UAE`, and `EU`, WebSocket connections continue to use the global stream because Bybit does not list a dedicated V5 trading stream for those values. This means `apiRegion: 'EU'` selects `api.bybit.eu` for REST and keeps `stream.bybit.com` for WebSocket. Testnet WebSocket connections use `stream-testnet.bybit.com`. + New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. #### Brazil and Argentina international accounts with x-site-id diff --git a/llms.txt b/llms.txt index 00f26b35..3cc2d306 100644 --- a/llms.txt +++ b/llms.txt @@ -12961,23 +12961,23 @@ ws.subscribeV5(['order', 'execution', 'position', 'wallet'], 'linear'); Do not combine `testnet: true` with `demoTrading: true`. Bybit's demo trading docs also note that WebSocket API commands are not supported in demo trading, so use REST API demo trading or private demo streams for demo workflows, and use testnet for WebSocket API command testing. -### Regional REST API access: apiRegion and x-site-id +### Regional REST and WebSocket API access: apiRegion and x-site-id -Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: +Bybit uses two regional API access models. Use the configuration that matches the site where your account is registered: -| Account setup | REST API endpoint | SDK configuration | -| --- | --- | --- | -| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | -| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | -| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | +| Account setup | REST API endpoint | WebSocket endpoint | SDK configuration | +| --- | --- | --- | --- | +| Account with a dedicated regional domain | Matching regional API domain | Regional mainnet stream when Bybit lists one, otherwise the global stream | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'ARG_BTL'` | -`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. +`apiRegion` selects the regional REST domain and, where Bybit lists one, the regional mainnet WebSocket domain. `siteId` keeps the default global domains and adds the `x-site-id` header to REST requests and Node.js WebSocket handshakes. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. #### Dedicated regional domains with apiRegion -By default, REST API calls use the global Bybit domain. If your account belongs to a regional Bybit domain, set `apiRegion`: +By default, REST and WebSocket clients use the global Bybit domains. If your account belongs to a regional Bybit domain, set `apiRegion` directly on each client: ```typescript const client = new RestClientV5({ @@ -12985,6 +12985,9 @@ const client = new RestClientV5({ secret: process.env.BYBIT_API_SECRET!, apiRegion: 'EU', }); + +const ws = new WebsocketClient({ apiRegion: 'EU' }); +ws.subscribeV5('tickers.BTCUSDT', 'linear'); ``` Supported API region values in this SDK: @@ -13003,6 +13006,17 @@ Supported API region values in this SDK: For a Hong Kong account, `apiRegion: 'HK'` selects `api.spark-fintech.com` on mainnet or `api-testnet.spark-fintech.com` on testnet. The SDK adds the required `x-refer-site-id: HKG` header automatically. This is separate from the `siteId` option used for Brazil and Argentina international accounts. +On WebSocket clients, these mainnet routes are selected automatically: + +- `TK`: `stream.bybit.tr` +- `KZ`: `stream.bybit.kz` +- `HK`: `stream.spark-fintech.com`, with `x-refer-site-id: HKG` +- `GE`: `stream.bybitgeorgia.ge` +- `ID`: `stream.bybit.id` +- `JP`: `stream.manepa.jp` + +For `default`, `bytick`, `NL`, `UAE`, and `EU`, WebSocket connections continue to use the global stream because Bybit does not list a dedicated V5 trading stream for those values. This means `apiRegion: 'EU'` selects `api.bybit.eu` for REST and keeps `stream.bybit.com` for WebSocket. Testnet WebSocket connections use `stream-testnet.bybit.com`. + New API regions will be supported as they become available. If you're looking for a region not yet supported, please get in touch. #### Brazil and Argentina international accounts with x-site-id @@ -15082,6 +15096,13 @@ export interface WSClientConfigurableOptions { /** Delay in milliseconds before respawning the connection */ reconnectTimeout?: number; + /** + * Select WebSocket routing with the same region values as REST. Uses a + * dedicated mainnet stream when Bybit documents one for that region. + * Top-level `apiRegion` takes precedence over `restOptions.apiRegion`. + */ + apiRegion?: APIRegion; + /** * Site ID sent as `x-site-id` during the Node.js WebSocket handshake. * Required for eligible international accounts that use the global stream domain, @@ -15091,7 +15112,8 @@ export interface WSClientConfigurableOptions { /** * REST options reused for WebSocket routing. - * `restOptions.siteId` is retained as a fallback; prefer top-level `siteId`. + * Regional and site ID values are retained as fallbacks; prefer the matching + * top-level `apiRegion` and `siteId` options. */ restOptions?: RestClientOptions; requestOptions?: AxiosRequestConfig; @@ -22054,7 +22076,7 @@ Professional Node.js, JavaScript & TypeScript SDK for the Bybit REST APIs, WebSo ## Bybit EU and Other Regions - [`apiRegion` and `x-site-id`](#bybit-eu-and-other-regions-apiregion-and-x-site-id) -- [REST API Usage with Bybit EU](#rest-api-usage-with-bybit-eu) +- [REST and WebSocket API Usage with Bybit EU](#rest-and-websocket-api-usage-with-bybit-eu) ## Additional Features @@ -22326,6 +22348,12 @@ const wsConfig = { /** Delay in milliseconds before respawning the connection */ // reconnectTimeout: 500, + /** Select WebSocket routing using the same region values as REST */ + // apiRegion: 'TK', + + /** Add x-site-id for an eligible Brazil or Argentina international account */ + // siteId: 'BRA_BTL', + // override which URL to use for websocket connections // wsUrl: 'wss://stream.bytick.com/realtime' @@ -22537,21 +22565,21 @@ Important: do not subscribe to the same topics on both clients or you will recei ## Bybit EU and Other Regions: apiRegion and x-site-id -Bybit uses two regional REST API access models. Use the configuration that matches the site where your account is registered: +Bybit uses two regional API access models. Use the configuration that matches the site where your account is registered: -| Account setup | REST API endpoint | SDK configuration | -| --- | --- | --- | -| Account with a dedicated regional domain | The matching regional domain | Set `apiRegion` | -| Brazil international account | `api.bybit.com` | Set `siteId: 'BRA_BTL'` | -| Argentina international account | `api.bybit.com` | Set `siteId: 'ARG_BTL'` | +| Account setup | REST API endpoint | WebSocket endpoint | SDK configuration | +| --- | --- | --- | --- | +| Account with a dedicated regional domain | Matching regional API domain | Regional mainnet stream when Bybit lists one, otherwise the global stream | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'ARG_BTL'` | -`apiRegion` changes the REST API domain. `siteId` keeps the default global domain and adds the `x-site-id` header to every REST request. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. +`apiRegion` selects the regional REST domain and, where Bybit lists one, the regional mainnet WebSocket domain. `siteId` keeps the default global domains and adds the `x-site-id` header to REST requests and Node.js WebSocket handshakes. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. -### Dedicated Regional REST API Domains with apiRegion +### Dedicated Regional API Domains with apiRegion -By default, this Node.js, JavaScript & TypeScript SDK uses the Bybit Global API & WebSocket domains. For regions where Bybit has dedicated regional domains, including the alternative Bybit Global domain (bytick), these can be configured in the REST Client using the `apiRegion` property. +By default, this Node.js, JavaScript & TypeScript SDK uses the Bybit Global API and WebSocket domains. For regions where Bybit has dedicated regional domains, including the alternative Bybit Global domain (bytick), pass `apiRegion` directly to the REST or WebSocket client. The following values are currently supported in this option: @@ -22568,6 +22596,24 @@ The following values are currently supported in this option: - `apiRegion: "ID"`: the dedicated Bybit Indonesia domain `api.bybit.id`. - `apiRegion: "JP"`: the dedicated Bybit Japan domain `api.manepa.jp`. Testnet uses `api-testnet.manepa.jp`. +For WebSocket clients, the same option selects these mainnet stream domains: + +| `apiRegion` | WebSocket domain | +| --- | --- | +| `TK` | `stream.bybit.tr` | +| `KZ` | `stream.bybit.kz` | +| `HK` | `stream.spark-fintech.com` | +| `GE` | `stream.bybitgeorgia.ge` | +| `ID` | `stream.bybit.id` | +| `JP` | `stream.manepa.jp` | + +For `default`, `bytick`, `NL`, `UAE`, and `EU`, WebSocket connections continue to use the global stream because Bybit does not list a dedicated V5 trading stream for those values. This means `apiRegion: 'EU'` selects `api.bybit.eu` for REST and keeps `stream.bybit.com` for WebSocket. Testnet WebSocket connections use `stream-testnet.bybit.com`. For Hong Kong mainnet WebSocket connections, the SDK also adds `x-refer-site-id: HKG` automatically. + +```typescript +const ws = new WebsocketClient({ apiRegion: 'TK' }); +ws.subscribeV5('tickers.BTCUSDT', 'linear'); +``` + New regions will be supported when they become available in the Bybit API. If you notice any regions that have not been added yet, please open a new issue on GitHub. ### Brazil and Argentina International Accounts with x-site-id @@ -22596,14 +22642,14 @@ The REST client sends `x-site-id` on every request. In Node.js, `WebsocketClient See Bybit's [WebSocket connection guidance](https://bybit-exchange.github.io/docs/v5/ws/connect) for the regional requirement. -### REST API Usage with Bybit EU +### REST and WebSocket API Usage with Bybit EU -Below is an example for using this Node.js, TypeScript & JavaScript SDK for Bybit's APIs, using an account registered on the Bybit EU domain: +Below is an example for using REST and WebSocket APIs with an account registered on Bybit EU: ```typescript -const { RestClientV5 } = require('bybit-api'); +const { RestClientV5, WebsocketClient } = require('bybit-api'); // or -// import { RestClientV5 } from 'bybit-api'; +// import { RestClientV5, WebsocketClient } from 'bybit-api'; const client = new RestClientV5({ key: API_KEY, @@ -22621,6 +22667,9 @@ client .catch((err) => { console.error('getAccountInfo error: ', err); }); + +const ws = new WebsocketClient({ apiRegion: 'EU' }); +ws.subscribeV5('tickers.BTCUSDT', 'linear'); ``` --- diff --git a/src/types/websockets/ws-general.ts b/src/types/websockets/ws-general.ts index 2f56b28a..286ff8aa 100644 --- a/src/types/websockets/ws-general.ts +++ b/src/types/websockets/ws-general.ts @@ -2,7 +2,7 @@ import { AxiosRequestConfig } from 'axios'; import type { ClientRequestArgs } from 'http'; import WebSocket from 'isomorphic-ws'; -import { RestClientOptions, WS_KEY_MAP } from '../../util'; +import { APIRegion, RestClientOptions, WS_KEY_MAP } from '../../util'; /** For spot markets, spotV3 is recommended */ export type APIMarket = 'v5'; @@ -120,6 +120,13 @@ export interface WSClientConfigurableOptions { /** Delay in milliseconds before respawning the connection */ reconnectTimeout?: number; + /** + * Select WebSocket routing with the same region values as REST. Uses a + * dedicated mainnet stream when Bybit documents one for that region. + * Top-level `apiRegion` takes precedence over `restOptions.apiRegion`. + */ + apiRegion?: APIRegion; + /** * Site ID sent as `x-site-id` during the Node.js WebSocket handshake. * Required for eligible international accounts that use the global stream domain, @@ -129,7 +136,8 @@ export interface WSClientConfigurableOptions { /** * REST options reused for WebSocket routing. - * `restOptions.siteId` is retained as a fallback; prefer top-level `siteId`. + * Regional and site ID values are retained as fallbacks; prefer the matching + * top-level `apiRegion` and `siteId` options. */ restOptions?: RestClientOptions; requestOptions?: AxiosRequestConfig; diff --git a/src/util/BaseWSClient.ts b/src/util/BaseWSClient.ts index 52f7bfc5..fad405a5 100644 --- a/src/util/BaseWSClient.ts +++ b/src/util/BaseWSClient.ts @@ -728,15 +728,20 @@ export abstract class BaseWebsocketClient< const { protocols = [], ...wsOptions } = wsOptionsConfig; const siteId = this.options.siteId ?? this.options.restOptions?.siteId; + const apiRegion = + this.options.apiRegion ?? this.options.restOptions?.apiRegion; const finalWsOptions = { ...wsOptions, ...(!wsOptions.agent && legacyAgent ? { agent: legacyAgent } : undefined), - ...(siteId + ...(siteId || apiRegion === 'HK' ? { headers: { ...wsOptions.headers, - 'x-site-id': siteId, + ...(apiRegion === 'HK' + ? { 'x-refer-site-id': 'HKG' } + : undefined), + ...(siteId ? { 'x-site-id': siteId } : undefined), }, } : undefined), diff --git a/src/util/websockets/websocket-util.ts b/src/util/websockets/websocket-util.ts index bfa6975f..1f09d21e 100644 --- a/src/util/websockets/websocket-util.ts +++ b/src/util/websockets/websocket-util.ts @@ -9,6 +9,7 @@ import { } from '../../types'; import { WSAPIRequest } from '../../types/websockets/ws-api'; import { DefaultLogger } from '../logger'; +import { APIRegion } from '../requestUtils'; import { neverGuard } from '../typeGuards'; export const WS_KEY_MAP = { @@ -216,6 +217,15 @@ export const WS_BASE_URL_MAP: Record< }, }; +const WS_MAINNET_REGION_DOMAIN_MAP: Partial> = { + TK: 'stream.bybit.tr', + KZ: 'stream.bybit.kz', + HK: 'stream.spark-fintech.com', + GE: 'stream.bybitgeorgia.ge', + ID: 'stream.bybit.id', + JP: 'stream.manepa.jp', +}; + export function isPrivateWsTopic(topic: string): boolean { return PRIVATE_TOPICS.includes(topic); } @@ -279,56 +289,56 @@ export function getWsUrl( const isDemoTrading = wsClientOptions.demoTrading; const isTestnet = wsClientOptions.testnet; const networkKey = isTestnet ? 'testnet' : 'livenet'; - const isJP = wsClientOptions.restOptions?.apiRegion === 'JP'; + const apiRegion = + wsClientOptions.apiRegion ?? wsClientOptions.restOptions?.apiRegion; + const regionalDomain = + !isTestnet && apiRegion + ? WS_MAINNET_REGION_DOMAIN_MAP[apiRegion] + : undefined; + + const resolveUrl = (path: string, defaultUrl: string): string => { + return regionalDomain ? `wss://${regionalDomain}${path}` : defaultUrl; + }; switch (wsKey) { case WS_KEY_MAP.v5Private: { if (isDemoTrading) { return DEMO_TRADING_ENDPOINT; } - if (isJP) { - const base = isTestnet - ? 'stream-testnet.manepa.jp' - : 'stream.manepa.jp'; - return `wss://${base}/v5/private`; - } - return WS_BASE_URL_MAP.v5.private[networkKey]; + return resolveUrl('/v5/private', WS_BASE_URL_MAP.v5.private[networkKey]); } case WS_KEY_MAP.v5PrivateTrade: { if (isDemoTrading) { return DEMO_TRADING_ENDPOINT; } - if (isJP) { - const base = isTestnet - ? 'stream-testnet.manepa.jp' - : 'stream.manepa.jp'; - return `wss://${base}/v5/trade`; - } - return WS_BASE_URL_MAP[wsKey].private[networkKey]; + return resolveUrl( + '/v5/trade', + WS_BASE_URL_MAP[wsKey].private[networkKey], + ); } case WS_KEY_MAP.v5SpotPublic: { - if (isJP) { - return 'wss://stream.manepa.jp/v5/public/spot'; - } - return WS_BASE_URL_MAP.v5SpotPublic.public[networkKey]; + return resolveUrl( + '/v5/public/spot', + WS_BASE_URL_MAP.v5SpotPublic.public[networkKey], + ); } case WS_KEY_MAP.v5LinearPublic: { - if (isJP) { - return 'wss://stream.manepa.jp/v5/public/linear'; - } - return WS_BASE_URL_MAP.v5LinearPublic.public[networkKey]; + return resolveUrl( + '/v5/public/linear', + WS_BASE_URL_MAP.v5LinearPublic.public[networkKey], + ); } case WS_KEY_MAP.v5InversePublic: { - if (isJP) { - return 'wss://stream.manepa.jp/v5/public/inverse'; - } - return WS_BASE_URL_MAP.v5InversePublic.public[networkKey]; + return resolveUrl( + '/v5/public/inverse', + WS_BASE_URL_MAP.v5InversePublic.public[networkKey], + ); } case WS_KEY_MAP.v5OptionPublic: { - if (isJP) { - return 'wss://stream.manepa.jp/v5/public/option'; - } - return WS_BASE_URL_MAP.v5OptionPublic.public[networkKey]; + return resolveUrl( + '/v5/public/option', + WS_BASE_URL_MAP.v5OptionPublic.public[networkKey], + ); } default: { logger.error('getWsUrl(): Unhandled wsKey: ', { From a5d48256a1d2de9f9b5aa55cf9ae28067bddd4fa Mon Sep 17 00:00:00 2001 From: "Tiago Siebler @ Siebly.io" Date: Fri, 4 Sep 2026 14:27:07 +0100 Subject: [PATCH 08/10] docs: refresh regional API examples --- examples/Rest/rest-v5-custom-url.ts | 38 ++++++++++++++++++++++++++--- llms.txt | 38 ++++++++++++++++++++++++++--- 2 files changed, 68 insertions(+), 8 deletions(-) diff --git a/examples/Rest/rest-v5-custom-url.ts b/examples/Rest/rest-v5-custom-url.ts index dccf5c68..3fc974be 100644 --- a/examples/Rest/rest-v5-custom-url.ts +++ b/examples/Rest/rest-v5-custom-url.ts @@ -21,7 +21,8 @@ const client = new RestClientV5({ // /** * - * There are also predefined API regions, which you can easily use with the "apiRegion" property: + * Predefined API regions are available through the `apiRegion` property. + * Choose the region where your Bybit account is registered: * */ // @@ -34,21 +35,50 @@ const client = new RestClientV5({ // apiRegion: 'bytick', // // - // NL: routes to api.bybit.nl (for Netherland users) + // NL: routes to api.bybit.nl (for Netherlands users) // apiRegion: 'NL', // // + // TK: routes to api.bybit.tr (for Turkey users) + // apiRegion: 'TK', + // + // + // KZ: routes to api.bybit.kz (for Kazakhstan users) + // apiRegion: 'KZ', + // + // // HK: routes to api.spark-fintech.com and adds x-refer-site-id: HKG // Testnet routes to api-testnet.spark-fintech.com // apiRegion: 'HK', // // - // TK: routes to api.bybit.tr (for Turkey users) - // apiRegion: 'TK', + // GE: routes to api.bybitgeorgia.ge (for Georgia users) + // apiRegion: 'GE', + // + // + // UAE: routes to api.bybit.ae (for United Arab Emirates users) + // apiRegion: 'UAE', + // + // + // EU: routes to api.bybit.eu (for EU and EEA users) + // apiRegion: 'EU', // // // ID: routes to api.bybit.id (for Indonesian users) // apiRegion: 'ID', + // + // + // JP: routes to api.manepa.jp (for Japan users) + // Testnet routes to api-testnet.manepa.jp + // apiRegion: 'JP', + // + // + /** + * Brazil and Argentina international accounts use the global API domain + * with an x-site-id header. Choose the site ID for your account: + */ + // siteId: 'BRA_BTL', + // siteId: 'ARG_BTL', }); (async () => { diff --git a/llms.txt b/llms.txt index 3cc2d306..bc407da2 100644 --- a/llms.txt +++ b/llms.txt @@ -3797,7 +3797,8 @@ import { RestClientV5 } from '../../src/index'; // /** * - * There are also predefined API regions, which you can easily use with the "apiRegion" property: + * Predefined API regions are available through the `apiRegion` property. + * Choose the region where your Bybit account is registered: * */ // @@ -3810,21 +3811,50 @@ import { RestClientV5 } from '../../src/index'; // apiRegion: 'bytick', // // -// NL: routes to api.bybit.nl (for Netherland users) +// NL: routes to api.bybit.nl (for Netherlands users) // apiRegion: 'NL', // // +// TK: routes to api.bybit.tr (for Turkey users) +// apiRegion: 'TK', +// +// +// KZ: routes to api.bybit.kz (for Kazakhstan users) +// apiRegion: 'KZ', +// +// // HK: routes to api.spark-fintech.com and adds x-refer-site-id: HKG // Testnet routes to api-testnet.spark-fintech.com // apiRegion: 'HK', // // -// TK: routes to api.bybit.tr (for Turkey users) -// apiRegion: 'TK', +// GE: routes to api.bybitgeorgia.ge (for Georgia users) +// apiRegion: 'GE', +// +// +// UAE: routes to api.bybit.ae (for United Arab Emirates users) +// apiRegion: 'UAE', +// +// +// EU: routes to api.bybit.eu (for EU and EEA users) +// apiRegion: 'EU', // // // ID: routes to api.bybit.id (for Indonesian users) // apiRegion: 'ID', +// +// +// JP: routes to api.manepa.jp (for Japan users) +// Testnet routes to api-testnet.manepa.jp +// apiRegion: 'JP', +// +// +/** + * Brazil and Argentina international accounts use the global API domain + * with an x-site-id header. Choose the site ID for your account: + */ +// siteId: 'BRA_BTL', +// siteId: 'ARG_BTL', ================ File: examples/Rest/rest-v5-next-cursor.ts From 53d110368e679350e13e24f4efd832ab15876992 Mon Sep 17 00:00:00 2001 From: "Tiago Siebler @ Siebly.io" Date: Fri, 4 Sep 2026 14:30:15 +0100 Subject: [PATCH 09/10] feat(v4.7.6): expand Bybit API & WebSocket regional routing & docs --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index e10b9135..e92949c1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "bybit-api", - "version": "4.7.5", + "version": "4.7.6", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "bybit-api", - "version": "4.7.5", + "version": "4.7.6", "license": "MIT", "dependencies": { "@types/ws": "8.18.1", diff --git a/package.json b/package.json index f49495b9..44bbdf71 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "bybit-api", - "version": "4.7.5", + "version": "4.7.6", "description": "Complete & robust Node.js SDK for Bybit's REST APIs and WebSockets, with TypeScript & strong end to end tests.", "main": "lib/index.js", "types": "lib/index.d.ts", From 53380429aebd35d6b9d3c82182c3b38d2959fe43 Mon Sep 17 00:00:00 2001 From: "Tiago Siebler @ Siebly.io" Date: Fri, 4 Sep 2026 15:21:48 +0100 Subject: [PATCH 10/10] chore: phrasing --- README.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ec6fc8e0..1c7a3b5a 100644 --- a/README.md +++ b/README.md @@ -580,13 +580,13 @@ Important: do not subscribe to the same topics on both clients or you will recei Bybit uses two regional API access models. Use the configuration that matches the site where your account is registered: -| Account setup | REST API endpoint | WebSocket endpoint | SDK configuration | -| --- | --- | --- | --- | -| Account with a dedicated regional domain | Matching regional API domain | Regional mainnet stream when Bybit lists one, otherwise the global stream | Set `apiRegion` | -| Brazil international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'BRA_BTL'` | -| Argentina international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'ARG_BTL'` | +| Account setup | REST API endpoint | WebSocket endpoint | SDK configuration | +| ---------------------------------------- | ---------------------------- | ------------------------------------------------------------------------- | ----------------------- | +| Account with a dedicated regional domain | Matching regional API domain | Regional mainnet stream when Bybit lists one, otherwise the global stream | Set `apiRegion` | +| Brazil international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'BRA_BTL'` | +| Argentina international account | `api.bybit.com` | `stream.bybit.com` | Set `siteId: 'ARG_BTL'` | -`apiRegion` selects the regional REST domain and, where Bybit lists one, the regional mainnet WebSocket domain. `siteId` keeps the default global domains and adds the `x-site-id` header to REST requests and Node.js WebSocket handshakes. Only set `siteId` when Bybit documents it for your account. Do not derive or invent a value. +`apiRegion` selects the regional REST domain and, where Bybit lists one, the regional mainnet WebSocket domain. `siteId` keeps the default global domains and adds the `x-site-id` header to REST requests and Node.js WebSocket handshakes. This is only relevant if your account belongs to a specific region. See [Bybit's Integration Guidance](https://bybit-exchange.github.io/docs/v5/guide#authentication) for current regional requirements. @@ -611,14 +611,14 @@ The following values are currently supported in this option: For WebSocket clients, the same option selects these mainnet stream domains: -| `apiRegion` | WebSocket domain | -| --- | --- | -| `TK` | `stream.bybit.tr` | -| `KZ` | `stream.bybit.kz` | -| `HK` | `stream.spark-fintech.com` | -| `GE` | `stream.bybitgeorgia.ge` | -| `ID` | `stream.bybit.id` | -| `JP` | `stream.manepa.jp` | +| `apiRegion` | WebSocket domain | +| ----------- | -------------------------- | +| `TK` | `stream.bybit.tr` | +| `KZ` | `stream.bybit.kz` | +| `HK` | `stream.spark-fintech.com` | +| `GE` | `stream.bybitgeorgia.ge` | +| `ID` | `stream.bybit.id` | +| `JP` | `stream.manepa.jp` | For `default`, `bytick`, `NL`, `UAE`, and `EU`, WebSocket connections continue to use the global stream because Bybit does not list a dedicated V5 trading stream for those values. This means `apiRegion: 'EU'` selects `api.bybit.eu` for REST and keeps `stream.bybit.com` for WebSocket. Testnet WebSocket connections use `stream-testnet.bybit.com`. For Hong Kong mainnet WebSocket connections, the SDK also adds `x-refer-site-id: HKG` automatically.