gunbot-sdk-js

Gunbot SDK for JavaScript & TypeScript

JavaScript & TypeScript client for the Gunbot REST API for automated crypto-/ETF-/stock trading

Programmatically control Gunbot – the self-hosted automated trading bot – from Node.js, browsers, CI jobs or serverless functions.

Key Features

• 100 % OpenAPI 3.0 generated – strong typings & up-to-date endpoints
• Unified interface for spot, futures and on-chain derivatives
• Works in Node ≥ 18, browsers (ES modules) and TypeScript projects
• Tree-shakeable ES bundle + CommonJS build + d.ts typings
• Small footprint and few runtime deps except superagent
• MIT licensed – use in commercial or open-source projects

Table of Contents

• Installation
• Quick Start
• Configuration
• Supported Exchanges
• API Coverage
• TypeScript Usage
• Authentication
• Examples
• Troubleshooting
• Contributing
• Roadmap
• Changelog
• License

Installation

# npm
npm install gunbot-sdk-js
# yarn
yarn add gunbot-sdk-js
# pnpm
pnpm add gunbot-sdk-js

Works out-of-the-box with ESM and CJS.

Quick Start

import { ApiClient, GunbotApi } from 'gunbot-sdk-js';

const api     = ApiClient.instance;
api.basePath  = 'http://<host>:3000/api/v1';   // ← REST base
api.authentications.BearerAuth = { type: 'oauth2', accessToken: '<token>' };

const gunbot  = new GunbotApi(api);

/* Call methods, like placing an order, query balances, manage strategies … */
const assets  = await gunbot.assetsTotal({
  exchange: 'binance',
  base:     'USDT',
  start:    Date.now() - 86400000,
  end:      Date.now()
});

console.log(assets);

Replace <host> and <token> with your own instance values.

The docs folder on Github has documentation for each of the supported methods, online version of this documentation.

You need an appropriate Gunbot plan to use this SDK effectively.

Configuration

Option	Default	Description
api.basePath	http://localhost:3000	Gunbot REST base path
BearerAuth.accessToken	–	JWT from GUI localStorage or /auth/login
timeout (ApiClient)	60 000 ms	Request timeout
userAgent	gunbot-sdk-js/<version>	Custom UA header

Supported Exchanges

Gunbot ships with native connectors for 25+ exchanges.

Exchange	Spot	Futures / Perps	DeFi (on-chain)	Extra notes
Binance	✔️	✔️ (USD-M & COIN-M)		Largest liquidity
Binance US	✔️			US-regulated arm
Bitget	✔️	✔️ (USDT & UM perps)
Bybit	✔️	✔️ (USDT & inverse perps)
OKX	✔️	✔️ (Perps & dated futures)
Kraken	✔️	✔️ (via Kraken Futures)
KuCoin	✔️
Gate.io	✔️
MEXC	✔️
BingX	✔️
Crypto.com	✔️
Huobi Global	✔️
Bitfinex	✔️
HitBTC	✔️
Coinbase Advanced Trade	✔️			Former Coinbase Pro
CEX.io	✔️
Poloniex	✔️
Alpaca (stocks & crypto)	✔️
dYdX (v3/v4)		✔️	✔️	Perpetual DEX
HyperLiquid	✔️	✔️	✔️	DeFi perps
PancakeSwap		✔️	✔️	BSC DEX
Bitmex / Bitmex Testnet		✔️

API Coverage

This SDK targets Gunbot REST v1 (/api/v1), built from the official OpenAPI spec.

Tag / Section	Status
Auth	✅
Market Data	✅
Orders	✅
Strategy	✅
Wallet	✅
Exchange Mgmt	✅

TypeScript Usage

Types are bundled (dist/index.d.ts).

Full generics for responses and request bodies.

Authentication

• Bearer Token – Easy way: copy from Gunbot GUI localStorage.jwtToken
• Password Encryption – To get bearer token programatically, use helpers from the Gunbot docs
• All requests sent via HTTPS recommended for non-localhost deployments.

Examples

The script sets up the SDK client, creates a GunbotApi instance, and calls most of the available endpoints, so you can run it once to verify connectivity and see the expected argument patterns and raw responses. Use it as a reference checklist when integrating the SDK.

import { ApiClient, GunbotApi } from 'gunbot-sdk-js';

/* ───────────────────── 1. CLIENT CONFIG ───────────────────── */
const apiClient = ApiClient.instance;
apiClient.basePath = 'http://localhost:3000/api/v1';                  // ← set real REST base
apiClient.authentications['BearerAuth'] = {
  type: 'oauth2',
  accessToken: '<YOUR-JWT-HERE>'                                      // ← set real bearer token
};

/* ───────────────────── 2. SERVICE WRAPPER ──────────────────── */
const gunbot = new GunbotApi(apiClient);

