Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/bybit-api/llms.txt

Use this file to discover all available pages before exploring further.

Both RestClientV5 and WebsocketClient accept a plain configuration object as their first constructor argument. You can start with an empty object for public endpoints and add credentials and other settings incrementally as your integration grows.

​
RestClientV5 Options

The REST client configuration is defined by the RestClientOptions interface. Pass it as the first argument to new RestClientV5(options, networkOptions). The optional second argument accepts any Axios request config fields such as proxy settings. 
import { RestClientV5 } from 'bybit-api';

const client = new RestClientV5({
  key: 'your-api-key',
  secret: 'your-api-secret',
  testnet: false,
  recv_window: 5000,
  parseAPIRateLimits: true,
});

​
Authentication

​
key
string
Your Bybit API key. Both HMAC and RSA key types are automatically detected and supported. Required for all private endpoints.
​
secret
string
Your Bybit API secret (or RSA private key string). Must be provided whenever key is set; providing one without the other will throw at construction time.

​
Environment Selection

​
testnet
boolean
default:"false"
Set to true to direct all requests to api-testnet.bybit.com. Testnet credentials are separate from live credentials and must be created at testnet.bybit.com.
​
demoTrading
boolean
default:"false"
Set to true to route requests to Bybit’s demo trading environment. Uses your live credentials but simulates P&L. Do not combine with testnet: true.

​
Regional Domain Routing

​
apiRegion
'default' | 'bytick' | 'NL' | 'TK' | 'KZ' | 'HK' | 'GE' | 'UAE' | 'EU'
Route API requests to a regional Bybit domain. When omitted the SDK uses api.bybit.com. See the Environments guide for the full domain map.
​
baseUrl
string
Fully override the base URL, e.g. 'https://api5.bybit.com'. Takes precedence over apiRegion. Useful for custom proxy endpoints or domains not yet represented in apiRegion.

​
Request Timing

​
recv_window
number
default:"5000"
Maximum allowed gap in milliseconds between the timestamp on a signed request and the server’s current time. Increase this value (e.g. 10000) when using a proxy or VPN that adds latency. The Bybit API enforces a hard maximum of 10 000 ms.
​
enable_time_sync
boolean
default:"false"
When true, the client will query the Bybit server time on startup and periodically thereafter to compensate for local clock drift. Useful on machines with inconsistent system clocks.
​
sync_interval_ms
number | string
default:"3600000"
How often (in milliseconds) to re-sync time drift with Bybit servers when enable_time_sync is enabled. Defaults to one hour.
​
syncTimeBeforePrivateRequests
boolean
default:"false"
When true, the client fetches and re-calculates the server time offset before every private API call instead of relying on the periodic sync interval.

​
Response Handling

​
parseAPIRateLimits
boolean
default:"false"
When true, per-endpoint rate limit headers are parsed and added to every response object under the rateLimitApi key. Useful for building adaptive rate-limit strategies.
​
throwOnFailedRateLimitParse
boolean
default:"false"
When true (and parseAPIRateLimits is also true), the client throws an error if the rate limit header parser fails rather than silently returning undefined.
​
throwExceptions
boolean
default:"false"
When true, the client automatically throws the response object for any API call that returns a non-zero retCode, so you can use a simple try/catch instead of manually checking retCode.
​
parse_exceptions
boolean
default:"true"
When false, HTTP and network errors are re-thrown as-is without the SDK’s normalisation layer. Disable only if you need raw Axios error objects.

​
Connection & Performance

​
keepAlive
boolean
default:"false"
Enable HTTP keep-alive on the underlying https.Agent. Reduces TCP handshake overhead for high-frequency REST polling. Node.js only — has no effect in browser builds.
​
keepAliveMsecs
number
default:"1000"
When keepAlive is true, sets the interval (in ms) between TCP keep-alive probes. Defaults to the Node.js https.Agent default of 1000 ms.

​
Signing

​
encodeSerialisedValues
boolean
default:"true"
URI-encode parameter values during the signing process. Introduced to fix rare signature failures caused by cursor values containing % characters. Only disable this if you have a specific compatibility reason.
​
strict_param_validation
boolean
default:"false"
When true, the SDK throws an error if any request parameter resolves to undefined rather than silently omitting it from the query string.
​
customSignMessageFn
(message: string, secret: string) => Promise<string>
Provide a custom signing function to replace the default Web Crypto API implementation. For example, use Node.js crypto.createHmac for significantly faster HMAC signing in high-throughput scenarios. See examples/Auth/fasterHmacSign.ts in the repository for a complete demonstration.

