ccxt-typescript

# CCXT for TypeScript/JavaScript A comprehensive guide to using CCXT in TypeScript and JavaScript projects for cryptocurrency exchange integration. ## Installation ### REST API (Standard CCXT) ```bash npm install ccxt ``` ### WebSocket API (Real-time, ccxt.pro) ```bash npm install ccxt ``` Both REST and WebSocket APIs are included in the same package. ## Quick Start ### REST API - TypeScript ```typescript import ccxt from 'ccxt' const exchange = new ccxt.binance() await exchange.loadMarkets() const ticker = await exchange.fetchTicker('BTC/USDT') console.log(ticker) ``` ### REST API - JavaScript (CommonJS) ```javascript const ccxt = require('ccxt') (async () => { const exchange = new ccxt.binance() await exchange.loadMarkets() const ticker = await exchange.fetchTicker('BTC/USDT') console.log(ticker) })() ``` ### WebSocket API - Real-time Updates ```typescript import ccxt from 'ccxt' const exchange = new ccxt.pro.binance() while (true) { const ticker = await exchange.watchTicker('BTC/USDT') console.log(ticker) // Live updates! } await exchange.close() ``` ## REST vs WebSocket | Feature | REST API | WebSocket API | |---------|----------|---------------| | **Use for** | One-time queries, placing orders | Real-time monitoring, live price feeds | | **Method prefix** | `fetch*` (fetchTicker, fetchOrderBook) | `watch*` (watchTicker, watchOrderBook) | | **Speed** | Slower (HTTP request/response) | Faster (persistent connection) | | **Rate limits** | Strict (1-2 req/sec) | More lenient (continuous stream) | | **Import** | `ccxt.exchange()` | `ccxt.pro.exchange()` | | **Best for** | Trading, account management | Price monitoring, arbitrage detection | **When to use REST:** - Placing orders - Fetching account balance - One-time data queries - Order management (cancel, fetch orders) **When to use WebSocket:** - Real-time price monitoring - Live orderbook updates - Arbitrage detection - Portfolio tracking with live updates ## Creating Exchange Instance ### REST API ```typescript // Public API (no authentication) const exchange = new ccxt.binance({ enableRateLimit: true // Recommended! }) // Private API (with authentication) const exchange = new ccxt.binance({ apiKey: 'YOUR_API_KEY', secret: 'YOUR_SECRET', enableRateLimit: true }) ``` ### WebSocket API ```typescript // Public WebSocket const exchange = new ccxt.pro.binance() // Private WebSocket (with authentication) const exchange = new ccxt.pro.binance({ apiKey: 'YOUR_API_KEY', secret: 'YOUR_SECRET' }) // Always close when done await exchange.close() ``` ## Common REST Operations ### Loading Markets ```typescript // Load all available trading pairs await exchange.loadMarkets() // Access market information const btcMarket = exchange.market('BTC/USDT') console.log(btcMarket.limits.amount.min) // Minimum order amount ``` ### Fetching Ticker ```typescript // Single ticker const ticker = await exchange.fetchTicker('BTC/USDT') console.log(ticker.last) // Last price console.log(ticker.bid) // Best bid console.log(ticker.ask) // Best ask console.log(ticker.volume) // 24h volume // Multiple tickers (if supported) const tickers = await exchange.fetchTickers(['BTC/USDT', 'ETH/USDT']) ``` ### Fetching Order Book ```typescript // Full orderbook const orderbook = await exchange.fetchOrderBook('BTC/USDT') console.log(orderbook.bids[0]) // [price, amount] console.log(orderbook.asks[0]) // [price, amount] // Limited depth const orderbook = await exchange.fetchOrderBook('BTC/USDT', 5) // Top 5 levels ``` ### Creating Orders #### Limit Order ```typescript // Buy limit order const order = await exchange.createLimitBuyOrder('BTC/USDT', 0.01, 50000) console.log(order.id) // Sell limit order const order = await exchange.createLimitSellOrder('BTC/USDT', 0.01, 60000) // Generic limit order const order = await exchange.createOrder('BTC/USDT', 'limit', 'buy', 0.01, 50000) ``` #### Market Order ```typescript // Buy market order const order = await exchange.createMarketBuyOrder('BTC/USDT', 0.01) // Sell market order const order = await exchange.createMarketSellOrder('BTC/USDT', 0.01) // Generic market order const order = await exchange.createOrder('BTC/USDT', 'market', 'sell', 0.01) ``` ### Fetching Balance ```typescript const balance = await exchange.fetchBalance() console.log(balance.BTC.free) // Available balance console.log(balance.BTC.used) // Balance in orders console.log(balance.BTC.total) // Total balance ``` ### Fetching Orders ```typescript // Open orders const openOrders = await exchange.fetchOpenOrders('BTC/USDT') // Closed orders const closedOrders = await exchange.fetchClosedOrders('BTC/USDT') // All orders (open + closed) const allOrders = await exchange.fetchOrders('BTC/USDT') // Single order by ID const order = await exchange.fetchOrder(orderId, 'BTC/USDT') ``` ### Fetching Trades ```typescript // Recent public trades const trades = await exchange.fetchTrades('BTC/USDT', undefined, 10) // Your trades (requires authentication) const myTrades = await exchange.fetchMyTrades('BTC/USDT') ``` ### Canceling Orders ```typescript // Cancel single order await exchange.cancelOrder(orderId, 'BTC/USDT') // Cancel all orders for a symbol await exchange.cancelAllOrders('BTC/USDT') ``` ## WebSocket Operations (Real-time) ### Watching Ticker (Live Price Updates) ```typescript const exchange = new ccxt.pro.binance() while (true) { const ticker = await exchange.watchTicker('BTC/USDT') console.log(ticker.last, ticker.timestamp) } await exchange.close() ``` ### Watching Order Book (Live Depth Updates) ```typescript const exchange = new ccxt.pro.binance() while (true) { const orderbook = await exchange.watchOrderBook('BTC/USDT') console.log('Best bid:', orderbook.bids[0]) console.log('Best ask:', orderbook.asks[0]) } await exchange.close() ``` ### Watching Trades (Live Trade Stream) ```typescript const exchange = new ccxt.pro.binance() while (true) { const trades = await exchange.watchTrades('BTC/USDT') for (const trade of trades) { console.log(trade.price, trade.amount, trade.side) } } await exchange.close() ``` ### Watching Your Orders (Live Order Updates) ```typescript const exchange = new ccxt.pro.binance({ apiKey: 'YOUR_API_KEY', secret: 'YOUR_SECRET' }) while (true) { const orders = await exchange.watchOrders('BTC/USDT') for (const order of orders) { console.log(order.id, order.status, order.filled) } } await exchange.close() ``` ### Watching Balance (Live Balance Updates) ```typescript const exchange = new ccxt.pro.binance({ apiKey: 'YOUR_API_KEY', secret: 'YOUR_SECRET' }) while (true) { const balance = await exchange.watchBalance() console.log('BTC:', balance.BTC) console.log('USDT:', balance.USDT) } await exchange.close() ``` ### Watching Multiple Symbols ```typescript const exchange = new ccxt.pro.binance() const symbols = ['BTC/USDT', 'ETH/USDT', 'SOL/USDT'] while (true) { // Watch all symbols concurrently const tickers = await exchange.watchTickers(symbols) for (const symbol in tickers) { console.log(symbol, tickers[symbol].last) } } await exchange.close() ``` ## Complete Method Reference ### Market Data Methods #### Tickers & Prices - `fetchTicker(symbol)` - Fetch ticker for one symbol - `fetchTickers([symbols])` - Fetch multiple tickers at once - `fetchBidsAsks([symbols])` - Fetch best bid/ask for multiple symbols - `fetchLastPrices([symbols])` - Fetch last prices - `fetchMarkPrices([symbols])` - Fetch mark prices (derivatives) #### Order Books - `fetchOrderBook(symbol, limit)` - Fetch order book - `fetchOrderBooks([symbols])` - Fetch multiple order books - `fetchL2OrderBook(symbol)` - Fetch level 2 order book - `fetchL3OrderBook(symbol)` - Fetch level 3 order book (if supported) #### Trades - `fetchTrades(symbol, since, limit)` - Fetch public trades - `fetchMyTrades(symbol, since, limit)` - Fetch your trades (auth required) - `fetchOrderTrades(orderId, symbol)` - Fetch trades for specific order #### OHLCV (Candlesticks) - `fetchOHLCV(symbol, timeframe, since, limit)` - Fetch candlestick data - `fetchIndexOHLCV(symbol, timeframe)` - Fetch index price OHLCV - `fetchMarkOHLCV(symbol, timeframe)` - Fetch mark price OHLCV - `fetchPremiumIndexOHLCV(symbol, timeframe)` - Fetch premium index OHLCV ### Account & Balance - `fetchBalance()` - Fetch account balance (auth required) - `fetchAccounts()` - Fetch sub-accounts - `fetchLedger(code, since, limit)` - Fetch ledger history - `fetchLedgerEntry(id, code)` - Fetch specific ledger entry - `fetchTransactions(code, since, limit)` - Fetch transactions - `fetchDeposits(code, since, limit)` - Fetch deposit history - `fetchWithdrawals(code, since, limit)` - Fetch withdrawal history - `fetchDepositsWithdrawals(code, since, limit)` - Fetch both deposits and withdrawals ### Trading Methods #### Creating Orders - `createOrder(symbol, type, side, amount, price, params)` - Create order (generic) - `createLimitOrder(symbol, side, amount, price)` - Create limit order - `createMarketOrder(symbol, side, amount)` - Create market order - `createLimitBuyOrder(symbol, amount, price)` - Buy limit order - `createLimitSellOrder(symbol, amount, price)` - Sell limit order - `createMarketBuyOrder(symbol, amount)` - Buy market order - `createMarketSellOrder(symbol, amount)` - Sell market order - `createMarketBuyOrderWithCost(symbol, cost)` - Buy with specific cost - `createStopLimitOrder(symbol, side, amount, price, stopPrice)` - Stop-limit order - `createStopMarketOrder(symbol, side, amount, stopPrice)` - Stop-market order - `createStopLossOrder(symbol, side, amount, stopPrice)` - Stop-loss order - `createTakeProfitOrder(symbol, side, amount, takeProfitPrice)` - Take-profit order - `createTrailingAmountOrder(symbol, side, amount, trailingAmount)` - Trailing stop - `createTrailingPercentOrder(symbol, side, amount, trailingPercent)` - Trailing stop % - `createTriggerOrder(symbol, side, amount, triggerPrice)` - Trigger order - `createPostOnlyOrder(symbol, side, amount, price)` - Post-only order - `createReduceOnlyOrder(symbol, side, amount, price)` - Reduce-only order - `createOrders([orders])` - Create multiple orders at once - `createOrderWithTakeProfitAndStopLoss(symbol, type, side, amount, price, tpPrice, slPrice)` - OCO order #### Managing Orders - `fetchOrder(orderId, symbol)` - Fetch single order - `fetchOrders(symbol, since, limit)` - Fetch all orders - `fetchOpenOrders(symbol, since, limit)` - Fetch open orders - `fetchClosedOrders(symbol, since, limit)` - Fetch closed orders - `fetchCanceledOrders(symbol, since, limit)` - Fetch canceled orders - `fetchOpenOrder(orderId, symbol)` - Fetch specific open order - `fetchOrdersByStatus(status, symbol)` - Fetch orders by status - `cancelOrder(orderId, symbol)` - Cancel single order - `cancelOrders([orderIds], symbol)` - Cancel multiple orders - `cancelAllOrders(symbol)` - Cancel all orders for symbol - `editOrder(orderId, symbol, type, side, amount, price)` - Modify order ### Margin & Leverage - `fetchBorrowRate(code)` - Fetch borrow rate for margin - `fetchBorrowRates([codes])` - Fetch multiple borrow rates - `fetchBorrowRateHistory(code, since, limit)` - Historical borrow rates - `fetchCrossBorrowRate(code)` - Cross margin borrow rate - `fetchIsolatedBorrowRate(symbol, code)` - Isolated margin borrow rate - `borrowMargin(code, amount, symbol)` - Borrow margin