XChange
XChange is a Java library providing a simple and consistent API for interacting with 60+ Bitcoin and other cryptocurrency exchanges, providing a consistent interface for trading and accessing market data.
A big thanks to all the contributors who have helped make XChange what it is today! ❤️
Important!
The world of Bitcoin changes quickly and XChange is no exception. For the latest bugfixes and features you should use the snapshot jars or build yourself from the develop branch. See below for more details about building with Maven. To report bugs and see what issues people are currently working on see the issues page.
Description
XChange is a Java based library providing a simple and consistent API for interacting with a diverse set of cryptocurrency exchanges.
Basic usage is very simple: Create an Exchange instance, get the appropriate service, and request data. More complex usages are progressively detailed below.
Integration status
| Exchange | Status |
|---|
| bitfinex | |
| bitget | |
| deribit | |
| gate.io | |
| kraken | |
| stream-bitfinex | |
| stream-deribit | |
| stream-kraken-v2 | |
REST API
Public Market Data
To use public APIs which do not require authentication:
Exchange bitstamp = ExchangeFactory.INSTANCE.createExchange(BitstampExchange.class);
MarketDataService marketDataService = bitstamp.getMarketDataService();
Ticker ticker = marketDataService.getTicker(CurrencyPair.BTC_USD);
System.out.println(ticker.toString());
Private Account Info
To use APIs which require authentication, create an ExchangeSpecification with your API credentials and pass this to createExchange():
ExchangeSpecification exSpec = new BitstampExchange().getDefaultExchangeSpecification();
exSpec.setUserName("34387");
exSpec.setApiKey("a4SDmpl9s6xWJS5fkKRT6yn41vXuY0AM");
exSpec.setSecretKey("sisJixU6Xd0d1yr6w02EHCb9UwYzTNuj");
Exchange bitstamp = ExchangeFactory.INSTANCE.createExchange(exSpec);
Please Note: while most exchanges use just an API key and secret key, others (such as username on Bitstamp or passphrase on Coinbase Pro) are exchange-specific. For more examples of adding the keys to the ExchangeSpecification, including storing them in a configuration file, see Frequently Asked Questions.
Once you have an authenticated Exchange, the private API services, AccountService and TradeService, can be used to access private data:
// Get the account information
AccountService accountService = bitstamp.getAccountService();
AccountInfo accountInfo = accountService.getAccountInfo();
System.out.println(accountInfo.toString());
All exchange implementations expose the same API, but you can also directly access the underlying "raw" data from the individual exchanges if you need to.
Websocket API
The above API is usually fully supported on all exchanges and is best used for occasional requests and polling on relatively long intervals. Many exchanges, however, heavily limit the frequency that these requests can be made, and advise instead that you use their websocket API if you need streaming or real-time data.
For a smaller number of exchanges, the websocket-based StreamingExchange API is also available. This uses Reactive streams to allow you to efficiently subscribe to changes relating to thousands of coin pairs without requiring large numbers of threads.
You will need to import an additional dependency for the exchange you are using (see below), then example usage is as follows:
// Use StreamingExchangeFactory instead of ExchangeFactory
StreamingExchange exchange = StreamingExchangeFactory.INSTANCE.createExchange(BitstampStreamingExchange.class);
// Connect to the Exchange WebSocket API. Here we use a blocking wait.
exchange.connect().blockingAwait();
// Subscribe to live trades update.
Disposable subscription1 = exchange.getStreamingMarketDataService()
.getTrades(CurrencyPair.BTC_USD)
.subscribe(
trade -> LOG.info("Trade: {}", trade),
throwable -> LOG.error("Error in trade subscription", throwable));
// Subscribe order book data with the reference to the subscription.
Disposable subscription2 = exchange.getStreamingMarketDataService()
.getOrderBook(CurrencyPair.BTC_USD)
.subscribe(orderBook -> LOG.info("Order book: {}", orderBook));
// Wait for a while to see some results arrive
Thread.sleep(20000);
// Unsubscribe
subscription1.dispose();
subscription2.dispose();
// Disconnect from exchange (blocking again)
exchange.disconnect().blockingAwait();
Authentication, if supported for the exchange, works the same way as for the main API, via an ExchangeSpecification. For more information on what is supported, see the Wiki.
More information
Now go ahead and study some more examples, download the thing and provide feedback.
More information about reactive streams can be found at the RxJava wiki.
Features
More Info
Project Site: http://knowm.org/open-source/xchange
Example Code: http://knowm.org/open-source/xchange/xchange-example-code
Change Log: http://knowm.org/open-source/xchange/xchange-change-log/
Java Docs: http://knowm.org/javadocs/xchange/index.html
Talk to us on discord:
Wiki
Continuous Integration
Getting Started
Non-Maven
Maven
The XChange release artifacts are hosted on Maven Central: org.knowm.xchange
Add the following dependencies in your pom.xml file. You will need at least xchange-core. Add the additional dependencies for the exchange modules you are interested in (XYZ shown only for a placeholder). There is example code for all the modules in xchange-examples.
<dependency>
<groupId>org.knowm.xchange</groupId>
<artifactId>xchange-core</artifactId>
<version>6.0.0</version>
</dependency>
<dependency>
<groupId>org.knowm.xchange</groupId>
<artifactId>xchange-XYZ</artifactId>
<version>6.0.0</version>
</dependency>
If it is available for your exchange, you may also want to use the streaming API:
<dependency>
<groupId>org.knowm.xchange</groupId>
<artifactId>xchange-stream-XYZ</artifactId>
<version>6.0.0</version>
</dependency>
For snapshots, add the following repository to your pom.xml file.
<repository>
<name>Central Portal Snapshots</name>
<id>central-portal-snapshots</id>
<url>https://central.sonatype.com/repository/maven-snapshots/</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
The current snapshot version is:
6.0.1-SNAPSHOT
Building with Maven
| Instruction | Command |
|---|
| run unit tests | mvn clean test |
| run unit and integration tests | mvn clean verify -DskipIntegrationTests=false |
| install in local Maven repo | mvn clean install |
| create project javadocs | mvn javadoc:aggregate |
| generate dependency tree | mvn dependency:tree |
| check for dependency updates | mvn versions:display-dependency-updates |
| check for plugin updates | mvn versions:display-plugin-updates |
| code format | mvn com.spotify.fmt:fmt-maven-plugin:format |
| pom format/organize | mvn com.github.ekryd.sortpom:sortpom-maven-plugin:sort |
Bugs
Please report any bugs or submit feature requests to XChange's Github issue tracker.
Contributing
If you'd like to submit a new implementation for another exchange, please take a look at New Implementation Best Practices first, as there are lots of time-saving tips!
For more information such as a contributor list and a list of known projects depending on XChange, visit the Main Project Wiki.
Maintained by Knowm Inc.
XChange is an open-source project sponsored and maintained by the team at Knowm Inc., a company dedicated to neuromorphic computing and machine learning research since 2015.
Our team also powers AI Receptionist, an AI-driven automated phone system for small businesses. We leverage the same high-performance, resilient technical architecture and design principles used in XChange to ensure AI Receptionist never misses a call.
Learn more about our research at Knowm.org.
Connect with the Lead Developer:
Tim Molter on LinkedIn | Tim Molter on X (Twitter)
