Skip to main content
skill CX Codex

ccxt-java — Claude Code skill for CCXT in Java

ccxt-java is a Claude Code skill for using CCXT with Java crypto exchange integrations. It covers REST requests and WebSocket feeds for market data and orders.

MIT 106 installs ★ 44,950 updated 2026-11-18

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ccxt/ccxt --skill ccxt-java -a claude-code
Open on GitHub

What ccxt-java does

ccxt-java guides Java projects through CCXT exchange access, market loading, ticker and order book queries, trade and candle retrieval, order creation, and balance checks. REST operations use fetch* methods; WebSocket updates use watch* methods.

The skill explains typed exchange classes and authentication with apiKey and secret. Java 21 or newer is required because the library uses virtual threads. The library installation instructions cover Gradle and Maven.

What it helps with

  • connect a Java project to a CCXT exchange
  • retrieve tickers, order books, or recent trades
  • stream live prices over WebSocket
  • place orders and check account balances

Example prompts for the agent

  • Connect CCXT to my Java project and fetch the BTC/USDT ticker over REST.
  • Show how to retrieve the BTC/USDT order book and recent trades with CCXT.
  • Set up a Java WebSocket subscription for the BTC/USDT ticker.

How to install ccxt-java

1Skills CLI (Vercel)

npx skills add ccxt/ccxt --skill ccxt-java -a claude-code

2Manually: put the files in place

~/.claude/skills/ccxt-java/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ccxt-java/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ccxt-java

How do I install ccxt-java in Claude Code?

Run npx skills add ccxt/ccxt --skill ccxt-java -a claude-code. The skill file is placed at ~/.claude/skills/ccxt-java/SKILL.md.

What does ccxt-java do?

It guides Java use of CCXT to connect to crypto exchanges through REST and WebSocket APIs. Topics include market data, orders, authentication, and error handling.

Which Java version does ccxt-java require?

Java 21 or newer is required.

Source text

SKILL.md · MIT
---
name: ccxt-java
description: CCXT cryptocurrency exchange library for Java developers. Covers both REST API (standard) and WebSocket API (real-time). Helps install CCXT, connect to exchanges, fetch market data, place orders, stream live tickers/orderbooks, handle authentication, and manage errors in Java projects. Use when working with crypto exchanges in Java applications, trading systems, or financial software. Requires Java 21+.
---

# CCXT for Java

A comprehensive guide to using CCXT in Java projects for cryptocurrency exchange integration.

## Installation

### Via Gradle
```groovy
// build.gradle
repositories {
    mavenCentral()
}
dependencies {
    implementation 'io.github.ccxt:ccxt:latest.release'
}
```

### Via Maven
```xml
<dependency>
    <groupId>io.github.ccxt</groupId>
    <artifactId>ccxt</artifactId>
    <version>LATEST</version>
</dependency>
```

### Requirements
- Java 21 or higher (uses virtual threads)

## Quick Start

### REST API
```java
import io.github.ccxt.exchanges.Binance;
import io.github.ccxt.types.Ticker;

Binance exchange = new Binance();
exchange.loadMarkets(false);
Ticker ticker = exchange.fetchTicker("BTC/USDT");
System.out.println(ticker.last);
```

### WebSocket API - Real-time Updates
```java
import io.github.ccxt.exchanges.pro.Binance;

var exchange = new Binance();
exchange.loadMarkets(false);
while (true) {
    Ticker ticker = exchange.watchTicker("BTC/USDT"); // typed sync, blocks for one update
    System.out.println(ticker.last);
}
```

## Architecture: Typed Subclasses

Each exchange has two classes following the Go pattern:
- `BinanceCore` - transpiled untyped class (internal, extends `BinanceApi` extends `Exchange`)
- `Binance` - typed wrapper extending Core with typed overloads (user-facing)

