Trading & CEX API Reference

Trading packages provide integrations with centralized exchanges and automated trading capabilities.

Packages

Package	Description
@nirholas/trading-spot-exchange	Binance spot trading
@nirholas/trading-spot-exchange-us	Binance US integration
@nirholas/trading-futures-exchange	Futures trading
@nirholas/trading-memecoin-bot	Memecoin trading bot
@nirholas/trading-bsc-meme-bot	BSC meme trading
@nirholas/trading-bots	Trading bot framework

---

Binance Spot Trading

Installation

pnpm add @nirholas/trading-spot-exchange

Configuration

import { BinanceClient } from '@nirholas/trading-spot-exchange'

const client = new BinanceClient({
  apiKey: process.env.BINANCE_API_KEY!,
  apiSecret: process.env.BINANCE_API_SECRET!,
  testnet: false, // Use true for testnet
})

Market Data

getPrice

Get current price for a symbol.

async function getPrice(symbol: string): Promise<PriceResult>

interface PriceResult {
  symbol: string
  price: string
  timestamp: number
}

Example:

const price = await client.getPrice('BTCUSDT')
console.log(`BTC Price: $${price.price}`)

getOrderBook

Get order book depth.

async function getOrderBook(
  symbol: string, 
  limit?: number
): Promise<OrderBook>

interface OrderBook {
  bids: [string, string][]  // [price, quantity]
  asks: [string, string][]
  lastUpdateId: number
}

getTicker24h

Get 24-hour ticker statistics.

async function getTicker24h(symbol: string): Promise<Ticker24h>

interface Ticker24h {
  symbol: string
  priceChange: string
  priceChangePercent: string
  weightedAvgPrice: string
  lastPrice: string
  lastQty: string
  openPrice: string
  highPrice: string
  lowPrice: string
  volume: string
  quoteVolume: string
  openTime: number
  closeTime: number
  count: number
}

getKlines

Get candlestick/kline data.

async function getKlines(params: KlineParams): Promise<Kline[]>

interface KlineParams {
  symbol: string
  interval: '1m' | '5m' | '15m' | '1h' | '4h' | '1d' | '1w'
  limit?: number
  startTime?: number
  endTime?: number
}

interface Kline {
  openTime: number
  open: string
  high: string
  low: string
  close: string
  volume: string
  closeTime: number
  quoteVolume: string
  trades: number
  takerBuyBaseVolume: string
  takerBuyQuoteVolume: string
}

---

Order Management

createOrder

Place a new order.

async function createOrder(params: OrderParams): Promise<Order>

interface OrderParams {
  symbol: string
  side: 'BUY' | 'SELL'
  type: 'LIMIT' | 'MARKET' | 'STOP_LOSS_LIMIT' | 'TAKE_PROFIT_LIMIT'
  quantity: string
  price?: string          // Required for LIMIT orders
  stopPrice?: string      // For stop orders
  timeInForce?: 'GTC' | 'IOC' | 'FOK'
}

Examples:

// Market buy
const marketOrder = await client.createOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'MARKET',
  quantity: '0.001',
})

// Limit sell
const limitOrder = await client.createOrder({
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'LIMIT',
  quantity: '0.001',
  price: '50000',
  timeInForce: 'GTC',
})

// Stop-loss
const stopLoss = await client.createOrder({
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'STOP_LOSS_LIMIT',
  quantity: '0.001',
  price: '44000',
  stopPrice: '45000',
  timeInForce: 'GTC',
})

cancelOrder

Cancel an existing order.

async function cancelOrder(
  symbol: string, 
  orderId: number
): Promise<CancelResult>

cancelAllOrders

Cancel all open orders for a symbol.

async function cancelAllOrders(symbol: string): Promise<CancelResult[]>

getOrder

Get order details.

async function getOrder(
  symbol: string, 
  orderId: number
): Promise<Order>

