bitmart-api

Node.js & JavaScript SDK for BitMart REST API & WebSockets

[!TIP] Upcoming change: As part of the Siebly.io brand, this SDK will soon be hosted under the Siebly.io GitHub organisation. The migration is seamless and requires no user changes.

Complete JavaScript, TypeScript & Node.js SDK for BitMart REST APIs & WebSockets:

• Professional, robust & performant BitMart SDK with extensive production use in live trading environments.
• Complete integration with all BitMart APIs and domains.
  • Spot trading APIs via RestClient
  • Full support for Futures V2 domain via FuturesClientV2
  • Unified WebSocket client for all markets
• Complete TypeScript support (with type declarations for most API requests & responses).
  • Strongly typed requests and responses.
  • Automated end-to-end tests ensuring reliability.
• Actively maintained with a modern, promise-driven interface.
• Robust WebSocket integration with configurable connection heartbeats & automatic reconnect then resubscribe workflows.
  • Event driven messaging.
  • Smart WebSocket persistence with automatic reconnection handling.
  • Emit reconnected event when dropped connection is restored.
  • Support for both public and private WebSocket streams.
• Browser-friendly HMAC signature mechanism with Web Crypto API support.
• Automatically supports both ESM and CJS projects.
• Custom HMAC signing support for enhanced performance.
• Heavy automated end-to-end testing with real API calls.
• Active community support & collaboration in telegram: Node.js Algo Traders.
• QuickStart Guide: https://siebly.io/sdk/bitmart/javascript

Table of Contents

• Installation
• Examples
• Issues & Discussion
• Usage
  • REST API Clients
    • Spot & Margin APIs
    • Futures V2 APIs
  • WebSocket Client
    • Public Streams
    • Private Streams
  • Configuration Options
    • Recv Window
    • Custom Sign
• Browser/Frontend Usage
  • Webpack
• Related Projects
• Structure
• LLMs & AI
• Used By
• Contributions & Thanks

Installation

npm install --save bitmart-api

Examples

Refer to the examples folder for implementation demos, including:

• REST API Examples: spot trading, futures trading, account management
• WebSocket Examples: public data streams, private account streams, custom logging
• Advanced Features: custom HMAC signing, error handling

Issues & Discussion

• Issues? Check the issues tab.
• Discuss & collaborate with other node devs? Join our Node.js Algo Traders engineering community on telegram.
• Follow our announcement channel for real-time updates on X/Twitter

Usage

Create API credentials on BitMart's website if you plan to use private endpoints or place trades.

Most methods accept JS objects. These can be populated using parameters specified by BitMart's API documentation, or check the type definition in each class within this repository.

Documentation Links

• BitMart API | Spot
• BitMart API | USD-M Futures
• REST Endpoint Function List

REST APIs

There are two main REST API clients depending on the market you're trading:

• RestClient - for spot trading, margin, and general account operations
• FuturesClientV2 - dedicated client for USD-M futures trading (uses V2 domain)

Spot & Margin APIs

Use the RestClient for spot trading, margin trading, and general account operations.

import { RestClient } from 'bitmart-api';
// or if you prefer require:
// const { RestClient } = require('bitmart-api');

const API_KEY = 'yourAPIKeyHere';
const API_SECRET = 'yourAPISecretHere';
const API_MEMO = 'yourAPIMemoHere';

const client = new RestClient({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
});

// For public endpoints, API credentials are optional
// const client = new RestClient();

// Get account balances
client
  .getAccountBalancesV1()
  .then((result) => {
    console.log('Account balances: ', result);
  })
  .catch((err) => {
    console.error('Error: ', err);
  });

// Submit a spot order
client
  .submitSpotOrderV2({
    symbol: 'BTC_USDT',
    side: 'buy',
    type: 'limit',
    size: '0.001',
    price: '30000',
  })
  .then((result) => {
    console.log('Order submitted: ', result);
  })
  .catch((err) => {
    console.error('Order error: ', err);
  });

// Get spot candlestick data
client
  .getSpotHistoryKlineV3({
    symbol: 'BTC_USDT',
    step: 60, // 1 minute
    from: Math.floor(Date.now() / 1000) - 3600, // 1 hour ago
    to: Math.floor(Date.now() / 1000),
  })
  .then((result) => {
    console.log('Klines: ', result);
  })
  .catch((err) => {
    console.error('Klines error: ', err);
  });