```java
// User-facing typed class (recommended)
Binance exchange = new Binance();
Ticker ticker = exchange.fetchTicker("BTC/USDT");       // returns Ticker
List<Trade> trades = exchange.fetchTrades("BTC/USDT");   // returns List<Trade>

// Exchange-specific implicit API methods are also accessible
Object raw = exchange.publicGetTicker24hr(params).join(); // Binance-specific endpoint

// Properties accessible directly
exchange.apiKey = "...";
exchange.secret = "...";
```

The typed methods use Java method overloading. They coexist safely with untyped methods because Java resolves overloads at compile time: `BinanceCore.java` is compiled without knowledge of `Binance.java`'s typed overloads, so internal calls always bind to untyped varargs.

## REST vs WebSocket

| Feature | REST API | WebSocket API |
|---------|----------|---------------|
| **Use for** | One-time queries, placing orders | Real-time monitoring, live price feeds |
| **Import** | `io.github.ccxt.exchanges.Binance` | `io.github.ccxt.exchanges.pro.Binance` |
| **Methods** | `fetch*` (fetchTicker, fetchOrderBook) | `watch*` (watchTicker, watchOrderBook) |
| **Returns** | Typed objects (Ticker, List\<Trade\>) | `CompletableFuture<Object>` (call `.join()`) |
| **Speed** | Slower (HTTP request/response) | Faster (persistent connection) |
| **Rate limits** | Strict (1-2 req/sec) | More lenient (continuous stream) |
| **Best for** | Trading, account management | Price monitoring, arbitrage detection |

## Creating Exchange Instance

### REST API
```java
import io.github.ccxt.exchanges.Binance;
import java.util.Map;
import java.util.HashMap;

// Public API (no authentication)
Binance exchange = new Binance();

// Private API (with authentication)
Map<String, Object> config = new HashMap<>();
config.put("apiKey", "YOUR_API_KEY");
config.put("secret", "YOUR_SECRET");
Binance exchange = new Binance(config);
```

### WebSocket API
```java
import io.github.ccxt.exchanges.pro.Binance;

// Public WebSocket
var exchange = new Binance();

// Private WebSocket (with authentication)
Map<String, Object> config = new HashMap<>();
config.put("apiKey", "YOUR_API_KEY");
config.put("secret", "YOUR_SECRET");
var exchange = new Binance(config);
```

### Dynamic Instantiation (generic, untyped)
```java
import io.github.ccxt.Exchange;

// Returns BaseExchange; cast to Exchange to get the typed unified methods for any venue
Exchange exchange = (Exchange) Exchange.dynamicallyCreateInstance("binance", config);
Ticker ticker = exchange.fetchTicker("BTC/USDT");
```

## Common REST Operations

### Loading Markets
```java
// Load all available trading pairs (typed)
Map<String, MarketInterface> markets = exchange.loadMarkets(false);

// Access market information
MarketInterface btcMarket = markets.get("BTC/USDT");
System.out.println(btcMarket.base);    // "BTC"
System.out.println(btcMarket.quote);   // "USDT"
System.out.println(btcMarket.active);  // true
```

### Fetching Ticker
```java
// Single ticker (typed)
Ticker ticker = exchange.fetchTicker("BTC/USDT");
System.out.println(ticker.last);      // Last price
System.out.println(ticker.bid);       // Best bid
System.out.println(ticker.ask);       // Best ask
System.out.println(ticker.baseVolume); // 24h volume

// Async variant
CompletableFuture<Ticker> future = exchange.fetchTickerAsync("BTC/USDT", null);
```

### Fetching Order Book
```java
// Full orderbook (typed)
OrderBook orderbook = exchange.fetchOrderBook("BTC/USDT");
System.out.println(orderbook.bids.get(0)); // [price, amount]
System.out.println(orderbook.asks.get(0)); // [price, amount]

// Limited depth
OrderBook orderbook = exchange.fetchOrderBook("BTC/USDT", 5L);
```

### Fetching Trades
```java
// Recent public trades (typed)
List<Trade> trades = exchange.fetchTrades("BTC/USDT");
for (Trade t : trades) {
    System.out.println(t.datetime + " " + t.side + " " + t.price + " x " + t.amount);
}

// Optional positional args: pass null to skip one (since), stop before params
List<Trade> trades = exchange.fetchTrades("BTC/USDT", null, 20L);
```

