CCXT

The CCXT integration gives web3agent access to centralized exchange data and trading through the CCXT library. CCXT supports hundreds of exchanges with a unified API, so the same tools work whether you're querying Binance, Coinbase, Kraken, or any other supported exchange.

All CCXT tools use the ccxt_ prefix.

Public vs Private Calls

CCXT tools split into two categories:

Public calls require no authentication. They return market data that exchanges expose openly: tickers, order books, OHLCV candles, and exchange metadata.

Private calls require exchange credentials. They access account-specific data: balances, open orders, positions, and trade history. Private write calls can place and cancel orders.

Tools

Tool	Auth Required	Description
ccxt_list_exchanges	No	List all exchanges supported by CCXT
ccxt_describe_exchange	No	Exchange metadata: markets, timeframes, features
ccxt_list_accounts	No	List configured exchange accounts from credentials file
ccxt_public_call	No	Call any public exchange method (tickers, order books, OHLCV)
ccxt_private_read	Yes	Call a private read method (balances, orders, positions)
ccxt_private_write	Yes	Call a private write method (place order, cancel order)

Public Calls

Public calls work immediately with no setup. Pass the exchange ID and the method name:

// Get ticker for BTC/USDT on Binance
ccxt_public_call({
  exchange: "binance",
  method: "fetchTicker",
  params: { symbol: "BTC/USDT" },
})

// Returns:
// {
//   symbol: "BTC/USDT",
//   last: 67234.50,
//   bid: 67230.00,
//   ask: 67239.00,
//   volume: 45231.8,
//   change: 1.24,
//   percentage: 1.88
// }

// Fetch OHLCV candles
ccxt_public_call({
  exchange: "coinbase",
  method: "fetchOHLCV",
  params: {
    symbol: "ETH/USD",
    timeframe: "1h",
    limit: 24,
  },
})

// Returns array of [timestamp, open, high, low, close, volume]

// Get order book depth
ccxt_public_call({
  exchange: "kraken",
  method: "fetchOrderBook",
  params: {
    symbol: "BTC/USD",
    limit: 20,
  },
})

// Discover what an exchange supports
ccxt_describe_exchange({
  exchange: "hyperliquid",
})

// Returns: { markets, timeframes, has: { fetchTicker, createOrder, ... }, urls, ... }

Private Calls

Private calls require exchange credentials configured in a JSON file. Set the path with CCXT_CONFIG_PATH:

CCXT_CONFIG_PATH=/path/to/exchange-credentials.json npx web3agent

Credentials File Format

{
  "accounts": [
    {
      "id": "binance-main",
      "exchange": "binance",
      "apiKey": "your_api_key",
      "secret": "your_secret_key"
    },
    {
      "id": "hyperliquid-trading",
      "exchange": "hyperliquid",
      "apiKey": "your_wallet_address",
      "secret": "your_private_key",
      "options": {
        "defaultType": "swap"
      }
    }
  ]
}

Each account has an id that you reference in tool calls. Multiple accounts on the same exchange are supported.

Listing Configured Accounts

ccxt_list_accounts()

// Returns:
// [
//   { id: "binance-main", exchange: "binance" },
//   { id: "hyperliquid-trading", exchange: "hyperliquid" }
// ]

Private Read Calls

// Fetch account balance
ccxt_private_read({
  accountId: "binance-main",
  method: "fetchBalance",
  params: {},
})

// Returns:
// {
//   total: { USDT: 5000.00, BTC: 0.15, ETH: 2.3 },
//   free: { USDT: 4500.00, BTC: 0.15, ETH: 2.3 },
//   used: { USDT: 500.00 }
// }

// Fetch open orders
ccxt_private_read({
  accountId: "binance-main",
  method: "fetchOpenOrders",
  params: { symbol: "BTC/USDT" },
})

// Fetch positions (for futures/perps)
ccxt_private_read({
  accountId: "hyperliquid-trading",
  method: "fetchPositions",
  params: {},
})

// Returns array of open positions with size, entry price, unrealized PnL, leverage

// Fetch trade history
ccxt_private_read({
  accountId: "binance-main",
  method: "fetchMyTrades",
  params: {
    symbol: "ETH/USDT",
    limit: 50,
  },
})

Private Write Calls

Write calls place or cancel orders. They go through the confirmation queue when CONFIRM_WRITES=true.

// Place a market buy order
ccxt_private_write({
  accountId: "binance-main",
  method: "createOrder",
  params: {
    symbol: "ETH/USDT",
    type: "market",
    side: "buy",
    amount: 0.5,
  },
})

// Place a limit sell order
ccxt_private_write({
  accountId: "binance-main",
  method: "createOrder",
  params: {
    symbol: "ETH/USDT",
    type: "limit",
    side: "sell",
    amount: 0.5,
    price: 4000.00,
  },
})

// Cancel an order
ccxt_private_write({
  accountId: "binance-main",
  method: "cancelOrder",
  params: {
    id: "order_id_here",
    symbol: "ETH/USDT",
  },
})

Finding Available Methods

Not every exchange supports every method. Use ccxt_describe_exchange to check what's available:

ccxt_describe_exchange({
  exchange: "binance",
})

// The "has" field lists supported methods:
// {
//   has: {
//     fetchTicker: true,
//     fetchOHLCV: true,
//     createOrder: true,
//     fetchPositions: true,
//     ...
//   }
// }

Security Considerations

The credentials file contains sensitive API keys and private keys. Keep it outside version control and restrict file permissions:

chmod 600 /path/to/exchange-credentials.json

For exchanges that support it, create API keys with the minimum required permissions. Read-only keys work for balance and position queries. Only enable trading permissions if the agent needs to place orders.

Private write calls are gated by the confirmation system by default. Set CONFIRM_WRITES=false only for fully autonomous trading agents where human approval isn't practical.

Supported Exchanges

CCXT supports 100+ exchanges. Common ones include:

Binance, Coinbase, Kraken, OKX, Bybit, Bitfinex, Huobi, KuCoin, Gate.io, Hyperliquid, dYdX, and many more.

Run ccxt_list_exchanges to see the full list, or check the CCXT documentation for the complete exchange catalog.