HTTP

Browsers and other http clients can make requests to the URLs below to get a full market data book snapshot in JSON format. The server caches the response for 2 seconds, so any successive requests less than 2 seconds apart will return the same data. This is enough for GUIs and other higher-latency applications. For low-latency real-time updates you should use the TCP or the FIX API.

{
    "success":			true,
    "last updated":		"20151022-03:28:18.676",
    "time zone":		"America/New_York",
    "symbol":			"BTC-USD",
    "exchange code":		"AGGR",
    "exchange name":		"Aggregated",
    "spread":			-2.06,
    "best bid size":		0.02000000,
    "best bid price":		270.60,
    "best ask size":		0.90000000,
    "best ask price":		268.54,

    "bids": [

        [ "BASE",		0.02000000,		270.60],
        [ "BASE",		0.02000000,		270.59],
        [ "BASE",		0.02000000,		270.58],
        ...
    ],

    "asks": [

        [ "OKCN",		0.90000000,		268.54],
        [ "OKCN",		0.86100000,		268.58],
        [ "OKCN",		2.34470000,		268.60],
        ...
    ]
}

FIX

We use FIX version 4.4. The standard FIX header (i.e. BeginString, MsgType, MsgSeqNum, SenderCompID and SendingTime) must be present in every message. The SenderCompID is your username. Click here to contact us and get the host, port, username and password to connect. Messages not specified below (i.e. Heartbeat, Test Request, etc.) follow the standard FIX format.

You use the Logon message to start a FIX session with the server. The server will reply with a Logon message to indicate that the logon was successful or with a Logout message to indicate that there was a problem with the logon.
          

The Logout message can be sent by the client to gracefully disconnect or it can be sent by the server to indicate that a logon attempt was not successful. In that case you should check the Text tag for clues.
          

The MarketDataRequest message can be sent by the client to subscribe to market data. The server supports subscription to all securities or individual subscriptions. The client can also use this message to unsubscribe. If the subscription is successful, the client will receive a MarketDataSnapshotFullRefresh with the book. When unsubscribing, the client will receive a MarketDataSnapshotFullRefresh with an empty book if successful.
          

The MarketDataRequestReject message is sent back by the server when it cannot process the MarketDataRequest sent by the client. It contains the reason why the request was rejected.
          

The MarketDataSnapshotFullRefresh message is sent by the server to provide the full market data book for a security. The server sends only one MarketDataSnapshotFullRefresh per symbol, never two symbols in the same message. This message is only sent as a response for a MarketDataRequest message. When processing this message, the client should clear his book before adding the orders.
          

The MarketDataIncrementalRefresh message is sent by the server to provide incremental updates for subscribed securities. Updates for more than one symbol can come on the same message. It is also used to indicate a live trade and to signal that a book for a security should be cleared.
          

TCP

For low-latency you should use our TCP API which is shorter and faster than FIX. It uses a byte-payload protocol where the first byte contains the size of the payload that follows. All binary numbers follow the big-endian network format. If you are using Java, you can use the ByteBuffer methods getShort (2 bytes), getInt (4 bytes) and getLong (8 bytes) to read binary numbers. The “Z” message (batch end) is always sent after previous update messages to denote that a full batch update has been sent by the server. That way the client might choose to take action only after a full batch has been received instead of taking action on individual updates. (Note: For FIX you can assume that each MarketDataIncrementalRefresh message contains a batch)

The Login message must be the first message sent by the client to the server upon connection. It provides username, password and the heartbeat interval the client wants to configure. The server will reply with an 'L' message back (without any fields) to indicate that the login was successful.
          

The server can send an error message to indicate any error condition like for example if the client can't be authenticated. It contains a text message with the details about the error. The text field does not have a fixed length. Its length will be the remaining of the message.
          

The client sends a SubscribeAll message to receive updates for all books. The server will reply with another 'A' message back if the subscription was successful. The client will receive all open orders from all books immediately after subscribing to all, so it should clear its books before sending this message. (Note: The subscription confirmation ('A' back) is sent by the server only after all orders are resent to the client)
          

The client sends an UnsubscribeAll message to stop receiving updates for all books. The server will reply with another 'X' message back if the unsubscribe request was successful. The client should clear all its books after receiving the unsubscribe confirmation back from the server.
          