### Fetching OHLCV (Candlesticks)
```java
List<OHLCV> candles = exchange.fetchOHLCV("BTC/USDT", "1h", null, 10L); // typed overloads take up to 4 args
for (OHLCV c : candles) {
    System.out.println(c.timestamp + " O:" + c.open + " H:" + c.high + " L:" + c.low + " C:" + c.close);
}
```

### Creating Orders

#### Limit Order
```java
// Buy limit order (typed)
Order order = exchange.createOrder("BTC/USDT", "limit", "buy", 0.01, 50000.0);
System.out.println(order.id);

// Sell limit order
Order order = exchange.createOrder("BTC/USDT", "limit", "sell", 0.01, 60000.0);
```

#### Market Order
```java
// Buy market order
Order order = exchange.createOrder("BTC/USDT", "market", "buy", 0.01);

// Sell market order
Order order = exchange.createOrder("BTC/USDT", "market", "sell", 0.01);
```

### Fetching Balance
```java
Balances balance = exchange.fetchBalance();
// Access via the info map
System.out.println(balance);
```

### Fetching Orders
```java
// Open orders
List<Order> openOrders = exchange.fetchOpenOrders("BTC/USDT");

// Closed orders
List<Order> closedOrders = exchange.fetchClosedOrders("BTC/USDT");

// Single order by ID
Order order = exchange.fetchOrder("orderId123", "BTC/USDT");
```

### Canceling Orders
```java
// Cancel single order
Order cancelled = exchange.cancelOrder("orderId123", "BTC/USDT");

// Cancel all orders for a symbol
List<Order> cancelled = exchange.cancelAllOrdersAsync("BTC/USDT", null).join(); // no typed sync overload
```

## Exchange-Specific (Implicit) API

Each exchange class inherits exchange-specific endpoint methods from its Api class. These return `CompletableFuture<Object>` (untyped):

```java
import io.github.ccxt.exchanges.Binance;

Binance exchange = new Binance();
exchange.loadMarkets(false);

// Binance-specific public endpoints
Map<String, Object> params = new HashMap<>();
params.put("symbol", "BTCUSDT");
Object rawTicker = exchange.publicGetTicker24hr(params).join();

// Binance-specific private endpoints (requires auth)
Object accountInfo = exchange.sapiGetAccountInfo(null).join();

// Access raw exchange info
Object exchangeInfo = exchange.publicGetExchangeInfo(null).join();
```

## WebSocket Operations (Real-time)

WebSocket classes are in `io.github.ccxt.exchanges.pro`. They return `CompletableFuture<Object>`:

### Watching Ticker
```java
import io.github.ccxt.exchanges.pro.Binance;

var exchange = new Binance();
exchange.loadMarkets(false);
while (true) {
    Ticker ticker = exchange.watchTicker("BTC/USDT"); // typed sync, blocks for one update
    System.out.println("Last: " + ticker.last);
}
```

### Watching Order Book
```java
var exchange = new Binance();
exchange.loadMarkets(false);
while (true) {
    OrderBook ob = exchange.watchOrderBook("BTC/USDT");
    System.out.println("Best bid: " + ob.bids.get(0));
}
```

### Watching Trades
```java
var exchange = new Binance();
exchange.loadMarkets(false);
while (true) {
    List<Trade> trades = exchange.watchTrades("BTC/USDT");
    for (Trade t : trades) {
        System.out.println(t.price + " " + t.amount + " " + t.side);
    }
}
```

### Watching Your Orders (Private)
```java
Map<String, Object> config = Map.of("apiKey", "KEY", "secret", "SECRET");
var exchange = new Binance(config);
exchange.loadMarkets(false);
while (true) {
    List<Order> orders = exchange.watchOrders("BTC/USDT");
    System.out.println(orders);
}
```

## Sync vs Async

Java CCXT provides three patterns — and the symmetry applies to both REST `fetch*` and WS `watch*` methods.

