ccxt 4.5.55 → 4.5.56

package/README.md

@@ -2,7 +2,7 @@
 
 [![NPM Downloads](https://img.shields.io/npm/dy/ccxt.svg)](https://www.npmjs.com/package/ccxt) [![npm](https://img.shields.io/npm/v/ccxt.svg)](https://npmjs.com/package/ccxt) [![PyPI](https://img.shields.io/pypi/v/ccxt.svg)](https://pypi.python.org/pypi/ccxt) [![NuGet version](https://img.shields.io/nuget/v/ccxt)](https://www.nuget.org/packages/ccxt) [![GoDoc](https://pkg.go.dev/badge/github.com/ccxt/ccxt/go/v4?utm_source=godoc)](https://godoc.org/github.com/ccxt/ccxt/go/v4) [![Discord](https://img.shields.io/discord/690203284119617602?logo=discord&logoColor=white)](https://discord.gg/ccxt) [![Supported Exchanges](https://img.shields.io/badge/exchanges-111-blue.svg)](https://github.com/ccxt/ccxt/wiki/Exchange-Markets) [![Follow CCXT at x.com](https://img.shields.io/twitter/follow/ccxt_official.svg?style=social&label=CCXT)](https://x.com/ccxt_official)
 
-A cryptocurrency trading API with more than 100 exchanges in JavaScript / TypeScript / Python / C# / PHP / Go.
+A cryptocurrency trading API with more than 100 exchanges in JavaScript / TypeScript / Python / C# / PHP / Go / Java.
 
 ### [Install](#install) · [Usage](#usage) · [Manual](https://github.com/ccxt/ccxt/wiki) · [FAQ](https://github.com/ccxt/ccxt/wiki/FAQ) · [Examples](https://github.com/ccxt/ccxt/tree/master/examples) · [Contributing](https://github.com/ccxt/ccxt/blob/master/CONTRIBUTING.md) · [Disclaimer](#disclaimer) · [Social](#social)
 
@@ -16,7 +16,7 @@ Current feature list:
 - fully implemented public and private APIs
 - optional normalized data for cross-exchange analytics and arbitrage
 - an out of the box unified API that is extremely easy to integrate
-- works in Node 10.4+, Python 3, PHP 8.1+, netstandard2.0/2.1, Go 1.20+ and web browsers
+- works in Node 10.4+, Python 3, PHP 8.1+, netstandard2.0/2.1, Go 1.20+, Java 21+ and web browsers
 
 ## See Also
 
@@ -198,6 +198,7 @@ The easiest way to install the CCXT library is to use a package manager:
 - [ccxt in **Packagist/Composer**](https://packagist.org/packages/ccxt/ccxt) (PHP 8.1+)
 - [ccxt in **Nuget**](https://www.nuget.org/packages/ccxt) (netstandard 2.0)
 - [ccxt in **GO**](https://pkg.go.dev/github.com/ccxt/ccxt/go/v4)
+- ccxt in **Java** (Java 21+, Gradle)
 
 This library is shipped as an all-in-one module implementation with minimalistic dependencies and requirements:
 
@@ -206,6 +207,7 @@ This library is shipped as an all-in-one module implementation with minimalistic
 - [php/](https://github.com/ccxt/ccxt/blob/master/php/) in PHP (generated from TS)
 - [cs/](https://github.com/ccxt/ccxt/blob/master/cs/)  in C# (generated from TS)
 - [go/](https://github.com/ccxt/ccxt/blob/master/go/)  in Go (generated from TS)
+- [java/](https://github.com/ccxt/ccxt/blob/master/java/) in Java (generated from TS)
 
 You can also clone it into your project directory from [ccxt GitHub repository](https://github.com/ccxt/ccxt):
 
@@ -242,13 +244,13 @@ console.log(version, Object.keys(exchanges));
 
 All-in-one browser bundle (dependencies included), served from a CDN of your choice:
 
-* jsDelivr: https://cdn.jsdelivr.net/npm/ccxt@4.5.55/dist/ccxt.browser.min.js
-* unpkg: https://unpkg.com/ccxt@4.5.55/dist/ccxt.browser.min.js
+* jsDelivr: https://cdn.jsdelivr.net/npm/ccxt@4.5.56/dist/ccxt.browser.min.js
+* unpkg: https://unpkg.com/ccxt@4.5.56/dist/ccxt.browser.min.js
 
 CDNs are not updated in real-time and may have delays. Defaulting to the most recent version without specifying the version number is not recommended. Please, keep in mind that we are not responsible for the correct operation of those CDN servers.
 
 ```HTML
-<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/ccxt@4.5.55/dist/ccxt.browser.min.js"></script>
+<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/ccxt@4.5.56/dist/ccxt.browser.min.js"></script>
 ```
 
 Creates a global `ccxt` object:
@@ -337,6 +339,65 @@ import "ccxt"
 fmt.Println(ccxt.Exchanges)
 ```
 
+### Java
+
+Java version of CCXT requires Java 21+ and uses Gradle as its build system.
+
+Add the CCXT library as a local dependency in your `build.gradle.kts`:
+
+```kotlin
+dependencies {
+    implementation("io.github.ccxt:ccxt:4.5.52")
+}
+```
+
+Or clone and build from source:
+
+```shell
+git clone https://github.com/ccxt/ccxt.git --depth 1
+cd ccxt/java
+./gradlew :lib:build
+```
+
+```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.symbol + " " + ticker.last);
+```
+
+Each exchange has its own typed subclass with strongly-typed return values. Every typed method ships both a blocking sync and a non-blocking `CompletableFuture`-returning async overload — pick the idiom that fits your call site:
+
+```Java
+// Sync — blocks until the response arrives
+Ticker ticker = exchange.fetchTicker("BTC/USDT");
+
+// Async — returns immediately, completes when the response arrives
+CompletableFuture<Ticker> future = exchange.fetchTickerAsync("BTC/USDT", null);
+future.thenAccept(t -> System.out.println(t.last));
+```
+
+WebSocket support is available via the pro exchange classes, with the same sync/async symmetry — `watchTicker` blocks for one update; `watchTickerAsync` returns a `CompletableFuture<Ticker>` you can compose:
+
+```Java
+import io.github.ccxt.exchanges.pro.Binance;
+
+var exchange = new Binance();
+exchange.loadMarkets(false);
+
+// Sync — blocks for one update
+Ticker tick = exchange.watchTicker("BTC/USDT");
+
+// Async — returns a typed CompletableFuture (composable with allOf, anyOf, etc.)
+CompletableFuture<Ticker> future = exchange.watchTickerAsync("BTC/USDT", null);
+```
+
+See [java/examples/](https://github.com/ccxt/ccxt/tree/master/java/examples) for more usage examples.
+
 ### Docker
 
 You can get CCXT installed in a container along with all the supported languages and dependencies. This may be useful if you want to contribute to CCXT (e.g. run the build scripts and tests — please see the [Contributing](https://github.com/ccxt/ccxt/blob/master/CONTRIBUTING.md) document for the details on that).
@@ -645,6 +706,149 @@ Lastly, just because the signature dictates that some argument like `symbol` is
 
 You can check different examples in the `examples/go` folder.
 
+### Java
+
+```Java
+import io.github.ccxt.exchanges.Kraken;
+import io.github.ccxt.exchanges.Bitfinex;
+import io.github.ccxt.exchanges.Binance;
+import io.github.ccxt.types.*;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class Example {
+    public static void main(String[] args) {
+        // Create exchange instances
+        Kraken kraken = new Kraken();
+        Bitfinex bitfinex = new Bitfinex();
+
+        Map<String, Object> config = new HashMap<>();
+        config.put("apiKey", "YOUR_API_KEY");
+        config.put("secret", "YOUR_SECRET");
+        Binance binance = new Binance(config);
+
+        // Load markets
+        kraken.loadMarkets(false);
+        binance.loadMarkets(false);
+
+        // Public API
+        OrderBook orderBook = kraken.fetchOrderBook("BTC/USDT");
+        Ticker ticker = bitfinex.fetchTicker("BTC/USD");
+        System.out.println(ticker.symbol + " last=" + ticker.last);
+
+        // Fetch OHLCV
+        var candles = binance.fetchOHLCV("BTC/USDT", "1h", null, 10L, null);
+        System.out.println("Got " + candles.size() + " candles");
+
+        // Private API (requires API keys)
+        Balances balance = binance.fetchBalance();
+        System.out.println("BTC free: " + balance.free.get("BTC"));
+
+        // Place a limit buy order
+        Order order = binance.createLimitBuyOrder("BTC/USDT", 0.001, 50000.0);
+        System.out.println("Order id: " + order.id + " status: " + order.status);
+
+        // Cancel it
+        binance.cancelOrder(order.id, "BTC/USDT", null);
+    }
+}
+```
+
+#### Async
+
+All methods are also available as async variants returning `CompletableFuture`:
+
+```Java
+import java.util.concurrent.CompletableFuture;
+
+// Fire multiple requests concurrently
+CompletableFuture<Ticker> btc = binance.fetchTickerAsync("BTC/USDT", null);
+CompletableFuture<Ticker> eth = binance.fetchTickerAsync("ETH/USDT", null);
+CompletableFuture.allOf(btc, eth).join();
+System.out.println("BTC: " + btc.get().last + " ETH: " + eth.get().last);
+```
+
+#### Error handling
+
+Typed sync methods throw the underlying ccxt error directly — no `CompletionException`
+unwrap needed. Catch exceptions in standard JDK order (most-specific first), like you
+would with any other Java library:
+
+```Java
+import io.github.ccxt.errors.*;
+import io.github.ccxt.exchanges.Binance;
+import io.github.ccxt.types.Order;
+
+Binance binance = new Binance(Map.of("apiKey", "...", "secret", "..."));
+try {
+    Order order = binance.createOrder("BTC/USDT", "limit", "buy", 0.001, 50000.0);
+} catch (InsufficientFunds e) {
+    // user error — show balance, don't retry
+} catch (InvalidOrder e) {                        // covers OrderNotFound, DuplicateOrderId, …
+    // user error — fix params
+} catch (AuthenticationError e) {                 // covers PermissionDenied, AccountSuspended
+    // refresh credentials
+} catch (RateLimitExceeded | DDoSProtection e) {  // multi-catch (Java 7+)
+    Thread.sleep(30_000);
+} catch (NetworkError e) {                        // RequestTimeout, ExchangeNotAvailable, …
+    Thread.sleep(2_000);                          // transient — retry
+} catch (ExchangeError e) {                       // any other exchange-side error
+    // exchange refused
+} catch (BaseError e) {                           // ccxt catch-all
+    // unknown ccxt error
+}
+```
+
+For async methods, `CompletableFuture` wraps thrown errors in `CompletionException`
+(JDK behaviour). Use `Helpers.unwrap()` inside `.exceptionally(...)` to peel the wrap
+and pattern-match the real cause:
+
+```Java
+import io.github.ccxt.Helpers;
+
+binance.createOrderAsync("BTC/USDT", "limit", "buy", 0.001, 50000.0)
+    .thenAccept(order -> log.info("placed " + order.id))
+    .exceptionally(throwable -> {
+        Throwable cause = Helpers.unwrap(throwable);
+        return switch (cause) {
+            case InsufficientFunds    e -> { notifyUser(e); yield null; }
+            case AuthenticationError  e -> { refreshCreds(); yield null; }
+            case RateLimitExceeded    e -> { scheduleRetry(); yield null; }
+            case NetworkError         e -> { scheduleRetry(); yield null; }
+            case BaseError            e -> { log.error("ccxt", e); yield null; }
+            default -> throw new java.util.concurrent.CompletionException(cause);
+        };
+    });
+```
+
+The full hierarchy lives under `io.github.ccxt.errors` — see the [Error Handling
+section of the Manual](https://github.com/ccxt/ccxt/wiki/Manual#error-handling)
+for the complete tree (NetworkError vs ExchangeError, retry-safe vs user-error
+categories, etc.).
+
+#### WebSocket
+
+WebSocket support is available via the pro exchange classes:
+
+```Java
+import io.github.ccxt.Exchange;
+import io.github.ccxt.exchanges.pro.Binance;
+
+import java.util.concurrent.TimeUnit;
+
+Exchange exchange = new Binance();
+exchange.loadMarkets().join();
+
+// Stream live ticker updates
+for (int i = 0; i < 10; i++) {
+    Object ticker = exchange.watchTicker("BTC/USDT").get(30, TimeUnit.SECONDS);
+    System.out.println(ticker);
+}
+```
+
+You can check different examples in the `java/examples` folder.
+
 ## Rate limiting
 
 Crypto exchanges enforce rate limits to protect their infrastructure, ensure fair usage across all clients, and prevent abuse that could degrade performance or availability for other users. That means you can't make an unlimited amount of requests to the exchange, there is a rate that needs to be respected.