Futures V2 APIs

Use the FuturesClientV2 for USD-M futures trading. This client connects to BitMart's V2 futures domain.

import { FuturesClientV2 } from 'bitmart-api';
// or if you prefer require:
// const { FuturesClientV2 } = require('bitmart-api');

const futuresClient = new FuturesClientV2({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
});

// Enable demo/simulated trading environment (optional)
const demoFuturesClient = new FuturesClientV2({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
  demoTrading: true, // Connect to simulated trading environment
});

// Get futures account assets
try {
  const balances = await futuresClient.getFuturesAccountAssets();
  console.log('Futures balances: ', JSON.stringify(balances, null, 2));
} catch (error) {
  console.error('Error getting balances: ', error);
}

// Submit a futures order
futuresClient
  .submitFuturesOrder({
    symbol: 'BTCUSDT',
    side: 'buy',
    type: 'limit',
    size: '0.001',
    price: '30000',
    leverage: '10',
  })
  .then((result) => {
    console.log('Futures order submitted: ', result);
  })
  .catch((err) => {
    console.error('Futures order error: ', err);
  });

WebSocket

All WebSocket functionality is supported via the unified WebsocketClient. This client handles both spot and futures WebSocket streams, with automatic connection management and reconnection.

Key WebSocket features:

• Event driven messaging
• Smart WebSocket persistence with automatic reconnection
• Heartbeat mechanisms to detect disconnections
• Automatic resubscription after reconnection
• Support for both public and private data streams
• Unified client for spot and futures markets

Public WebSocket Streams

For public data streams, API credentials are not required:

import { WebsocketClient } from 'bitmart-api';
// or if you prefer require:
// const { WebsocketClient } = require('bitmart-api');

// Create WebSocket client for public streams
const wsClient = new WebsocketClient();

// Set up event handlers
wsClient.on('open', (data) => {
  console.log('WebSocket connected: ', data?.wsKey);
});

wsClient.on('update', (data) => {
  console.log('Data received: ', JSON.stringify(data, null, 2));
});

wsClient.on('reconnected', (data) => {
  console.log('WebSocket reconnected: ', data);
});

wsClient.on('exception', (data) => {
  console.error('WebSocket error: ', data);
});

// Subscribe to public data streams

// Spot market ticker
wsClient.subscribe('spot/ticker:BTC_USDT', 'spot');

// Spot market depth
wsClient.subscribe('spot/depth20:BTC_USDT', 'spot');

// Futures market ticker
wsClient.subscribe('futures/ticker', 'futures');

// Futures market depth
wsClient.subscribe('futures/depth20:BTCUSDT', 'futures');

// Futures trades
wsClient.subscribe('futures/trade:BTCUSDT', 'futures');

// Multiple futures kline subscriptions
wsClient.subscribe(
  [
    'futures/klineBin1m:BTCUSDT',
    'futures/klineBin1m:ETHUSDT',
    'futures/klineBin5m:BTCUSDT',
    'futures/klineBin1h:ETHUSDT',
  ],
  'futures',
);

Private WebSocket Streams

For private account data streams, API credentials are required:

import { WebsocketClient } from 'bitmart-api';

// Create WebSocket client with API credentials for private streams
const wsClient = new WebsocketClient({
  apiKey: 'yourAPIKeyHere',
  apiSecret: 'yourAPISecretHere',
  apiMemo: 'yourAPIMemoHere',
});

// Enable demo/simulated trading environment for V2 Futures WebSocket (optional)
const demoWsClient = new WebsocketClient({
  apiKey: 'yourAPIKeyHere',
  apiSecret: 'yourAPISecretHere',
  apiMemo: 'yourAPIMemoHere',
  demoTrading: true, // Connect to simulated trading environment (V2 Futures only)
});

// Set up event handlers
wsClient.on('open', (data) => {
  console.log('Private WebSocket connected: ', data?.wsKey);
});

wsClient.on('update', (data) => {
  console.log('Private data received: ', JSON.stringify(data, null, 2));
});

wsClient.on('authenticated', (data) => {
  console.log('WebSocket authenticated: ', data);
});

wsClient.on('response', (data) => {
  console.log('WebSocket response: ', data);
});

wsClient.on('exception', (data) => {
  console.error('WebSocket error: ', data);
});

// Subscribe to private data streams