The client sends a Subscribe message to subscribe for updates for a single symbol. The server will reply with another 'S' message back if the subscription was successful. The client will receive all open orders for the requested symbol immediately after sending the subscription, so it should clear its book before sending this message. (Note: The subscription confirmation ('S' back) is sent by the server only after all orders for the symbol are resent to the client)
          

The client sends an Unsubscribe message to stop receiving updates for the provided symbol. The server will reply with another 'U' message back if the unsubscribe request was successful. The client should clear the book for the symbol after receiving the unsubscribe confirmation back from the server.

The client should send a heartbeat message after a period of inactivity, in other words, after a period of silence when it hasn't sent any messages to the server. The heartbeat period is configured in the Login message. If the server does not receive any message after the heartbeat interval it disconnects the client due to a read timeout. The server also sends heartbeats to the client.

The server sends a NewOrder message to indicate that a new order was added to the book.

The server sends a OwnOrder message to indicate that this order should be marked as mine.

The server sends a ModifyOrder message to indicate that an order was modified and should be updated in the client book. This message has the same format as the NewOrder message, with a different type ('M' instead of 'N').

The server sends a RemoveOrder message to indicate that an order was deleted and should be removed from the client book.

The server sends a BatchEnd message to indicate that it has sent a full batch of book changes. The client might want to take action only after a full batch has been received instead of taking action on each individual book update. A client can assume that it will always receive a 'Z' message after one or more book update messages.

The server sends a LiveTrade message to indicate that a trade in one of the exchanges has occured.

The server sends a ClearBook message to indicate that the client should clear all orders belonging to this feed ID for the given symbol.

The server sends a ClearBookByExchange message to indicate that the client should clear all orders belonging to this feed ID and exchange ID for the given symbol.

Aggregated Book

When you write and run multiple market data feeds, CoralMD automatically and transparently aggregates the quotes from all feeds inside the security market data book. See the example below:

Security sec = Security.get("BTC-USD");

NioReactor nio = NioReactor.create();

Feed coinbase = CoinbaseFeed.create(nio, 1);
Feed okcoin = OkcoinFeed.create(nio, 2);
Feed lakebtc = LakeBtcFeed.create(nio, 3);
Feed coinsetter = CoinsetterFeed.create(nio, 4);

coinbase.subscribe(sec);
okcoin.subscribe(sec);
lakebtc.subscribe(sec);
coinsetter.subscribe(sec);

coinbase.open();
okcoin.open();
lakebtc.open();
coinsetter.open();

nio.start();

Now you have access to the following market data books:

Security sec = Security.get("BTC-USD");

Book aggregated = Book.get(sec); // aggregated book with quotes from all feeds

Book coinbase = Book.get(sec, CoinbaseFeed.EXCHANGE_ID); // book with quotes coming only from Coinbase exchange

Book okcoin = Book.get(sec, OkcoinFeed.EXCHANGE_ID); // book with quotes coming only from Okcoin exchange

You can also display the market data book using the com.coralblocks.coralmd.BookViewer class, as the example below shows:

Security sec = Security.get("BTC-USD");
Book aggregated = Book.get(sec);

BookViewer bookViewer = new BookViewer(nio, aggregated);
bookViewer.start();

In your terminal you see:

Market Data over HTTP

CoralMD comes with a MarketDataHttpServer that you can use to serve your market data to http clients. Below how you launch the server:

MapConfiguration config = new MapConfiguration();
config.add("priceDecimals", 2);

Server httpServer = new MarketDataHttpServer(nio, 45453, config);
httpServer.open();

Market Data over TCP

For a fast, clean, efficient and simple binary protocol, you can use MarketDataTcpServer. Click here to check the message specification and to learn how to write your own TCP client that can get access to live Bitcoin market data from our servers. Below how you would launch a TCP server with CoralMD:

Server tcpServer = new MarketDataTcpServer(nio, 45454);
tcpServer.open();

Market Data over FIX

To use the standard FIX protocol, you can launch CoralMD’s MarketDataFixServer. Click here to check the FIX message specification and to learn how to write your own FIX client that can get access to live Bitcoin market data from our FIX servers. Below how you would launch the FIX server with CoralMD:

Server fixServer = new MarketDataFixServer(nio, 45455);
fixServer.open();

Conclusion