### 1. Typed Sync (blocking)
```java
// REST — blocks until one HTTP response
Binance exchange = new Binance();
Ticker ticker = exchange.fetchTicker("BTC/USDT");

// WS — blocks until one streaming update
var wsExchange = new io.github.ccxt.exchanges.pro.Binance();
Ticker tick = wsExchange.watchTicker("BTC/USDT");
```

### 2. Typed Async (non-blocking)
```java
// REST async
CompletableFuture<Ticker> future = exchange.fetchTickerAsync("BTC/USDT", null);
future.thenAccept(ticker -> System.out.println(ticker.last));

// WS async — same shape, returns CompletableFuture<Ticker> that completes on next update
CompletableFuture<Ticker> wsFuture = wsExchange.watchTickerAsync("BTC/USDT", null);
wsFuture.thenAccept(tick -> System.out.println(tick.last));

// Compose multiple watches without blocking the calling thread:
CompletableFuture.allOf(
    wsExchange.watchTickerAsync("BTC/USDT", null),
    wsExchange.watchOrderBookAsync("ETH/USDT", null, null)
).join();
```

Every typed `fetch*` and `watch*` method has a matching `*Async` overload at every supported arity, including zero-arg (where the method allows it). Same return-type symmetry: `Ticker fetchTicker(...)` ↔ `CompletableFuture<Ticker> fetchTickerAsync(...)`; `Tickers watchTickers(...)` ↔ `CompletableFuture<Tickers> watchTickersAsync(...)`.

### 3. Full-arity calls (CompletableFuture)
```java
// passing params (even null) selects the full-arity overload, which returns a future
Exchange exchange = (Exchange) Exchange.dynamicallyCreateInstance("binance", null);
Ticker result = exchange.fetchTicker("BTC/USDT", new HashMap<>()).join();
```

## Testnet, Capabilities, Precision and Pagination

```java
Binance exchange = new Binance();
exchange.apiKey = "...";
exchange.secret = "...";
exchange.setSandboxMode(true);          // right after construction; NotSupported if no testnet

// capability flags and finer-grained features (keys stay camelCase)
Object supported = exchange.has.get("fetchOHLCV");   // true | false | "emulated"
Object spotFeatures = exchange.features.get("spot"); // createOrder params, fetch limits, ...

// round to the market's precision before ordering (returns strings)
exchange.loadMarkets(false);
String amount = exchange.amountToPrecision("BTC/USDT", 0.0012345);
String price = exchange.priceToPrecision("BTC/USDT", 64123.456789);

// let CCXT paginate history for you
Map<String, Object> params = new HashMap<>();
params.put("paginate", true);
// with params use the *Async overload and join (the 5-arg fetchOHLCV returns a CompletableFuture)
List<OHLCV> history = exchange.fetchOHLCVAsync("BTC/USDT", "1d", 1704067200000L, null, params).join();
```

Conditional orders use unified `params` keys on `createOrder`: `triggerPrice`, `stopLossPrice`, `takeProfitPrice`, `reduceOnly`, `postOnly`, `clientOrderId`. Every `watch*` stream has an `unWatch*` (for example `unWatchTicker(symbol, params)`); `close()` stops them all. Always test orders on a testnet or at the minimum size first.

## Complete Method Reference

### Market Data Methods

#### Tickers & Prices
- `fetchTicker(symbol)` - Fetch ticker for one symbol
- `fetchTickers(symbols, params)` - Fetch multiple tickers
- `fetchBidsAsks(symbols, params)` - Fetch best bid/ask
- `fetchLastPrices(symbols, params)` - Fetch last prices
- `fetchMarkPrice(symbol, params)` - Fetch mark price (derivatives)

#### Order Books
- `fetchOrderBook(symbol, limit, params)` - Fetch order book

#### Trades
- `fetchTrades(symbol, since, limit, params)` - Fetch public trades
- `fetchMyTrades(symbol, since, limit, params)` - Fetch your trades (auth required)

#### OHLCV (Candlesticks)
- `fetchOHLCV(symbol, timeframe, since, limit, params)` - Fetch candlestick data

