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
npx skills add ccxt/ccxt --skill ccxt-java -a claude-codeWhat 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/USDTticker over REST. - Show how to retrieve the
BTC/USDTorder book and recent trades with CCXT. - Set up a Java WebSocket subscription for the
BTC/USDTticker.
How to install ccxt-java
1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill ccxt-java -a claude-code2Manually: put the files in place
~/.claude/skills/ccxt-java/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ccxt-java/
1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill ccxt-java -a codex2Manually: put the files in place
.agents/skills/ccxt-java/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill ccxt-java -a cursor2Manually: put the files in place
.cursor/skills/ccxt-java/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ccxt/ccxt .claude/skills/ccxt-java2Manually: put the files in place
.github/skills/ccxt-java/SKILL.md1Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill ccxt-java -a gemini-cli2Platform CLI
gemini skills install https://github.com/ccxt/ccxt --path .claude/skills/ccxt-javaManually: put the files in place
.devin/skills/ccxt-java/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ccxt/ccxt --skill ccxt-java -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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