or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account-management.mderror-handling.mdexchange-management.mdfunding-operations.mdindex.mdmarket-data.mdorder-management.mdtrading-operations.mdutility-functions.mdwebsocket-operations.md
tile.json

index.mddocs/

CCXT - Cryptocurrency Trading Library

CCXT is a comprehensive cryptocurrency trading library that provides a unified API for accessing over 100 cryptocurrency exchanges. It enables developers to access market data, manage portfolios, execute trades, and handle account operations across multiple exchanges using a consistent interface. The library supports both REST API calls for standard operations and WebSocket connections for real-time data streaming.

Package Information

  • Package Name: @iam4x/ccxt
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: 
    npm install @iam4x/ccxt

Core Imports

import ccxt from '@iam4x/ccxt';

For CommonJS:

const ccxt = require('@iam4x/ccxt');

For specific exchanges and utilities:

import ccxt, { binance, Exchange, NetworkError } from '@iam4x/ccxt';

Basic Usage

import ccxt from '@iam4x/ccxt';

// Create exchange instance
const exchange = new ccxt.binance({
  apiKey: 'your-api-key',
  secret: 'your-secret',
  sandbox: true,  // Enable sandbox mode for testing
});

// Fetch market data
const ticker = await exchange.fetchTicker('BTC/USDT');
const orderbook = await exchange.fetchOrderBook('BTC/USDT');
const trades = await exchange.fetchTrades('BTC/USDT');

// Account operations (requires API credentials)
const balance = await exchange.fetchBalance();
const order = await exchange.createLimitBuyOrder('BTC/USDT', 0.001, 50000);

// Handle errors
try {
  const result = await exchange.fetchBalance();
} catch (error) {
  if (error instanceof ccxt.NetworkError) {
    console.log('Network error:', error.message);
  } else if (error instanceof ccxt.ExchangeError) {
    console.log('Exchange error:', error.message);
  }
}

Architecture

CCXT is built around several key components:

  • Exchange Classes: Individual classes for each supported exchange, all extending the base Exchange class
  • Unified API: Consistent method signatures and return formats across all exchanges
  • Error Handling: Comprehensive error hierarchy for different types of failures
  • Type Safety: Full TypeScript support with detailed type definitions
  • Rate Limiting: Built-in rate limiting and request throttling
  • WebSocket Support: Real-time data streaming through the Pro module
  • Multi-Language: Available for JavaScript, Python, PHP, and C#

Capabilities

Exchange Management

Core functionality for creating and configuring exchange instances, with support for 100+ cryptocurrency exchanges including major ones like Binance, Coinbase, Kraken, and OKX.

// Individual exchange classes (100+ available)
class binance extends Exchange { }
class coinbase extends Exchange { }
class kraken extends Exchange { }
class okx extends Exchange { }
// ... and 96+ more exchanges

// Exchange constructor options
interface ExchangeOptions {
  apiKey?: string;
  secret?: string;
  password?: string;
  uid?: string;
  login?: string;
  privateKey?: string;
  walletAddress?: string;
  token?: string;
  sandbox?: boolean;
  timeout?: number;
  rateLimit?: number;
  enableRateLimit?: boolean;
  userAgent?: string;
  headers?: { [key: string]: string };
  proxy?: string;
  httpsProxy?: string;
  socksProxy?: string;
}

Exchange Management

Market Data

Comprehensive market data access including tickers, order books, trade history, OHLCV candlestick data, and market information across all supported exchanges.

// Market data methods
fetchMarkets(params?: Dict): Promise<Market[]>;
fetchTicker(symbol: string, params?: Dict): Promise<Ticker>;
fetchTickers(symbols?: string[], params?: Dict): Promise<Tickers>;
fetchOrderBook(symbol: string, limit?: number, params?: Dict): Promise<OrderBook>;
fetchOHLCV(symbol: string, timeframe?: string, since?: number, limit?: number, params?: Dict): Promise<OHLCV[]>;
fetchTrades(symbol: string, since?: number, limit?: number, params?: Dict): Promise<Trade[]>;

// Market data structures
interface Market {
  id: string;
  symbol: string;
  base: string;
  quote: string;
  active: boolean;
  type: 'spot' | 'margin' | 'swap' | 'future' | 'option';
  spot: boolean;
  margin: boolean;
  swap: boolean;
  future: boolean;
  option: boolean;
  contract: boolean;
  contractSize?: number;
  expiry?: number;
  strike?: number;
  precision: {
    amount: number;
    price: number;
  };
  limits: {
    amount?: { min: number; max: number };
    price?: { min: number; max: number };
    cost?: { min: number; max: number };
  };
  info: any;
}

interface Ticker {
  symbol: string;
  timestamp: number;
  datetime: string;
  high: number;
  low: number;
  bid: number;
  bidVolume?: number;
  ask: number;
  askVolume?: number;
  vwap?: number;
  open: number;
  close: number;
  last: number;
  previousClose?: number;
  change?: number;
  percentage?: number;
  average?: number;
  baseVolume: number;
  quoteVolume: number;
  info: any;
}