### Account & Balance
- `fetchBalance(params)` - Fetch account balance (auth required)
- `fetchAccounts(params)` - Fetch sub-accounts
- `fetchLedger(code, since, limit, params)` - Fetch ledger history

### Trading Methods

#### Creating Orders
- `createOrder(symbol, type, side, amount, price, params)` - Create order
- `createOrders(orders, params)` - Create multiple orders
- `editOrder(id, symbol, type, side, amount, price, params)` - Modify order

#### Managing Orders
- `fetchOrder(id, symbol, params)` - Fetch single order
- `fetchOrders(symbol, since, limit, params)` - Fetch all orders
- `fetchOpenOrders(symbol, since, limit, params)` - Fetch open orders
- `fetchClosedOrders(symbol, since, limit, params)` - Fetch closed orders
- `cancelOrder(id, symbol, params)` - Cancel single order
- `cancelAllOrders(symbol, params)` - Cancel all orders

### Derivatives & Futures
- `fetchPosition(symbol, params)` - Fetch single position
- `fetchPositions(symbols, params)` - Fetch all positions
- `fetchFundingRate(symbol, params)` - Current funding rate
- `fetchFundingRateHistory(symbol, since, limit, params)` - Funding rate history
- `setLeverage(leverage, symbol, params)` - Set leverage
- `setMarginMode(marginMode, symbol, params)` - Set margin mode

### Deposits & Withdrawals
- `fetchDepositAddress(code, params)` - Get deposit address
- `withdraw(code, amount, address, params)` - Withdraw funds (memo/tag and network go in params: `tag`, `network`)
- `transfer(code, amount, fromAccount, toAccount, params)` - Internal transfer
- `fetchDeposits(code, since, limit, params)` - Fetch deposit history
- `fetchWithdrawals(code, since, limit, params)` - Fetch withdrawal history

### Fees
- `fetchTradingFee(symbol, params)` - Trading fee for symbol
- `fetchTradingFees(params)` - All trading fees

### WebSocket Methods

All REST methods have WebSocket equivalents with `watch*` prefix:
- `watchTicker(symbol)` - Watch single ticker
- `watchTickers(symbols)` - Watch multiple tickers
- `watchOrderBook(symbol)` - Watch order book updates
- `watchTrades(symbol)` - Watch public trades
- `watchOHLCV(symbol, timeframe)` - Watch candlestick updates
- `watchBalance()` - Watch balance updates (auth required)
- `watchOrders(symbol)` - Watch your order updates (auth required)
- `watchMyTrades(symbol)` - Watch your trade updates (auth required)

### Optional Parameters

Typed sync overloads stop **before** `params`; pass `null` to skip an optional positional argument. Any call that passes `params` (even `null`) resolves to the full-arity overload, which returns a `CompletableFuture`. Use the `*Async` form and `.join()`:

```java
// With params: *Async + join
List<Trade> trades = exchange.fetchTradesAsync("BTC/USDT", sinceTimestamp, 100L, extraParams).join();

// Skip an optional positional arg with null, no params
List<Trade> trades = exchange.fetchTrades("BTC/USDT", null, 100L);

// Convenience overload (required params only)
List<Trade> trades = exchange.fetchTrades("BTC/USDT");
```

## Authentication

### Setting API Keys
```java
Map<String, Object> config = new HashMap<>();
config.put("apiKey", System.getenv("BINANCE_API_KEY"));
config.put("secret", System.getenv("BINANCE_SECRET"));
Binance exchange = new Binance(config);

// Or set after creation
exchange.apiKey = System.getenv("BINANCE_API_KEY");
exchange.secret = System.getenv("BINANCE_SECRET");
```

### Testing Authentication
```java
try {
    Balances balance = exchange.fetchBalance();
    System.out.println("Authentication successful!");
} catch (CompletionException e) {
    if (e.getCause() instanceof AuthenticationError) {
        System.out.println("Invalid API credentials");
    }
}
```

## Error Handling