interface Order {
  symbol: string
  orderId: number
  clientOrderId: string
  price: string
  origQty: string
  executedQty: string
  status: OrderStatus
  type: string
  side: string
  time: number
  updateTime: number
}

type OrderStatus = 
  | 'NEW'
  | 'PARTIALLY_FILLED'
  | 'FILLED'
  | 'CANCELED'
  | 'REJECTED'
  | 'EXPIRED'

getOpenOrders

Get all open orders.

async function getOpenOrders(symbol?: string): Promise<Order[]>

getOrderHistory

Get historical orders.

async function getOrderHistory(params: HistoryParams): Promise<Order[]>

interface HistoryParams {
  symbol: string
  startTime?: number
  endTime?: number
  limit?: number
}

---

Account & Portfolio

getAccountInfo

Get account information including balances.

async function getAccountInfo(): Promise<AccountInfo>

interface AccountInfo {
  makerCommission: number
  takerCommission: number
  buyerCommission: number
  sellerCommission: number
  canTrade: boolean
  canWithdraw: boolean
  canDeposit: boolean
  updateTime: number
  accountType: string
  balances: Balance[]
}

interface Balance {
  asset: string
  free: string
  locked: string
}

getBalance

Get balance for a specific asset.

async function getBalance(asset: string): Promise<Balance>

getTrades

Get recent trades for a symbol.

async function getTrades(params: TradeParams): Promise<Trade[]>

interface Trade {
  symbol: string
  id: number
  orderId: number
  price: string
  qty: string
  quoteQty: string
  commission: string
  commissionAsset: string
  time: number
  isBuyer: boolean
  isMaker: boolean
}

---

WebSocket Streams

subscribeToTicker

Subscribe to real-time ticker updates.

function subscribeToTicker(
  symbol: string,
  callback: (ticker: TickerUpdate) => void
): () => void  // Returns unsubscribe function

subscribeToTrades

Subscribe to real-time trade updates.

function subscribeToTrades(
  symbol: string,
  callback: (trade: TradeUpdate) => void
): () => void

subscribeToKlines

Subscribe to real-time candlestick updates.

function subscribeToKlines(
  symbol: string,
  interval: string,
  callback: (kline: KlineUpdate) => void
): () => void

subscribeToDepth

Subscribe to order book updates.

function subscribeToDepth(
  symbol: string,
  callback: (depth: DepthUpdate) => void
): () => void

Example:

// Subscribe to BTC price updates
const unsubscribe = client.subscribeToTicker('BTCUSDT', (ticker) => {
  console.log(`BTC: $${ticker.lastPrice} (${ticker.priceChangePercent}%)`)
})

// Later: unsubscribe
unsubscribe()

---

Futures Trading

Installation

pnpm add @nirholas/trading-futures-exchange

Configuration

import { FuturesClient } from '@nirholas/trading-futures-exchange'

const futures = new FuturesClient({
  apiKey: process.env.BINANCE_API_KEY!,
  apiSecret: process.env.BINANCE_API_SECRET!,
  testnet: true, // Recommended for testing
})

Position Management

openPosition

Open a futures position.

async function openPosition(params: FuturesOrderParams): Promise<FuturesOrder>

interface FuturesOrderParams {
  symbol: string
  side: 'BUY' | 'SELL'
  type: 'LIMIT' | 'MARKET' | 'STOP' | 'TAKE_PROFIT'
  quantity: string
  price?: string
  stopPrice?: string
  reduceOnly?: boolean
  closePosition?: boolean
}

closePosition

Close a futures position.

async function closePosition(
  symbol: string, 
  side: 'BUY' | 'SELL'
): Promise<FuturesOrder>

getPosition

Get current position for a symbol.

async function getPosition(symbol: string): Promise<FuturesPosition>

interface FuturesPosition {
  symbol: string
  positionAmt: string
  entryPrice: string
  markPrice: string
  unRealizedProfit: string
  liquidationPrice: string
  leverage: string
  marginType: 'isolated' | 'cross'
  positionSide: 'BOTH' | 'LONG' | 'SHORT'
}