​
Proxy Configuration

Proxy settings are passed as the second argument to the RestClientV5 constructor via the standard Axios config shape: 
import { RestClientV5 } from 'bybit-api';

const client = new RestClientV5(
  {
    key: process.env.API_KEY,
    secret: process.env.API_SECRET,
    // Increase recv window to account for extra proxy latency
    recv_window: 10000,
  },
  {
    proxy: {
      protocol: 'http',
      host: 'proxyhost',
      port: 8080,
      auth: {
        username: 'proxyuser',
        password: 'proxypass',
      },
    },
  },
);
Some proxy services are not compatible with Axios’s native proxy config. If requests fail through a proxy, try using https-proxy-agent as shown in examples/Rest/rest-v5-proxies2.ts.

​
WebsocketClient Options

The WebSocket client configuration is defined by the WSClientConfigurableOptions interface. Pass it as the first argument to new WebsocketClient(options, logger). The optional second argument is a custom logger object. 
import { WebsocketClient } from 'bybit-api';

const ws = new WebsocketClient({
  key: 'your-api-key',
  secret: 'your-api-secret',
  pingInterval: 10000,
  pongTimeout: 1000,
  reconnectTimeout: 500,
});

​
Authentication

​
key
string
Your Bybit API key. Only required for private topics (orders, positions, wallet, etc.) or WebSocket API calls.
​
secret
string
Your Bybit API secret or RSA private key. Required when key is provided.

​
Environment Selection

​
testnet
boolean
default:"false"
Connect to Bybit’s testnet WebSocket endpoints. Do not combine with demoTrading: true.
​
demoTrading
boolean
default:"false"
Connect to Bybit’s demo trading WebSocket endpoints. Uses live credentials. Supported for private topics (order, execution, position, wallet, greeks).

​
Connection Health

​
pingInterval
number
default:"10000"
How often (in milliseconds) to send a ping frame to check that the connection is still alive. Bybit requires a heartbeat at least every 20 seconds; the default of 10 000 ms provides a comfortable margin.
​
pongTimeout
number
default:"1000"
How long (in milliseconds) to wait for a pong response after sending a ping before treating the connection as dead and initiating a reconnect.
​
reconnectTimeout
number
default:"500"
Delay in milliseconds before spawning a new connection after an unexpected disconnect. After reconnecting, the client automatically re-authenticates and re-subscribes to all previously active topics.

​
URL Override & Recv Window

​
wsUrl
string
Fully override the WebSocket endpoint URL, e.g. 'wss://stream.bytick.com/realtime'. Useful for custom routing or regional failover.
​
recvWindow
number
default:"5000"
Recv window (in milliseconds) used when generating the private WebSocket authentication signature. Increase on high-latency connections such as VPNs.

​
Advanced

​
promiseSubscribeRequests
boolean
default:"false"
When true, calls to subscribeV5() return a Promise that resolves when the subscription is confirmed by the server. Note: subscriptions are sent in batches internally, so behaviour may vary when subscribing to many topics at once.
​
customSignMessageFn
(message: string, secret: string) => Promise<string>
Custom signing function, identical in purpose to the REST client option. Useful for Node.js crypto.createHmac-based performance improvements.
​
market
'v5'
default:"'v5'"
The API market group to connect to. Only 'v5' is currently supported. You do not normally need to set this explicitly.
​
restOptions
RestClientOptions
REST client options to use when the WebSocket client needs to make internal REST calls (for example, to fetch server time for authentication). Accepts the same fields as the RestClientV5 options object.
​
requestOptions
AxiosRequestConfig
Additional Axios request config options forwarded to internal REST calls made by the WebSocket client. Useful for proxy configuration or custom timeout values on those requests.
​
wsOptions
object
Low-level options passed directly to the underlying isomorphic-ws constructor. Accepts protocols (subprotocol negotiation), agent (proxy support), and any other fields from WebSocket.ClientOptions or ClientRequestArgs.

Environments

Switch between live, testnet, demo trading, and regional domains

Error Handling

Handle API errors, rate limits, and network failures

Logging

Customise log output with a custom logger or the DefaultLogger

Browser Usage

Bundle bybit-api for browser and frontend projects

Build docs developers (and LLMs) love

Get started for freeTalk to us