### Exception Hierarchy
```
BaseError
+- NetworkError (recoverable - retry)
|  +- RequestTimeout
|  +- ExchangeNotAvailable
|  +- RateLimitExceeded
|  +- DDoSProtection
+- ExchangeError (non-recoverable - don't retry)
   +- AuthenticationError
   +- InsufficientFunds
   +- InvalidOrder
   +- BadSymbol
   +- NotSupported
```

### Basic Error Handling

Typed sync methods (`fetchTicker`, `createOrder`, `fetchBalance`, etc.) unwrap
`CompletionException` internally and rethrow the underlying typed ccxt error,
so users write idiomatic Java `try`/`catch` with multiple typed `catch` blocks
in **most-specific → least-specific** order — same shape as catching
`ArrayIndexOutOfBoundsException` / `IOException` from the JDK:

```java
import io.github.ccxt.errors.*;
import io.github.ccxt.exchanges.Binance;
import io.github.ccxt.types.Ticker;

Binance exchange = new Binance();
try {
    Ticker ticker = exchange.fetchTicker("BTC/USDT");
} catch (NetworkError e) {
    System.out.println("Network error - retry: " + e.getMessage());
} catch (ExchangeError e) {
    System.out.println("Exchange error - do not retry: " + e.getMessage());
}
```

No `CompletionException` boilerplate, no `.getCause()` unwrap needed.

#### Java pitfalls when catching ccxt errors

1. **You cannot multi-catch a parent and child error together.** Java forbids it:
   ```java
   // ❌ compile error — BaseError is parent of NetworkError
   catch (NetworkError | BaseError e) { ... }

   // ✅ separate clauses, most-specific first
   catch (NetworkError e) { ... }
   catch (BaseError e) { ... }
   ```

2. **Passing `params` (or `null` in its place) returns a `CompletableFuture`.** Typed sync
   overloads stop before `params`, so `fetchBalance()` returns `Balances`, but
   `fetchBalance(params)` and `fetchBalance((Map<String, Object>) null)` resolve to the full-arity
   method, which returns `CompletableFuture<Balances>`. The same holds for every method
   (`createOrder(..., price, params)`, `fetchOHLCV(..., limit, params)`, ...):
   ```java
   // ❌ incompatible types: CompletableFuture<Balances> cannot be converted to Balances
   Balances b = exchange.fetchBalance((Map<String, Object>) null);

   // ✅ typed overload without params
   Balances b = exchange.fetchBalance();

   // ✅ with params: the *Async overload, then join
   Balances b = exchange.fetchBalanceAsync(params).join();
   ```

3. **The JVM stays alive after `main()` returns** because of internal HTTP/scheduler threads
   (Netty event loop, virtual-thread executors per WS connection). Call `exchange.close()` to
   release them; as a last resort `System.exit(0)` will force-exit. Avoid `Runtime.addShutdownHook`
   — a shutdown hook runs *during* JVM shutdown, it doesn't trigger one.

### Specific Exception Handling

Multi-catch and ordering work exactly as JDK conventions expect:

```java
try {
    Order order = exchange.createOrder("BTC/USDT", "limit", "buy", 0.01, 50000.0);
} catch (InsufficientFunds e) {
    System.out.println("Not enough balance: " + e.getMessage());
} catch (InvalidOrder e) {                                  // covers OrderNotFound, DuplicateOrderId, etc.
    System.out.println("Invalid order params: " + e.getMessage());
} catch (AuthenticationError e) {
    System.out.println("Check your API credentials: " + e.getMessage());
} catch (RateLimitExceeded | DDoSProtection e) {             // multi-catch — same handler for both
    Thread.sleep(30_000);
} catch (NetworkError e) {                                   // any other transient: RequestTimeout, ExchangeNotAvailable
    Thread.sleep(2_000);
} catch (ExchangeError e) {                                  // any other exchange-side error
    System.out.println("Exchange refused: " + e.getMessage());
} catch (BaseError e) {                                      // ccxt catch-all (rare)
    System.out.println("CCXT error: " + e.getMessage());
}
```

