The intention to is allow clients to connect to a wide range of exchanges offering trade opportunities. This is not limited to Bitcoin, although the first exchange implementation happens to use the BTC currency due to market demand.

Two approaches were considered: fully self-contained, or extensible. Existing APIs addressing similar problems (such as JDBC for relational databases) demonstrated that the extensible approach is the better choice. This implied that XChange should provide a collection of interfaces that someone will need to implement for their exchange. Clearly, XChange will initially create early versions of these providers, but eventually it is hoped that exchange owners themselves will contribute them. This is actively encouraged.

The following are the main components that developers will interact with, typically in the order presented below. These classes are all in xchange-core in the com.xeiam.xchange package.

This provides all the configuration for the Exchange including the implementor class name, authentication credentials, API secret keys and so on. Passing this to the ExchangeFactory will result in a suitable configured Exchange to work with.

Is responsible for creating Exchange implementations based on details provided in the ExchangeSpecification.

The main point of interaction. This interface provided to consuming applications, which will use this to access the various services supported by the exchange by calling one of the supporting getters. Exchanges may implement this interface by extending BaseExchange.

• BasePollingService
  • PollingMarketDataService
  • PollingTradeService
  • PollingAccountService
• StreamingExchangeService

Interfaces which are the entry point to an exchange service (e.g. listing market prices against a particular symbol etc), could be synchronous (blocking) or asynchronous (non-blocking) depending on the requirement.

Implementations of these service extend provided core base classes:

• BaseExchangeService
  • BasePollingExchangeService
  • BaseWebSocketExchangeService

A service is encouraged to have two implementations, one which provides the raw data from the exchange, and one which coerces this data into standard DTOs and implements one of the Service interfaces.

Standard DTOs for encoding a message to and from the exchange. Treated as immutable. Note that null timestamps are common and not a bug. Timestamps in DTOs represent a timestamp given from the server's JSON response, and if it's not given, the DTO contains a null timestamp.

The REST client that XChange uses is ResCU, which was originally integrated directly into XChange, but later split off into it's own separate library. One nice feature that was later integrated into ResCU is nonce handling, required by many exchanges. The nonce factory used to create a nonce value. Allows services to accept a placeholder that is replaced with generated value just before message is serialized and sent. If a method of a rest accepts ValueFactory as a parameter, it's evaluated, the message is serialized and sent in a single synchronized block.

If required by the exchange, the XChange implementation should preferably use SynchronizedValueFactory. This requires two steps:

1. In the exchange's BaseExchange implementation (see ANXExchange for example) the getNonceFactory() should be implemented and a concrete SynchronizedValueFactory<T> instance should be returned. There are many SynchronizedValueFactory<T> implementations to chose from in com.xeiam.xchange.utils.nonce.
2. In the REST interface class (see ANXV2 for example) the SynchronizedValueFactory<T> implementation should be passed as a parameter.

Each BaseExchange implementation hard-codes a SynchronizedValueFactory<T> instance. If you want to change the SynchronizedValueFactory<T> instance used, you'll need to create your own subclass of BaseExchange and provide your preferred SynchronizedValueFactory<T> instance by overriding the getNonceFactory() method to your liking, using a different nonce factory provided in com.xeiam.xchange.utils.nonce or one of your own implementations.

See here for a list of completed and planned milestones