setLeverage

Set leverage for a symbol.

async function setLeverage(
  symbol: string, 
  leverage: number
): Promise<void>

setMarginType

Set margin type (isolated/cross).

async function setMarginType(
  symbol: string,
  marginType: 'ISOLATED' | 'CROSSED'
): Promise<void>

---

Trading Bots

Installation

pnpm add @nirholas/trading-bots

Bot Framework

createBot

Create a trading bot instance.

function createBot(config: BotConfig): TradingBot

interface BotConfig {
  name: string
  exchange: 'binance' | 'binance_us'
  symbols: string[]
  strategy: Strategy
  riskManagement: RiskConfig
  notifications?: NotificationConfig
}

interface RiskConfig {
  maxPositionSize: string      // % of portfolio
  maxDailyLoss: string         // % of portfolio
  stopLossPercent: number
  takeProfitPercent: number
  maxOpenPositions: number
}

Built-in Strategies

// Grid trading
const gridStrategy = createGridStrategy({
  lowerPrice: '40000',
  upperPrice: '50000',
  gridLevels: 10,
  orderSize: '0.001',
})

// DCA (Dollar Cost Averaging)
const dcaStrategy = createDCAStrategy({
  interval: '1h',
  amount: '100',
  symbol: 'BTCUSDT',
})

// Mean reversion
const meanReversionStrategy = createMeanReversionStrategy({
  period: 20,
  stdDevThreshold: 2,
  orderSize: '0.001',
})

Bot Lifecycle

const bot = createBot(config)

// Start the bot
await bot.start()

// Get bot status
const status = bot.getStatus()
console.log(status.isRunning, status.openPositions, status.pnl)

// Stop the bot
await bot.stop()

// Get performance metrics
const metrics = bot.getPerformance()
console.log(metrics.totalTrades, metrics.winRate, metrics.sharpeRatio)

---

Memecoin Trading Bot

Installation

pnpm add @nirholas/trading-memecoin-bot

Quick Start

import { MemecoinBot } from '@nirholas/trading-memecoin-bot'

const bot = new MemecoinBot({
  chain: 'ethereum', // or 'bsc', 'base', 'arbitrum'
  privateKey: process.env.PRIVATE_KEY!,
  maxBuyAmount: '0.1', // ETH
  slippage: 0.15,      // 15%
  gasMultiplier: 1.5,
})

// Monitor for new tokens
bot.on('newToken', async (token) => {
  // Check token safety
  const analysis = await bot.analyzeToken(token.address)

  if (analysis.isHoneypot) {
    console.log('Honeypot detected, skipping')
    return
  }

  if (analysis.buyTax > 10 || analysis.sellTax > 10) {
    console.log('High tax token, skipping')
    return
  }

  // Buy if safe
  await bot.buy(token.address, '0.05')
})

// Start monitoring
await bot.start()

Safety Analysis

interface TokenAnalysis {
  address: string
  name: string
  symbol: string
  isHoneypot: boolean
  buyTax: number
  sellTax: number
  isRenounced: boolean
  isLiquidityLocked: boolean
  lpLockDuration?: number
  holderCount: number
  top10HolderPercent: number
  creatorBalance: number
  riskScore: number  // 0-100, lower is better
}

---

Error Types

class TradingError extends Error {
  code: string
}

// Order errors
class InsufficientBalanceError extends TradingError {}
class InvalidOrderError extends TradingError {}
class OrderNotFoundError extends TradingError {}
class OrderRejectedError extends TradingError {}

// Position errors
class PositionNotFoundError extends TradingError {}
class MarginInsufficientError extends TradingError {}
class LiquidationRiskError extends TradingError {}

// Connection errors
class RateLimitError extends TradingError {}
class APIError extends TradingError {}
class WebSocketError extends TradingError {}