// Spot account orders
wsClient.subscribe('spot/user/order:BTC_USDT', 'spot');

// Spot account balance updates
wsClient.subscribe('spot/user/balance:USDT', 'spot');

// Futures account orders
wsClient.subscribe('futures/user/order:BTCUSDT', 'futures');

// Futures account positions
wsClient.subscribe('futures/user/position:BTCUSDT', 'futures');

For more comprehensive examples, including custom logging and error handling, check the examples folder.

Configuration Options

Demo Trading

BitMart provides a simulated trading environment for testing futures trading strategies. Enable demo mode by adding demoTrading: true to your client configuration:

REST API (Futures V2 only):

const demoClient = new FuturesClientV2({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
  demoTrading: true, // Uses https://demo-api-cloud-v2.bitmart.com
});

WebSocket (V2 Futures only):

const demoWsClient = new WebsocketClient({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
  demoTrading: true, // Uses wss://openapi-wsdemo-v2.bitmart.com
});

Note: Demo environment is only available for V2 Futures. Spot trading and V1 Futures will continue using production endpoints. The same API keys work for both production and demo environments.

Recv Window

The receive window parameter determines how long an API request is valid. This can be configured at two levels:

• Per method: If provided in a method call, will be used instead of the global default
• Global default: Applied by default to any API call that supports recvWindow, if no recvWindow is provided in the method call

// Set global receive window during client initialization
const client = new RestClient({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
  recvWindow: 10000, // 10 seconds global default
});

// Override receive window for specific method calls
client.getAccountBalancesV1({ recvWindow: 5000 }); // 5 seconds for this call

Custom Sign

Authentication involves HMAC signing on requests using API credentials. Internally, this SDK uses the Web Crypto API for browser compatibility. The REST client also supports injecting a custom sign function if you wish to use an alternative (such as Node.js's native & faster createHmac).

Refer to the fasterHmacSign.ts example for a complete demonstration.

Browser/Frontend Usage

Webpack

Build a bundle using webpack:

• npm install
• npm run build
• npm run pack

The bundle can be found in dist/. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.

Use with LLMs & AI

This SDK includes a bundled llms.txt file in the root of the repository. If you're developing with LLMs, use the included llms.txt with your LLM - it will significantly improve the LLMs understanding of how to correctly use this SDK.

This file contains AI optimised structure of all the functions in this package, and their parameters for easier use with any learning models or artificial intelligence.

Used By

Related Projects

Check out our JavaScript/TypeScript/Node.js SDKs & Projects:

• Visit our website: https://Siebly.io
• Try our REST API & WebSocket SDKs published on npmjs:
  • Bybit Node.js SDK: bybit-api
  • Kraken Node.js SDK: @siebly/kraken-api
  • OKX Node.js SDK: okx-api
  • Binance Node.js SDK: binance
  • Gate (gate.com) Node.js SDK: gateio-api
  • Bitget Node.js SDK: bitget-api
  • Kucoin Node.js SDK: kucoin-api
  • Coinbase Node.js SDK: coinbase-api
  • Bitmart Node.js SDK: bitmart-api
• Try my misc utilities:
  • OrderBooks Node.js: orderbooks
  • Crypto Exchange Account State Cache: accountstate
• Check out my examples:
  • awesome-crypto-examples Node.js

Structure

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).

Note: The build will output both ESM and CJS, although node should automatically import the correct entrypoint for your environment.

• src - the whole SDK written in TypeScript
• dist - ESM & CJS builds of the SDK in JavaScript (this is published to npm)
• examples - some implementation examples & demonstrations.

Contributions & Thanks

Have my projects helped you? Share the love, there are many ways you can show your thanks:

• Star & share my projects.
• Are my projects useful? Sponsor me on Github and support my effort to maintain & improve them: https://github.com/sponsors/tiagosiebler
• Have an interesting project? Get in touch & invite me to it.
• Or buy me all the coffee:
  • ETH(ERC20): 0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C
• Sign up with my referral links:
  • OKX (receive a 20% fee discount!): https://www.okx.com/join/42013004
  • Binance (receive a 20% fee discount!): https://accounts.binance.com/register?ref=OKFFGIJJ
  • HyperLiquid (receive a 4% fee discount!): https://app.hyperliquid.xyz/join/SDK
  • Gate: https://www.gate.io/signup/NODESDKS?ref_type=103

Contributions & Pull Requests

Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.

Star History