Note: each `catch` clause must be for a single class; you cannot multi-catch
`NetworkError | BaseError` because BaseError is a parent of NetworkError.
The order above (most-specific to least-specific) is the JDK convention.

### Async Error Handling

For async methods (`fetchTickerAsync`, `createOrderAsync`, …), the returned
`CompletableFuture` wraps exceptions in `CompletionException`. Use the
`Helpers.unwrap()` helper inside `.exceptionally(...)` to peel the wrapper
and pattern-match the underlying ccxt error:

```java
import io.github.ccxt.Helpers;

exchange.fetchTickerAsync("BTC/USDT")
    .thenAccept(t -> System.out.println(t.last))
    .exceptionally(throwable -> {
        Throwable cause = Helpers.unwrap(throwable);          // peels CompletionException
        return switch (cause) {                                // pattern-matching switch (Java 21+)
            case RateLimitExceeded e   -> { backoff(); yield null; }
            case NetworkError e        -> { retry(); yield null; }
            case AuthenticationError e -> { refreshCredentials(); yield null; }
            case ExchangeError e       -> { logExchangeError(e); yield null; }
            case BaseError e           -> { logCcxtError(e); yield null; }
            default -> throw new java.util.concurrent.CompletionException(cause);
        };
    });
```

If you'd rather block and use the sync exception style, you can also do
`Helpers.joinUnwrapped(future)` instead of calling `.join()` directly — that's
the same helper the typed sync wrappers use internally.

## Rate Limiting

### Built-in Rate Limiter (Enabled by Default)
```java
// Rate limiting is enabled by default
Binance exchange = new Binance();
System.out.println(exchange.enableRateLimit); // true
System.out.println(exchange.rateLimit);       // milliseconds between requests
```

## Proxy Configuration

```java
// HTTP Proxy
exchange.httpProxy = "http://your-proxy-host:port";

// HTTPS Proxy
exchange.httpsProxy = "https://your-proxy-host:port";

// SOCKS Proxy
exchange.socksProxy = "socks://your-proxy-host:port";
```

## Common Pitfalls

### Typed vs Untyped Methods
```java
// Typed (recommended) - use concrete exchange class
Binance exchange = new Binance();
Ticker ticker = exchange.fetchTicker("BTC/USDT");  // returns Ticker

// Dynamic - any venue by id; cast the BaseExchange to Exchange for the typed methods
Exchange exchange = (Exchange) Exchange.dynamicallyCreateInstance("binance", null);
Ticker ticker = exchange.fetchTicker("BTC/USDT");
```

### Passing params changes the return type
```java
// Wrong - passing params (or null for it) picks the full-arity overload: a CompletableFuture
Balances balance = exchange.fetchBalance((Map<String, Object>) null); // does not compile

// Correct - typed overload without params, or *Async + join when you need params
Balances balance = exchange.fetchBalance();
Balances withParams = exchange.fetchBalanceAsync(params).join();
```

### Wrong Symbol Format
```java
// Wrong
"BTCUSDT"    // No separator
"BTC-USDT"   // Dash separator
"btc/usdt"   // Lowercase

// Correct
"BTC/USDT"   // Unified CCXT format
```

### REST for Real-time Monitoring
```java
// Wrong - wastes rate limits
while (true) {
    Ticker ticker = exchange.fetchTicker("BTC/USDT");
    Thread.sleep(1000);
}

// Correct - use WebSocket
var wsExchange = new io.github.ccxt.exchanges.pro.Binance();
wsExchange.loadMarkets(false);
while (true) {
    Ticker ticker = wsExchange.watchTicker("BTC/USDT"); // typed sync
}
```

## Troubleshooting

### Common Issues

**1. "Java 21 required"**
- Solution: CCXT Java requires Java 21+ for virtual threads

**2. "RateLimitExceeded"**
- Solution: Rate limiting is enabled by default. If you disabled it, re-enable with `exchange.enableRateLimit = true`

**3. "AuthenticationError"**
- Solution: Check API key and secret
- Verify API key permissions on exchange
- Check system clock is synced

