Skip to main content

Documentation Index

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

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

Bitget’s API uses a three-part credential system: an API Key, an API Secret, and an API Passphrase. Every authenticated REST request and every private WebSocket connection must carry a signature derived from these three values. The bitget-api SDK handles the signing automatically — you only need to supply the credentials when constructing a client. Both HMAC-SHA256 and RSA-SHA256 signing are supported, and the SDK detects which method to use based on the format of your apiSecret.
Never hardcode your API key, secret, or passphrase directly in source code. Use environment variables or a secrets manager. Committing credentials to version control is a common cause of account compromise.

​
Creating API Credentials

1
Open API Management on Bitget
2
Visit How to create an API key and log in to your Bitget account. Navigate to Profile → API Management and click Create API.
3
Choose a signing method
4
Bitget supports two signing methods:
5
  • HMAC (default) — Bitget generates a secret string for you. This is the simplest option and sufficient for most use cases.
  • RSA (self-generated) — You generate an RSA key pair locally, provide Bitget with your public key, and keep the private key yourself. This is the more secure option because your secret never leaves your machine.
    • 6
    Save your credentials
    7
    After creating the key, record all three values:
    8
    ValueDescriptionAPI KeyPublic identifier — safe to log, not safe to share openlyAPI SecretHMAC secret string, or your RSA private key — never share or commit thisAPI PassphraseChosen by you at creation time — this is not your account login password
    9
    Store them as environment variables:
    10
    export API_KEY_COM="your_api_key"
export API_SECRET_COM="your_api_secret_or_rsa_private_key"
export API_PASS_COM="your_api_passphrase"

    ​
    Constructor Options

    Pass credentials and configuration to any client constructor via the RestClientOptions interface. The same options object is accepted by RestClientV3, RestClientV2, WebsocketClientV3, and WebsocketClientV2.
    ​
    apiKey
    string
    Your Bitget API key. Optional for public endpoints; required for any authenticated REST call or private WebSocket subscription.
    ​
    apiSecret
    string
    Your API secret. For HMAC, this is the secret string provided by Bitget. For RSA, pass your full PEM-encoded private key, including the -----BEGIN PRIVATE KEY----- header — the SDK detects RSA automatically from this header.
    ​
    apiPass
    string
    The passphrase you chose when creating the API key. This is not your Bitget account login password — it is the separate passphrase set at API key creation time. Optional for public endpoints; required for authenticated calls.
    ​
    demoTrading
    boolean
    default:"false"
    Set to true to route all requests to Bitget’s paper trading (demo) environment. No other code changes are required — the SDK switches base URLs and WebSocket endpoints automatically.
    ​
    customSignMessageFn
    (message: string, secret: string) => Promise<string>
    An optional function that overrides the default signing implementation. Useful for latency-sensitive applications that want to use Node’s native createHmac instead of the Web Crypto API. See the Custom Sign Function section below.
    ​
    baseUrl
    string
    Override the REST API base URL. Defaults to https://api.bitget.com. Useful when routing through a proxy or a custom gateway.
    ​
    strictParamValidation
    boolean
    default:"false"
    When true, the SDK throws an error if any request parameter is undefined. Useful during development to catch accidental omissions before they reach the API.
    ​
    encodeQueryStringValues
    boolean
    default:"true"
    When true (the default), query string values are URI-encoded via encodeURIComponent. Disable only if you are pre-encoding values yourself; leaving this enabled prevents signature errors caused by special characters in parameter values.
    ​
    parseExceptions
    boolean
    default:"true"
    When true (the default), the SDK post-processes API error responses and throws them as structured exceptions. Set to false to receive raw error responses instead.
    ​
    keepAlive
    boolean
    Enable HTTP keep-alive for REST API requests via the underlying axios agent. Reuses TCP connections across requests, which can reduce latency at high call rates.
    ​
    keepAliveMsecs
    number
    default:"1000"
    When keepAlive is true, controls how often (in milliseconds) TCP keep-alive packets are sent on idle sockets. Only relevant when keepAlive is enabled. Defaults to 1000 ms.

    ​
    HMAC Authentication

    HMAC is the default signing method. Pass your credentials to the constructor and the SDK signs every request automatically: 
    import { RestClientV3 } from 'bitget-api';