CoralMD makes it very easy to aggregate market data from multiple sources (i.e. feeds) and to serve them internally or externally through simple and efficient HTTP, TCP and FIX APIs.

Test Details

A pseudo market data generator sends UDP packets containing market data updates (i.e. ticks). Our test trading strategy receives these packets, parses them and places a trade order using the FIX protocol on a pseudo exchange that immediately executes the order. To warm up the test strategy, we initially send 1 million market data updates. Then we proceed to send one packet every 5 seconds. To measure the latency, we use tcpdump to record the UDP packet coming in and the FIX order going out. With the packet capture file from tcpdump we then use wireshark to calculate the difference in the timestamps of the packet arriving and the FIX order leaving.

Results

As you can see from the wireshark screenshot below, the tick-to-trade latencies are around 10-11 microseconds. If you compare these numbers with the results from the same tick-to-trade test using CoralFIX and CoralReactor, you will see that CoralMD and CoralGateway add around 1-3 microseconds on top of CoralReactor and CoralFIX.

Source Code

Market data is received through a feed implemented using CoralMD. The trade order is placed through a gateway implemented using CoralGateway. As you can see from the source code below, our test strategy receives a book update from the market data feed and proceeds to place an order using the gateway. Also note that the source code down below produces zero garbage for the GC.

package com.coralblocks.coralgateway.bench;

import com.coralblocks.coralgateway.FixGateway;
import com.coralblocks.coralgateway.FixGateway.FixOrder;
import com.coralblocks.coralgateway.Order.Side;
import com.coralblocks.coralgateway.Order.TimeToLive;
import com.coralblocks.coralgateway.Order.Type;
import com.coralblocks.coralgateway.sample.TestFixGateway;
import com.coralblocks.coralmd.Book;
import com.coralblocks.coralmd.Book.State;
import com.coralblocks.coralmd.BookListener;
import com.coralblocks.coralmd.Security;
import com.coralblocks.coralmd.feed.Feed;
import com.coralblocks.coralmd.sample.SimpleFeed;
import com.coralblocks.coralreactor.nio.NioReactor;
import com.coralblocks.coralreactor.util.MapConfiguration;

public class BenchStrategy implements BookListener {
	
	private final FixGateway<FixOrder> gateway;
	private final Feed feed;
	private boolean isStarted = false;
	
	public BenchStrategy(FixGateway<FixOrder> gateway, Feed feed) {
		this.gateway = gateway;
		this.feed = feed;
		Book.addGlobalBookListener(this);
	}
	
	public void open() {
		gateway.open();
		feed.open();
	}
	
	public void close() {
		gateway.close();
		feed.close();
	}
	
	public void setStarted(boolean flag) {
		this.isStarted = flag;
	}

	///// BookListener ////
	
	@Override
    public void onBookUpdated(Book book) {
	    
		if (!isStarted) return;
		
		Security sec = book.getSecurity();
		long size = book.getBestAskSize();
		long price = book.getBestAskPrice();
		
		gateway.send(TimeToLive.IOC, Side.BUY, Type.LIMIT, sec.getSymbolString(), size, price);
    }

	@Override
    public void onTopOfBookChanged(Book book, 
               int oldNumberOfBidQuotes, long oldBidSize, long oldBidPrice, 
               int oldNumberOfAskQuotes, long oldAskSize, long oldAskPrice) {
	    
    }

	@Override
    public void onStateChanged(Book book, State oldState) {
	    
    }
	
	public static void main(String[] args) {
		
		NioReactor nio = NioReactor.create();
		
		MapConfiguration gwConfig = new MapConfiguration();
		gwConfig.add("fixVersion", 44);
		gwConfig.add("senderComp", "TEST1");
		gwConfig.add("forceSeqReset", true);
		
		FixGateway<FixOrder> gateway = new TestFixGateway(nio, args.length > 0 ? args[0] : "localhost", 55559, gwConfig);
		
		MapConfiguration feedConfig = new MapConfiguration();
		feedConfig.add("host", "0.0.0.0");
		feedConfig.add("port", 55558);
		
		Feed feed = new SimpleFeed(nio, feedConfig);
		
		BenchStrategy strategy = new BenchStrategy(gateway, feed);
		strategy.open();
		strategy.setStarted(true);
		
		nio.start();
	}
}