BrokerClient: Broker & Sub-Account Management

npm install kucoin-api

import { BrokerClient } from 'kucoin-api';

const client = new BrokerClient({
  apiKey: process.env.KUCOIN_BROKER_API_KEY,
  apiSecret: process.env.KUCOIN_BROKER_API_SECRET,
  apiPassphrase: process.env.KUCOIN_BROKER_API_PASSPHRASE,
});

import { BrokerClient } from 'kucoin-api';

const client = new BrokerClient({
  apiKey: process.env.KUCOIN_BROKER_API_KEY,
  apiSecret: process.env.KUCOIN_BROKER_API_SECRET,
  apiPassphrase: process.env.KUCOIN_BROKER_API_PASSPHRASE,
});

// Retrieve basic broker account information
const brokerInfo = await client.getBrokerInfo({
  begin: '20240101',
  end: '20240630',
  tradeType: '1',
});
console.log('Broker info:', JSON.stringify(brokerInfo, null, 2));

// Create a new sub-account
// Note: account names are globally unique — use a prefix to avoid collisions
const newSub = await client.createSubAccount({
  accountName: 'mybroker_trader_001',
});
console.log('Created sub-account UID:', newSub.data.uid);

// List all sub-accounts for a UID (paginated, default page size = 20, max = 100)
const subAccounts = await client.getSubAccounts({
  uid: 'your_sub_uid',
  pageSize: 50,
  currentPage: 1,
});
console.log(`Total sub-accounts: ${subAccounts.data.items.length}`);

// Transfer USDT from broker master (MAIN) to sub-account (TRADE)
// direction: 'OUT' = broker → sub, 'IN' = sub → broker
const transferOut = await client.submitTransfer({
  currency: 'USDT',
  amount: '100',
  direction: 'OUT',
  accountType: 'MAIN',            // broker master account type
  specialUid: 'your_sub_uid',     // the sub-account UID
  specialAccountType: 'TRADE',    // sub-account destination type
  clientOid: 'unique_transfer_id_001',
});
console.log('Transfer order ID:', transferOut.data.orderId);

// Transfer USDT back from sub-account (TRADE) to broker master (MAIN)
const transferIn = await client.submitTransfer({
  currency: 'USDT',
  amount: '50',
  direction: 'IN',
  accountType: 'MAIN',
  specialUid: 'your_sub_uid',
  specialAccountType: 'TRADE',
  clientOid: 'unique_transfer_id_002',
});

// Check transfer status by order ID
const transferStatus = await client.getTransferHistory({
  orderId: transferOut.data.orderId,
});
console.log('Transfer status:', transferStatus.data.status);

// List all sub-account deposits (defaults to 1000 records, max 1000)
const deposits = await client.getDeposits({
  currency: 'USDT',
  status: 'SUCCESS',
  limit: 100,
});

// Look up a single deposit by currency + on-chain transaction hash
const deposit = await client.getDeposit({
  currency: 'BTC',
  hash: 'on_chain_tx_hash_here',
});
console.log('Deposit status:', deposit.data.status);

// Retrieve a sub-account withdrawal record by withdrawal ID
const withdrawal = await client.getWithdrawal({
  withdrawalId: 'your_withdrawal_id',
});
console.log('Withdrawal status:', withdrawal.data.status);

// Submit a fast API withdrawal for a sub-account
// An initial call returns 2FA factors; resubmit with validation to complete
const fastWithdrawal = await client.applyFastWithdrawal({
  currency: 'USDT',
  address: '0xRecipientAddress',
  amount: '50',
  chain: 'ERC20',
  uid: 'your_sub_uid',
  // Include 2FA fields on the resubmission step
});

// Download broker rebate data as a CSV file URL
// tradeType: '1' = Spot, '2' = Futures
// Maximum range: 6 months; URL valid for 24 hours
const rebate = await client.getBrokerRebate({
  begin: '20240101',
  end: '20240630',
  tradeType: '1',
});
console.log('Download URL:', rebate.data.url);