Market Data

Account Management

Account operations including balance retrieval, account information, deposit addresses, withdrawal management, and multi-account support for exchanges that offer sub-accounts.

fetchBalance(params?: Dict): Promise<Balances>;
fetchAccounts(params?: Dict): Promise<Account[]>;
fetchPositions(symbols?: string[], params?: Dict): Promise<Position[]>;
fetchLedger(code?: string, since?: number, limit?: number, params?: Dict): Promise<LedgerEntry[]>;
createDepositAddress(code: string, params?: Dict): Promise<DepositAddress>;
fetchDepositAddress(code: string, params?: Dict): Promise<DepositAddress>;
fetchDeposits(code?: string, since?: number, limit?: number, params?: Dict): Promise<Transaction[]>;
fetchWithdrawals(code?: string, since?: number, limit?: number, params?: Dict): Promise<Transaction[]>;

interface Balances {
  [currency: string]: {
    free: number;
    used: number;
    total: number;
  };
  info: any;
}

interface Position {
  id?: string;
  symbol: string;
  side: 'long' | 'short';
  amount: number;
  contracts?: number;
  contractSize?: number;
  unrealizedPnl?: number;
  percentage?: number;
  timestamp?: number;
  info: any;
}

Account Management

Order Management

Complete order lifecycle management including creation, modification, cancellation, and monitoring of different order types across spot, margin, and derivatives trading.

createOrder(symbol: string, type: OrderType, side: OrderSide, amount: number, price?: number, params?: Dict): Promise<Order>;
createLimitBuyOrder(symbol: string, amount: number, price: number, params?: Dict): Promise<Order>;
createLimitSellOrder(symbol: string, amount: number, price: number, params?: Dict): Promise<Order>;
createMarketBuyOrder(symbol: string, amount: number, price?: number, params?: Dict): Promise<Order>;
createMarketSellOrder(symbol: string, amount: number, price?: number, params?: Dict): Promise<Order>;
createStopOrder(symbol: string, side: OrderSide, amount: number, price: number, stopPrice: number, params?: Dict): Promise<Order>;
editOrder(id: string, symbol: string, type: OrderType, side: OrderSide, amount?: number, price?: number, params?: Dict): Promise<Order>;
cancelOrder(id: string, symbol?: string, params?: Dict): Promise<Order>;
cancelAllOrders(symbol?: string, params?: Dict): Promise<Order[]>;
fetchOrder(id: string, symbol?: string, params?: Dict): Promise<Order>;
fetchOrders(symbol?: string, since?: number, limit?: number, params?: Dict): Promise<Order[]>;
fetchOpenOrders(symbol?: string, since?: number, limit?: number, params?: Dict): Promise<Order[]>;
fetchClosedOrders(symbol?: string, since?: number, limit?: number, params?: Dict): Promise<Order[]>;

type OrderType = 'limit' | 'market' | 'stop' | 'stop_limit' | 'trailing_stop';
type OrderSide = 'buy' | 'sell';

interface Order {
  id: string;
  clientOrderId?: string;
  timestamp: number;
  datetime: string;
  lastTradeTimestamp?: number;
  symbol: string;
  type: OrderType;
  side: OrderSide;
  amount: number;
  price?: number;
  stopPrice?: number;
  filled: number;
  remaining: number;
  cost: number;
  trades?: Trade[];
  fee?: {
    currency: string;
    cost: number;
    rate?: number;
  };
  status: 'open' | 'closed' | 'canceled' | 'expired' | 'rejected';
  info: any;
}

Order Management

Trading Operations

Trading execution and history including trade fetching, order-trade relationships, and portfolio management operations for active trading workflows.

fetchMyTrades(symbol?: string, since?: number, limit?: number, params?: Dict): Promise<Trade[]>;
fetchOrderTrades(id: string, symbol?: string, since?: number, limit?: number, params?: Dict): Promise<Trade[]>;

interface Trade {
  id: string;
  order?: string;
  timestamp: number;
  datetime: string;
  symbol: string;
  type?: OrderType;
  side: OrderSide;
  amount: number;
  price: number;
  cost: number;
  fee?: {
    currency: string;
    cost: number;
    rate?: number;
  };
  info: any;
}

Trading Operations

Funding Operations

Comprehensive funding management including deposits, withdrawals, internal transfers, and address management for moving funds between exchanges and external wallets.

withdraw(code: string, amount: number, address: string, tag?: string, params?: Dict): Promise<WithdrawalResponse>;
transfer(code: string, amount: number, fromAccount: string, toAccount: string, params?: Dict): Promise<TransferEntry>;

interface WithdrawalResponse {
  id: string;
  txid?: string;
  timestamp: number;
  datetime: string;
  currency: string;
  amount: number;
  address: string;
  tag?: string;
  status: 'pending' | 'ok' | 'failed' | 'canceled';
  fee?: {
    currency: string;
    cost: number;
  };
  info: any;
}

interface DepositAddress {
  currency: string;
  address: string;
  tag?: string;
  network?: string;
  info: any;
}

Funding Operations