/* ───────────────────── 3. EXAMPLES ─────────────────────────── */
async function runExamples() {

  /* ---------- SYSTEM / AUTH ---------- */
  const authStatusRes = await gunbot.authStatus();
  console.log('authStatus:', authStatusRes);

  const timeRes = await gunbot.time();
  console.log('time:', timeRes);

  const systemStartRes = await gunbot.systemStart();
  console.log('systemStart:', systemStartRes);

  const systemStopRes = await gunbot.systemStop();
  console.log('systemStop:', systemStopRes);


  /* ---------- CONFIGURATION ---------- */
  const configFullRes = await gunbot.configFull();
  console.log('configFull:', configFullRes);

  const configUpdateRes = await gunbot.configUpdate({
    data: { /* full Gunbot config as object */ }
  });
  console.log('configUpdate:', configUpdateRes);

  const configPairAddRes = await gunbot.configPairAdd({
    pair: 'USDT-BTC',
    exchange: 'binance',
    settings: {
                strategy: "stepgrid",
                enabled: true,
                override: {
                    "BUY_METHOD": "stepgrid",
                    "SELL_METHOD": "stepgrid",
                    "GAIN": "2"
                }
            }
  });
  console.log('configPairAdd:', configPairAddRes);

  const configPairRemoveRes = await gunbot.configPairRemove({
    pair: 'USDT-BTC',
    exchange: 'binance'
  });
  console.log('configPairRemove:', configPairRemoveRes);

  const configStrategyAddRes = await gunbot.configStrategyAdd({
    name: 'MY-STRATEGY',
    settings: { SOME_PARAM: true, MORE_PARAMS: 2 }
  });
  console.log('configStrategyAdd:', configStrategyAddRes);

  const configStrategyRemoveRes = await gunbot.configStrategyRemove({
    name: 'MY-STRATEGY'
  });
  console.log('configStrategyRemove:', configStrategyRemoveRes);


  /* ---------- MARKET DATA ---------- */
  const assetsTotalRes = await gunbot.assetsTotal({
    exchange: 'binance',
    base: 'USDT',
    start: Date.now() - 24 * 60 * 60 * 1000,
    end: Date.now()
  });
  console.log('assetsTotal:', assetsTotalRes);

  const chartDataRes = await gunbot.chartData({
    exchange: 'binance',
    pair: 'USDT-BTC',
    interval: '1h',
    start: Date.now() - 72 * 60 * 60 * 1000,
    end: Date.now()
  });
  console.log('chartData:', chartDataRes);

  const chartMarksRes = await gunbot.chartMarks(
    'binance', 'USDT-BTC', '1h',
    Date.now() - 24 * 60 * 60 * 1000, Date.now()
  );
  console.log('chartMarks:', chartMarksRes);

  const marketCandlesRes = await gunbot.marketCandles('binance/USDT-BTC');
  console.log('marketCandles:', marketCandlesRes);

  const marketOrderbookRes = await gunbot.marketOrderbook('binance/USDT-BTC');
  console.log('marketOrderbook:', marketOrderbookRes);


  /* ---------- CORE MEMORY ---------- */
  const corememRes = await gunbot.coremem();
  console.log('coremem:', corememRes);

  const corememRequestRes = await gunbot.corememRequest({
    exchange: 'binance',
    pair: 'USDT-BTC',
    elements: []
  });
  console.log('corememRequest:', corememRequestRes);

  const corememSingleRes = await gunbot.corememSingle({
    exchange: 'binance',
    pair: 'USDT-BTC'
  });
  console.log('corememSingle:', corememSingleRes);


  /* ---------- ORDERS ---------- */
  const ordersRes = await gunbot.orders('binance/USDT-BTC');
  console.log('orders:', ordersRes);

  const ordersPageRes = await gunbot.ordersPage('binance/USDT-BTC', 0, 50);
  console.log('ordersPage:', ordersPageRes);

  const ordersPageMultiRes = await gunbot.ordersPageMulti(
    ['binance/USDT-BTC', 'binance/USDT-BTC'], 0, 100
  );
  console.log('ordersPageMulti:', ordersPageMultiRes);

  const ordersDayRes = await gunbot.ordersDay(
    'Europe/Berlin', ['binance/USDT-BTC']
  );
  console.log('ordersDay:', ordersDayRes);


  /* ---------- BALANCES & PAIRS ---------- */
  const balancesRes = await gunbot.balances();
  console.log('balances:', balancesRes);

  const pairsRes = await gunbot.pairs('binance');
  console.log('pairs:', pairsRes);

  const pairsDetailedRes = await gunbot.pairsDetailed('binance');
  console.log('pairsDetailed:', pairsDetailedRes);


  /* ---------- PNL ---------- */
  const pnlDailyRes = await gunbot.pnlDaily(
    'binance/USDT-BTC',
    Date.now() - 24 * 60 * 60 * 1000, Date.now()
  );
  console.log('pnlDaily:', pnlDailyRes);

  const pnlDailyPaginatedRes = await gunbot.pnlDailyPaginated(
    'binance/USDT-BTC', 1, 30, Date.now()
  );
  console.log('pnlDailyPaginated:', pnlDailyPaginatedRes);

  const pnlSumRes = await gunbot.pnlSum(
    'binance', Date.now() - 7 * 24 * 60 * 60 * 1000, Date.now()
  );
  console.log('pnlSum:', pnlSumRes);

  const pnlTotalRes = await gunbot.pnlTotal('binance/USDT-BTC');
  console.log('pnlTotal:', pnlTotalRes);

  const pnlOverviewRes = await gunbot.pnlOverview({
    timezone: 'Europe/Berlin',
    keys: ['binance/USDT-BTC']
  });
  console.log('pnlOverview:', pnlOverviewRes);


  /* ---------- FILES ---------- */
  const filesStateRes = await gunbot.filesState();
  console.log('filesState:', filesStateRes);

  const filesStrategyRes = await gunbot.filesStrategy();
  console.log('filesStrategy:', filesStrategyRes);

  const filesStrategyWriteRes = await gunbot.filesStrategyWrite({
    filename: 'apistrat.js',
    document: 'full strategy as string'
  });
  console.log('filesStrategyWrite:', filesStrategyWriteRes);

  const filesStrategyDeleteRes = await gunbot.filesStrategyDelete({
    filename: 'apistrat.js'
  });
  console.log('filesStrategyDelete:', filesStrategyDeleteRes);

  const strategyFileContentRes = await gunbot.filesStrategyGet({
    filename: 'mfi.js'
  });
  console.log('filesStrategyGet:', strategyFileContentRes);

  const filesAcvarGetRes = await gunbot.filesAcvarGet({
    filename: 'autoconfig-variables.json'
  });
  console.log('filesAcvarGet:', filesAcvarGetRes);

  const filesAcvarRes = await gunbot.filesAcvar();
  console.log('filesAcvar:', filesAcvarRes);

  const filesAutoconfigWriteRes = await gunbot.filesAutoconfigWrite({
    /* full autoconfig.json */
  });
  console.log('filesAutoconfigWrite:', filesAutoconfigWriteRes);

  const filesCustomEditorWriteRes = await gunbot.filesCustomEditorWrite({
    document: { test: true }
  });
  console.log('filesCustomEditorWrite:', filesCustomEditorWriteRes);

  const filesCustomEditorGetRes = await gunbot.filesCustomEditorGet();
  console.log('filesCustomEditorGet:', filesCustomEditorGetRes);

  const filesBackupRes = await gunbot.filesBackup();
  console.log('filesBackup:', filesBackupRes);

  const backupFileRes = await gunbot.filesBackupGet({
    filename: 'autoconfig.json.1623252417412'
  });
  console.log('filesBackupGet:', backupFileRes);


  /* ---------- TRADING ---------- */
  const tradeBuyRes1 = await gunbot.tradeBuy({
    exch: 'binance',
    pair: 'USDT-BTC',
    price: 100000,
    amt: 0.001
  });
  console.log('tradeBuy (data):', tradeBuyRes1);

  const tradeSellRes = await gunbot.tradeSell({
    exch: 'binance',
    pair: 'USDT-BTC',
    price: 100000,
    amt: 0.001
  });
  console.log('tradeSell:', tradeSellRes);

  const tradeBuyMarketRes = await gunbot.tradeBuyMarket({
    exch: 'binance',
    pair: 'USDT-BTC',
    price: 100000, // explicit price needed in simulator mode, can be set to 0 for real trading
    amt: 0.001
  });
  console.log('tradeBuy (market):', tradeBuyMarketRes);

  const tradeSellMarketRes = await gunbot.tradeSellMarket({
    exch: 'binance',
    pair: 'USDT-BTC',
    price: 100000, // explicit price needed in simulator mode, can be set to 0 for real trading
    amt: 0.001
  });
  console.log('tradeSellMarket:', tradeSellMarketRes);
}

/* ───────────────────── 4. RUN ─────────────────────────────── */
runExamples().catch(console.error);

Troubleshooting

Symptom	Checklist
401 Unauthorized	✓ Valid token? ✓ Correct basePath?
400 Bad Request	✓ Payload shape vs spec? ✓ Missing required param?
ECONNREFUSED	✓ Gunbot core running? ✓ Port forwarded?
Enable DEBUG=superagent gunbot-sdk-js:* for verbose logs.

Contributing

• Fork → PR
• Follow Conventional Commits for commits & PR titles

License

MIT – see LICENSE.