n8n-nodes-bitget-MP

Production-grade n8n community nodes for Bitget Futures trading.

Includes two nodes:

| Node | Purpose | |------|---------| | Bitget Futures Order | Place futures orders with 4 unit modes (quantity / cost / value / balancePercent) | | Bitget Modify Position | Modify TP / SL on existing positions identified by symbol + holdSide |

Features

• Live & Demo (Paper Trading) mode via a global Account Mode dropdown
• All parameters support n8n expressions — wire any value from previous nodes
  e.g. {{$json.symbol}}, {{$json.tp}}, {{$node["AI"].json.side}}
• 4 Unit Settings for position sizing:
  • quantity — direct base-currency size (e.g. 0.01 BTC)
  • cost — USDT margin to spend (leveraged)
  • value — USD notional value of the position
  • balancePercent — % of available futures balance (auto-fetches balance)
• Auto-fetches market price when needed (cost / value / balancePercent / market orders)
• HMAC-SHA256 signed requests with exponential-backoff retry (3 attempts)
• Full TypeScript with strict types
• Returns rich diagnostic output: availableBalance, usableMargin, marketPrice, calculatedSize, currentTP, updatedTP, etc.

Installation

In n8n (Community Nodes)

1. Go to Settings → Community Nodes → Install
2. Enter n8n-nodes-bitget-MP
3. Click Install

Manual / Self-hosted

cd ~/.n8n/nodes          # or your custom nodes path
npm install n8n-nodes-bitget-MP

Then restart n8n.

From source

git clone https://github.com/your-org/n8n-nodes-bitget-MP.git
cd n8n-nodes-bitget-MP
npm install
npm run build
npm link
cd ~/.n8n/nodes && npm link n8n-nodes-bitget-MP

Credentials Setup

Create a Bitget API credential in n8n:

| Field | Description | |-------|-------------| | API Key | From Bitget → API Management | | Secret Key | Secret associated with the API key | | Passphrase | Passphrase set during API key creation |

Demo trading: Use credentials from your Bitget demo account and set Account Mode → Demo in the node.

Node: Bitget Futures Order

Parameters

| Parameter | Type | Expressions | Description | |-----------|------|-------------|-------------| | Account Mode | Dropdown | — | live or demo | | Symbol | String | ✅ {{$json.symbol}} | e.g. BTCUSDT | | Side | Dropdown | ✅ {{$json.side}} | buy (long) or sell (short) | | Trade Side | Dropdown | — | open or close | | Entry Type | Dropdown | ✅ {{$json.entryType}} | market or limit | | Limit Price | String | ✅ {{$json.price}} | Required for limit orders | | Unit Setting | Dropdown | — | quantity / cost / value / balancePercent | | Amount | String | ✅ {{$json.amount}} | Interpreted per Unit Setting | | Leverage | String | ✅ {{$json.leverage}} | 1–125 | | Margin Mode | Dropdown | — | isolated or crossed | | Take Profit Price | String | ✅ {{$json.tp}} | Optional | | Stop Loss Price | String | ✅ {{$json.sl}} | Optional | | Client Order ID | String | ✅ {{$json.clientOid}} | Optional | | Reduce Only | Boolean | — | Only reduce existing position |

Unit Setting formulas

quantity:      size = amount
cost:          size = (amount × leverage) / marketPrice
value:         size = amount / marketPrice
balancePercent:
  usableMargin = availableBalance × (amount / 100)
  size = (usableMargin × leverage) / marketPrice

Example — 10% of balance with 20× leverage, BTC at $100,000:

availableBalance = 1000 USDT
usableMargin     = 1000 × 0.10 = 100 USDT
size             = (100 × 20) / 100000 = 0.02 BTC

Output fields

{
  "orderId": "...",
  "clientOid": "...",
  "accountMode": "live",
  "unitSetting": "balancePercent",
  "symbol": "BTCUSDT",
  "side": "buy",
  "tradeSide": "open",
  "entryType": "market",
  "leverage": 20,
  "marginMode": "isolated",
  "availableBalance": 1000,
  "usableMargin": 100,
  "marketPrice": 100000,
  "calculatedSize": 0.02,
  "takeProfit": 110000,
  "stopLoss": 95000
}

Node: Bitget Modify Position

Modifies the TP and/or SL of an open position. Positions are always identified by symbol + holdSide (never by orderId or clientOid).

Parameters

| Parameter | Type | Expressions | Description | |-----------|------|-------------|-------------| | Account Mode | Dropdown | — | live or demo | | Symbol | String | ✅ {{$json.symbol}} | e.g. BTCUSDT | | Hold Side | Dropdown | ✅ {{$json.holdSide}} | long or short | | New Take Profit Price | String | ✅ {{$json.tp}} | Leave empty to keep existing | | New Stop Loss Price | String | ✅ {{$json.sl}} | Leave empty to keep existing | | TP Trigger Type | Dropdown | — | fill_price / mark_price / index_price | | SL Trigger Type | Dropdown | — | fill_price / mark_price / index_price |

Output fields

{
  "accountMode": "live",
  "symbol": "BTCUSDT",
  "holdSide": "long",
  "currentPositionSize": "0.02",
  "currentTP": "110000",
  "currentSL": "95000",
  "updatedTP": 115000,
  "updatedSL": 97000,
  "tpTriggerType": "fill_price",
  "slTriggerType": "fill_price"
}

Account Mode: Live vs Demo

| Mode | Bitget Product Type | Header | |------|--------------------|-----------------------------| | live | USDT-FUTURES | (none) | | demo | SUSDT-FUTURES | paptrading: 1 |

The node automatically switches API product type and the paper trading header based on your selection. WebSocket support follows the same pattern when added.

Expression Examples

Every string parameter supports full n8n expression syntax:

// From previous HTTP node
{{$json.symbol}}
{{$json.tp}}
{{$json.sl}}

// From AI agent node
{{$node["AI Agent"].json.side}}
{{$node["AI Agent"].json.leverage}}

// Computed expressions
{{"BTC" + "USDT"}}
{{$json.balance * 0.1}}

Project Structure

n8n-nodes-bitget-MP/
├── credentials/
│   └── BitgetApi.credentials.ts      # API key / secret / passphrase
├── nodes/
│   ├── BitgetFuturesOrder/
│   │   ├── BitgetFuturesOrder.node.ts
│   │   └── bitget.svg
│   └── BitgetModifyPosition/
│       ├── BitgetModifyPosition.node.ts
│       └── bitget.svg
├── utils/
│   ├── bitgetApi.ts                  # Signing, request, retry, credentials
│   └── calculations.ts              # Size calculation engine + balance fetch
├── index.ts
├── package.json
└── tsconfig.json

Error Handling

• All API errors include the Bitget error code and message
• Network errors (ECONNRESET, timeouts) are retried up to 3 times with backoff
• continueOnFail is supported on both nodes — errors are passed downstream instead of halting the workflow
• Invalid parameter values (bad numbers, missing required fields) throw descriptive NodeOperationError before making any API call

License

MIT