WebSocket Operations

Real-time data streaming capabilities for live market data, order updates, balance changes, and position monitoring through WebSocket connections.

// WebSocket methods (available on pro exchanges)
watchTicker(symbol: string, params?: Dict): Promise<Ticker>;
watchOrderBook(symbol: string, limit?: number, params?: Dict): Promise<OrderBook>;
watchOHLCV(symbol: string, timeframe?: string, since?: number, limit?: number, params?: Dict): Promise<OHLCV[]>;
watchTrades(symbol: string, since?: number, limit?: number, params?: Dict): Promise<Trade[]>;
watchOrders(symbol?: string, since?: number, limit?: number, params?: Dict): Promise<Order[]>;
watchBalance(params?: Dict): Promise<Balances>;
watchPositions(symbols?: string[], since?: number, limit?: number, params?: Dict): Promise<Position[]>;

WebSocket Operations

Utility Functions

Comprehensive utility functions for cryptocurrency operations including mathematical precision, cryptographic operations, time handling, and data manipulation.

// Precision arithmetic
class Precise {
  constructor(number: string | number);
  toString(): string;
  static stringAdd(a: string, b: string): string;
  static stringMul(a: string, b: string): string;
  static stringDiv(a: string, b: string): string;
  static stringSub(a: string, b: string): string;
}

// Time functions
function iso8601(timestamp?: number): string;
function parse8601(timestamp: string): number;
function seconds(): number;
function milliseconds(): number;
function now(): number;

// Cryptographic functions  
function hash(request: string | Uint8Array, algorithm: string): string;
function hmac(request: string | Uint8Array, secret: string | Uint8Array, algorithm: string): string;
function ecdsa(request: string, secret: string, algorithm: string): string;

// Encoding functions
function base64ToBinary(str: string): Uint8Array;
function binaryToBase64(bytes: Uint8Array): string;
function urlencode(params: Dict): string;

Utility Functions

Error Handling

Comprehensive error hierarchy providing specific exception types for different failure scenarios, enabling precise error handling and recovery strategies.

// Base error classes
class BaseError extends Error { }
class ExchangeError extends BaseError { }
class OperationFailed extends BaseError { }

// Authentication errors
class AuthenticationError extends ExchangeError { }
class PermissionDenied extends ExchangeError { }
class AccountNotEnabled extends ExchangeError { }
class AccountSuspended extends ExchangeError { }

// Request errors
class ArgumentsRequired extends ExchangeError { }
class BadRequest extends ExchangeError { }
class BadSymbol extends BadRequest { }
class InvalidAddress extends ExchangeError { }

// Order errors
class InvalidOrder extends ExchangeError { }
class OrderNotFound extends ExchangeError { }
class OrderNotCached extends ExchangeError { }
class InsufficientFunds extends ExchangeError { }

// Network errors
class NetworkError extends BaseError { }
class DDoSProtection extends NetworkError { }
class RateLimitExceeded extends NetworkError { }
class ExchangeNotAvailable extends NetworkError { }
class RequestTimeout extends NetworkError { }

// Response errors
class BadResponse extends ExchangeError { }
class NullResponse extends BadResponse { }

Error Handling

Types

// Core data types
type Dict = { [key: string]: any };
type Strings = string[] | undefined;
type OrderBook = {
  symbol: string;
  bids: [number, number][];
  asks: [number, number][];
  timestamp: number;
  datetime: string;
  nonce?: number;
};

type OHLCV = [number, number, number, number, number, number]; // [timestamp, open, high, low, close, volume]

// Exchange capabilities
interface ExchangeCapabilities {
  CORS?: boolean;
  spot?: boolean;
  margin?: boolean;
  swap?: boolean;
  future?: boolean;
  option?: boolean;
  addMargin?: boolean;
  cancelAllOrders?: boolean;
  cancelOrder?: boolean;
  cancelOrders?: boolean;
  createDepositAddress?: boolean;
  createLimitOrder?: boolean;
  createMarketOrder?: boolean;
  createOrder?: boolean;
  deposit?: boolean;
  editOrder?: boolean;
  fetchBalance?: boolean;
  fetchClosedOrders?: boolean;
  fetchCurrencies?: boolean;
  fetchDepositAddress?: boolean;
  fetchDeposits?: boolean;
  fetchMarkets?: boolean;
  fetchMyTrades?: boolean;
  fetchOHLCV?: boolean;
  fetchOpenOrders?: boolean;
  fetchOrder?: boolean;
  fetchOrderBook?: boolean;
  fetchOrders?: boolean;
  fetchStatus?: boolean;
  fetchTicker?: boolean;
  fetchTickers?: boolean;
  fetchTime?: boolean;
  fetchTrades?: boolean;
  fetchTradingFee?: boolean;
  fetchTradingFees?: boolean;
  fetchWithdrawals?: boolean;
  reduceMargin?: boolean;
  setLeverage?: boolean;
  setMargin?: boolean;
  setMarginMode?: boolean;
  setPositionMode?: boolean;
  signIn?: boolean;
  withdraw?: boolean;
}