**4. "NotSupported"**
- Solution: Check `exchange.has` map for method availability before calling

**5. Typed methods not visible**
- Solution: Use the concrete exchange type (`Binance exchange = new Binance()`) not the generic `Exchange` type

### Debugging
```java
// Enable verbose logging
exchange.verbose = true;

// Check exchange capabilities
System.out.println(exchange.has);
```

## Prediction Markets

CCXT supports prediction-market exchanges (Polymarket, Kalshi, Limitless, Myriad, Hyperliquid) under the `io.github.ccxt.exchanges.prediction` package. They use the same unified API, but prices are quoted **0–1** (USDC per outcome share) and the tradeable unit is an **outcome** (e.g. a market's YES/NO token), not a regular market symbol.

```java
import io.github.ccxt.exchanges.prediction.Polymarket;
import io.github.ccxt.types.PredictionOrder;

Polymarket exchange = new Polymarket();
exchange.loadMarkets(false);
// discover events -> markets -> outcomes (each outcome has: outcome (handle),
// outcomeId, market, label); fetchEvents / fetchEvent are available too
// an outcome handle looks like 'TRUMP_OUT_PRESIDENT_2027:YES'
String handle = "TRUMP_OUT_PRESIDENT_2027:YES";
var ticker = exchange.fetchTicker(handle);
var book = exchange.fetchOrderBook(handle);
// limit buy 5 YES shares @ 0.40 USDC (price is 0..1 per share)
PredictionOrder order = exchange.createOrder(handle, "limit", "buy", 5.0, 0.40);
exchange.cancelOrder(order.id, handle);
```

- Price/trade methods (`fetchTicker`, `fetchOrderBook`, `fetchOHLCV`, `fetchTrades`, `createOrder`, `cancelOrder`, …) take an **outcome handle or outcomeId** (the `outcome` parameter), not a market symbol.
- Discover markets via `fetchEvents` / `fetchEvent` (or `loadMarkets`).

## Learn More

- [CCXT Manual](https://docs.ccxt.com/)
- [CCXT Pro Documentation](https://docs.ccxt.com/en/latest/ccxt.pro.html)
- [Supported Exchanges](https://github.com/ccxt/ccxt#supported-cryptocurrency-exchange-markets)
- [GitHub Repository](https://github.com/ccxt/ccxt)

© ccxt · MIT · ccxt/ccxt

Similar skills

All skills for Programming languages →

From the same set9

ccxt-python The ccxt-python skill for Claude Code integrates the CCXT cryptocurrency library for Python REST and WebSocket API trading. It supports market data fetching and order placement. CX Codex +1 2,400installs ccxt-typescript ccxt-typescript is a Claude Code skill that integrates the CCXT cryptocurrency exchange library into TypeScript and JavaScript projects. CX Codex +1 985installs ccxt-cli Teaches the agent to query cryptocurrency exchanges via the ccxt CLI, fetching tickers, OHLCV data, balances, and placing orders from the terminal. CX Codex +1 739installs new-exchange new-exchange scaffolds a new cryptocurrency exchange integration in CCXT on TypeScript, following the certified-exchange template. CX Codex +1 134installs ccxt-go ccxt-go is a Claude Code skill that integrates crypto exchange APIs into Go applications using REST and WebSocket. Runs when writing trading logic, bots, or microservices. CX Codex +1 ★ 44,950repo stars ccxt-csharp ccxt-csharp is a Claude Code skill for connecting CCXT to C# projects and working with crypto exchanges through REST and WebSocket APIs. It applies to exchange setup and market-data tasks. CX Codex +1 ★ 44,950repo stars ccxt-php ccxt-php is a Claude Code skill for using CCXT with PHP cryptocurrency exchange integrations. It covers market queries, order handling, and live data streams. CX Codex +1 ★ 44,950repo stars CCXT Connects AI assistants to 100+ crypto exchanges and prediction platforms via CCXT. It provides market data, balance tracking, and guarded order execution. CX Codex +1 ★ 44,950repo stars

Project sponsors

Companies that keep this analytics open