const client = new RestClientV3({
  apiKey: process.env.API_KEY_COM,
  apiSecret: process.env.API_SECRET_COM,
  apiPass: process.env.API_PASS_COM,
});

(async () => {
  try {
    const balances = await client.getBalances();
    console.log('Balances:', JSON.stringify(balances, null, 2));
  } catch (e) {
    console.error('Request failed:', e);
  }
})();

    ​
    RSA Authentication

    RSA authentication is supported for both V2 and V3 clients. To use it, generate an RSA key pair locally, register the public key with Bitget when creating the API key, and pass the private key as apiSecret. The SDK detects RSA automatically when the secret contains the PRIVATE KEY marker. Generate RSA keys with OpenSSL: 
    # Generate a 4096-bit private key
openssl genrsa -out rsa-private-key.pem 4096

# Derive the corresponding public key
openssl rsa -in rsa-private-key.pem -pubout -out rsa-public-key.pem
    Upload the contents of rsa-public-key.pem to Bitget when creating a “self-generated” API key. Bitget will issue you an API key string to use as apiKey. Your private key (rsa-private-key.pem) never leaves your machine. Use the RSA private key with the SDK: 
    import { readFileSync } from 'fs';
import { RestClientV3 } from 'bitget-api';

// Read the private key from a file — never embed PEM content directly in source
const rsaPrivateKey = readFileSync('./rsa-private-key.pem', 'utf-8');

const client = new RestClientV3({
  // API key string issued by Bitget after registering your public key
  apiKey: 'bg_0866563123123123123f567e83e52fd',
  // Pass the full PEM private key — the "BEGIN PRIVATE KEY" header triggers RSA mode
  apiSecret: rsaPrivateKey,
  apiPass: process.env.API_PASS_COM,
});

(async () => {
  try {
    const balances = await client.getBalances();
    console.log('V3 balances:', JSON.stringify(balances, null, 2));
  } catch (e) {
    console.error('Request failed:', e);
  }
})();
    The SDK uses RSA-SHA256 for RSA signing. Detection is automatic — if apiSecret contains the string "PRIVATE KEY" (as all standard PEM headers do), RSA mode is activated. No additional configuration is needed.

    ​
    Custom Sign Function

    Starting from SDK v3.0.0, the default signing implementation uses the Web Crypto API, which works in both Node.js and browser environments. However, for latency-sensitive applications, Node’s native createHmac is measurably faster. You can inject your own signing function via customSignMessageFn. The function receives the pre-built message string and the secret, and must return a Promise<string> containing the hex-encoded signature: 
    import { createHmac } from 'crypto';
import { RestClientV3, WebsocketClientV3 } from 'bitget-api';

const customSignMessageFn = async (message: string, secret: string): Promise<string> => {
  return createHmac('sha256', secret).update(message).digest('hex');
};

// Inject into the REST client
const restClient = new RestClientV3({
  apiKey: process.env.API_KEY_COM,
  apiSecret: process.env.API_SECRET_COM,
  apiPass: process.env.API_PASS_COM,
  customSignMessageFn,
});

// Inject into the WebSocket client
const wsClient = new WebsocketClientV3({
  apiKey: process.env.API_KEY_COM,
  apiSecret: process.env.API_SECRET_COM,
  apiPass: process.env.API_PASS_COM,
  customSignMessageFn,
});
    The customSignMessageFn is called on every authenticated REST request and once each time a private WebSocket connection is opened, so even small per-call savings compound at high request rates.

    ​
    Demo Trading

    Bitget’s demo (paper) trading environment mirrors the live API but operates with simulated funds. Enable it with a single flag: 
    import { RestClientV3 } from 'bitget-api';

const client = new RestClientV3({
  apiKey: process.env.API_KEY_COM,
  apiSecret: process.env.API_SECRET_COM,
  apiPass: process.env.API_PASS_COM,
  demoTrading: true, // Routes all requests to demo environment
});
    You must create a separate set of API keys in the Demo Trading environment. Live API keys do not work against the demo endpoints, and vice versa.

    ​
    Debugging HTTP Requests

    If you need to inspect the raw HTTP requests being sent to Bitget (for example when troubleshooting signature errors), set the BITGETTRACE environment variable to true before starting your application: 
    BITGETTRACE=true node your-script.js
    This causes the SDK to log detailed information about every outgoing request and the corresponding API response, including headers and the signed payload.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us