ICG Exchanges

Cryptocurrency exchange API implementations providing unified interfaces for RESTful APIs and WebSocket connections across 40+ exchanges.

Features

• Unified API: Consistent interface across all supported exchanges
• REST & WebSocket: Both REST API calls and real-time WebSocket data streams
• Multi-Key Support: Rotate between multiple API key pairs for rate limit management
• Comprehensive Coverage: Order management, market data, account info, deposits/withdrawals

Supported Exchanges

| Exchange | Exchange | Exchange | Exchange | | ---------------- | -------- | --------- | ------------- | | Ascendex | Biconomy | Binance | Bingx | | Bitfinex | Bitget | Bithumb | Bitkub | | Bitmart | Bitmex | Bitrue | Bitstamp | | Blofin | Btse | Bybit | Coinbase | | CoinbaseAdvanced | Coinex | Coinstore | Coinw | | Cryptocom | Deepcoin | Digifinex | Fastex | | Gate | Gemini | Hashkey | HashkeyGlobal | | Hitbtc | Hkbitex | Htx | Indodax | | Kraken | Kucoin | Lbank | Mexc | | Okx | P2b | Phemex | Poloniex | | Superex | Swft | Upbit | Weex | | Xt | | | |

Installation

npm install @icgio/icg-exchanges

Usage

const { Binance, Bybit, Okx } = require('@icgio/icg-exchanges')

// Initialize an exchange with API credentials
const binance = new Binance('api_key', 'secret_key')

// Or with multiple API key pairs (for rotation)
const bybit = new Bybit(['key1', 'key2'], ['secret1', 'secret2'])

// Example: Get orderbook
const orderbook = await binance.get_orderbook('BTCUSDT')

// Example: Place an order
const order = await binance.create_order('BTCUSDT', 'buy', 0.001, 50000)

// Example: Get account balance
const balance = await binance.get_balance()

API Structure

Each exchange class extends ExchangeBase and implements:

Market Data

• get_orderbook(pair) - Get order book for a trading pair
• get_ticker(pair) - Get current ticker data
• get_trades(pair) - Get recent trades
• get_ohlcv(pair, interval) - Get OHLCV candlestick data

Trading

• create_order(pair, side, amount, price) - Place a limit order
• create_market_order(pair, side, amount) - Place a market order
• cancel_order(pair, order_id) - Cancel an order
• cancel_all_orders(pair) - Cancel all orders for a pair
• get_open_orders(pair) - Get open orders
• get_order(pair, order_id) - Get order details

Account

• get_balance() - Get account balances
• get_deposits() - Get deposit history
• get_withdrawals() - Get withdrawal history
• get_trades_history(pair) - Get trade history

WebSocket

• ws_orderbook(pair, callback) - Subscribe to orderbook updates
• ws_trades(pair, callback) - Subscribe to trade updates
• ws_ticker(pair, callback) - Subscribe to ticker updates

WebSocket Staleness Detection

The WebSocket base class (exchange-ws.js) uses three layers of detection to identify and recover from dead or degraded connections:

Layer 1: Depth staleness (ts_dict check)

Runs every 10 seconds. For each subscribed pair, checks if ts_dict[pair].received_ts is older than market_stale_time (default 120s). If stale, disconnects and auto-reconnects after 5s.

ts_dict is updated when:

• A depth message is received (all exchanges)
• A server-initiated ping is received (lbank only — since lbank stops sending depth updates for low-liquidity pairs when the orderbook hasn't changed, the server ping acts as a liveness signal)

Layer 2: Dead socket detection (last_message_time check)

Also runs every 10 seconds in the same interval. Checks if any message (depth, trade, ping, pong) was received in the last market_stale_time. Only fires if Layer 1 didn't already trigger. Catches cases where the socket silently dies with no messages at all.

Layer 3: Ping/pong check

Runs every ping_interval (exchange-specific — 20s for lbank, 30s default). We send a ping and expect a pong back. On the next ping cycle, if last_pong < last_ping (the previous ping got no pong), disconnects and reconnects. Catches cases where the socket appears open but the server stopped responding.

Routine reconnection

Independent of staleness, each WebSocket connection is proactively closed and reconnected after reconnecting_time (default 2 hours) to prevent long-lived connection degradation.

Project Structure

icg-exchanges/
├── exchanges.js              # Main entry point, exports all exchanges
├── lib/
│   ├── exchanges/
│   │   ├── exchange-base.js  # Base class for all exchanges
│   │   ├── exchange-ws.js    # WebSocket base class
│   │   ├── binance.js        # Binance implementation
│   │   ├── bybit.js          # Bybit implementation
│   │   └── ...               # Other exchange implementations
│   ├── error_codes.json      # Standardized error codes
│   └── utils/
│       └── mexc/             # MEXC protobuf definitions
├── test/                     # Test files
└── package.json

Dependencies

| Package | Purpose | | ------------------ | ------------------------- | | @icgio/icg-utils | Utility functions | | lodash | Utility library | | needle | HTTP client | | ws | WebSocket client | | jsonwebtoken | JWT authentication | | protobufjs | Protocol buffer support | | pako | Compression/decompression |

Code Style

• CommonJS modules (require() / module.exports)
• Variable naming: snake_case
• Class naming: PascalCase

License

ISC License