bybit-api
Advanced tools
Complete & robust Node.js SDK for Bybit's REST APIs and WebSockets, with TypeScript & strong end to end tests.
Node.js SDK for the Bybit APIs and WebSockets:
npm install --save bybit-api
Check out my related projects:
Most methods accept JS objects. These can be populated using parameters specified by Bybit's API documentation, or check the type definition in each class within the github repository (see table below for convenient links to each class).
This connector is fully compatible with both TypeScript and pure JavaScript projects, while the connector is written in TypeScript. A pure JavaScript version can be built using npm run build, which is also the version published to npm.
The version on npm is the output from the build command and can be used in projects without TypeScript (although TypeScript is definitely recommended).
Bybit has several API groups (originally one per product). Each generation is labelled with the version number (e.g. v1/v2/v3/v5). Some of the newer API groups can only be used by upgrading your account to the unified account, but doing so will prevent you from using the V1 and V2 APIs.
Refer to the V5 upgrade guide for more information on requirements to use each API group. If you have a choice, you should use the newest generation that is available (e.g. use the V5 instead of the V3 APIs if you can).
Here are the available REST clients and the corresponding API groups described in the documentation:
| Class | Description |
|---|---|
| [ V5 API ] | The new unified V5 APIs (successor to previously fragmented APIs for all API groups). To learn more about the V5 API, please read the V5 upgrade guideline. |
| RestClientV5 | Unified V5 all-in-one REST client for all V5 REST APIs |
| [ Derivatives v3 ] | The Derivatives v3 APIs (successor to the Futures V2 APIs) |
| UnifiedMarginClient | Derivatives (v3) Unified Margin APIs |
| ContractClient | Derivatives (v3) Contract APIs. |
| [ Futures v2 ] | The Futures v2 APIs |
| Deprecated! ContractClient or RestClientV5 recommended | Please read the V5 upgrade guideline |
| Inverse Perpetual Futures (v2) APIs | |
| USDT Perpetual Futures (v2) APIs | |
| Inverse Futures (v2) APIs | |
| [ Spot ] | The spot APIs |
| SpotClientV3 | Spot Market (v3) APIs |
| Spot Market (v1) APIs | |
| [ USDC Contract ] | The USDC Contract APIs |
| USDCPerpetualClient | USDC Perpetual APIs |
| USDCOptionClient | USDC Option APIs |
| [ Other ] | Other standalone API groups |
| CopyTradingClient | Copy Trading APIs |
| AccountAssetClientV3 | Account Asset V3 APIs |
| Account Asset V1 APIs | |
| WebsocketClient | All WebSocket Events (Public & Private for all API categories) |
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.
Create API credentials on Bybit's website:
All REST clients have can be used in a similar way. However, method names, parameters and responses may vary depending on the API category you're using!
Not sure which function to call or which parameters to use? Click the class name in the table above to look at all the function names (they are in the same order as the official API docs), and check the API docs for a list of endpoints/parameters/responses.
The following is a minimal example for using the REST clients included with this SDK. For more detailed examples, refer to the examples folder in the repository on GitHub:
const {
InverseClient,
LinearClient,
InverseFuturesClient,
SpotClientV3,
UnifiedMarginClient,
USDCOptionClient,
USDCPerpetualClient,
AccountAssetClient,
CopyTradingClient,
RestClientV5,
} = require('bybit-api');
const restClientOptions = {
/** Your API key. Optional, if you plan on making private api calls */
key?: string;
/** Your API secret. Optional, if you plan on making private api calls */
secret?: string;
/** Set to `true` to connect to testnet. Uses the live environment by default. */
testnet?: boolean;
/** Override the max size of the request window (in ms) */
recv_window?: number;
/** Disabled by default. This can help on machines with consistent latency problems. */
enable_time_sync?: boolean;
/** How often to sync time drift with bybit servers */
sync_interval_ms?: number | string;
/** Default: false. If true, we'll throw errors if any params are undefined */
strict_param_validation?: boolean;
/**
* Optionally override API protocol + domain
* e.g baseUrl: 'https://api.bytick.com'
**/
baseUrl?: string;
/** Default: true. whether to try and post-process request exceptions. */
parse_exceptions?: boolean;
};
const API_KEY = 'xxx';
const API_SECRET = 'yyy';
const useTestnet = false;
const client = new RestClientV5({
key: API_KEY,
secret: API_SECRET,
testnet: useTestnet
},
// requestLibraryOptions
);
// For public-only API calls, simply don't provide a key & secret or set them to undefined
// const client = new RestClientV5({});
client.getAccountInfo()
.then(result => {
console.log("getAccountInfo result: ", result);
})
.catch(err => {
console.error("getAccountInfo error: ", err);
});
client.getOrderbook({ category: 'linear', symbol: 'BTCUSD' })
.then(result => {
console.log("getOrderBook result: ", result);
})
.catch(err => {
console.error("getOrderBook error: ", err);
});
All API groups can be used via a shared WebsocketClient. However, to listen to multiple API groups at once, you will need to make one WebsocketClient instance per API group.
The WebsocketClient can be configured to a specific API group using the market parameter. These are the currently available API groups:
| API Category | Market | Description |
|---|---|---|
| Unified Margin - Options | market: 'unifiedOption' | The derivatives v3 category for unified margin. Note: public topics only support options topics. If you need USDC/USDT perps, use unifiedPerp instead. |
| Unified Margin - Perps | market: 'unifiedPerp' | The derivatives v3 category for unified margin. Note: public topics only support USDT/USDC perpetual topics - use unifiedOption if you need public options topics. |
| Futures v2 - Inverse Perps | market: 'inverse' | The inverse v2 perps category. |
| Futures v2 - USDT Perps | market: 'linear' | The USDT/linear v2 perps category. |
| Futures v2 - Inverse Futures | market: 'inverse' | The inverse futures v2 category uses the same market as inverse perps. |
| Spot v3 | market: 'spotv3' | The spot v3 category. |
| Spot v1 | market: 'spot' | The older spot v1 category. Use the spotv3 market if possible, as the v1 category does not have automatic re-subscribe if reconnected. |
| Copy Trading | market: 'linear' | The copy trading category. Use the linear market to listen to all copy trading topics. |
| USDC Perps | market: 'usdcPerp | The USDC perps category. |
| USDC Options | market: 'usdcOption' | The USDC options category. |
| Contract v3 USDT | market: 'contractUSDT' | The Contract V3 category (USDT perps) |
| Contract v3 Inverse | market: 'contractInverse' | The Contract V3 category (inverse perps) |
| V5 Subscriptions | market: 'v5' | The v5 websocket topics for all categories under one market. Use the subscribeV5 method when subscribing to v5 topics. |
For more complete examples, look into the ws-* examples in the examples folder in the repo on GitHub. Here's a minimal example for using the websocket client:
const { WebsocketClient } = require('bybit-api');
const API_KEY = 'xxx';
const PRIVATE_KEY = 'yyy';
const wsConfig = {
key: API_KEY,
secret: PRIVATE_KEY,
/*
The following parameters are optional:
*/
// Connects to livenet by default. Set testnet to true to use the testnet environment.
// testnet: true
// If you can, use the v5 market (the newest generation of Bybit's websockets)
market: 'v5',
// The older generations of Bybit's websockets are still available under the previous markets:
// market: 'linear',
// market: 'inverse',
// market: 'spotv3',
// market: 'usdcOption',
// market: 'usdcPerp',
// market: 'unifiedPerp',
// market: 'unifiedOption',
// how long to wait (in ms) before deciding the connection should be terminated & reconnected
// pongTimeout: 1000,
// how often to check (in ms) that WS connection is still alive
// pingInterval: 10000,
// how long to wait before attempting to reconnect (in ms) after connection is closed
// reconnectTimeout: 500,
// config options sent to RestClient (used for time sync). See RestClient docs.
// restOptions: { },
// config for axios used for HTTP requests. E.g for proxy support
// requestOptions: { }
// override which URL to use for websocket connections
// wsUrl: 'wss://stream.bytick.com/realtime'
};
const ws = new WebsocketClient(wsConfig);
// (before v5) subscribe to multiple topics at once
ws.subscribe(['position', 'execution', 'trade']);
// (before v5) and/or subscribe to individual topics on demand
ws.subscribe('kline.BTCUSD.1m');
// (v5) subscribe to multiple topics at once
ws.subscribeV5(['orderbook.50.BTCUSDT', 'orderbook.50.ETHUSDT'], 'linear');
// (v5) and/or subscribe to individual topics on demand
ws.subscribeV5('position', 'linear');
ws.subscribeV5('publicTrade.BTC', 'option');
// Listen to events coming from websockets. This is the primary data source
ws.on('update', (data) => {
console.log('update', data);
});
// Optional: Listen to websocket connection open event (automatic after subscribing to one or more topics)
ws.on('open', ({ wsKey, event }) => {
console.log('connection open for websocket with ID: ' + wsKey);
});
// Optional: Listen to responses to websocket queries (e.g. the response after subscribing to a topic)
ws.on('response', (response) => {
console.log('response', response);
});
// Optional: Listen to connection close event. Unexpected connection closes are automatically reconnected.
ws.on('close', () => {
console.log('connection closed');
});
// Optional: Listen to raw error events. Recommended.
ws.on('error', (err) => {
console.error('error', err);
});
See websocket-client.ts for further information.
Pass a custom logger which supports the log methods silly, debug, notice, info, warning and error, or override methods from the default logger as desired.
const { WebsocketClient, DefaultLogger } = require('bybit-api');
// Disable all logging on the silly level
const customLogger = {
...DefaultLogger,
silly: () => {},
};
const ws = new WebsocketClient({ key: 'xxx', secret: 'yyy' }, customLogger);
Build a bundle using webpack:
npm installnpm buildnpm packThe bundle can be found in dist/. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.
However, note that browser usage will lead to CORS errors due Bybit. See issue #79 for more information & alternative suggestions.
If you found this project interesting or useful, create accounts with my referral links:
Or buy me a coffee using any of these:
1C6GWZL1XW3jrjpPTS863XtZiXL1aTK7Jk0xd773d8e6a50758e1ada699bb6c4f98bb4abf82daAn early generation of this library was started by @pixtron. If this library helps you to trade better on bybit, feel free to donate a coffee to @pixtron:
1Fh1158pXXudfM6ZrPJJMR7Y5SgZUz4EdF0x21aEdeC53ab7593b77C9558942f0c9E78131e8d7LNdHSVtG6UWsriMYLJR3qLdfVNKwJ6GSLFContributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.
FAQs
Complete & robust Node.js SDK for Bybit's REST APIs and WebSockets, with TypeScript & strong end to end tests.
We found that bybit-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.