WebSocket API

URI: wss://acx.io:8080
Return: JSON

ACX WebSocket API Service provides a close to realtime data channel. Server push orderbook change and trading data to clients.

Usage of WebSocket API consists of three steps:

1. Establishing websocket connection
2. Authenticating by api token
3. Receiving data

Establishing websocket connection

WebSocket is a standardized protocol. There are examples in various languages. Taking Javascript as example:

var host = 'wss://acx.io:8080';
        var socket = new WebSocket(host);
        socket.onopen = function() {
          console.log('opened');
        }
        socket.onmessage = function(msg) {
          console.log(msg);
        }
        socket.onclose = function() {
          console.log('closed');
        }

Authentication

Visit API Tokens to obtain your access/secret key.

When establishing websocket connection to server, server returns a challenge message in format as below:

{"challenge":"d45sSFIZZdYzRgwi-zDqA8HFP2MfVoWqXlHX-2LbB_37q9_3pkZ8og"}

To generate the signature, concat the access key with challenge string:

payload = access_key + challenge

E.g. Assuming the access key is “abc”, challenge is “def” and payload is “abcdef”, here is how to use HMAC-SHA256 and secret key to generate payload’s signature:

signature = HMAC-SHA256('ghi', 'abcdef').to_hex = '52ca0e5beab532532c62155e78d81c7dc8ad6d6f744cf3797668cf52dd2f9a41'

Then the client just sends the signature back to server in format below:

{auth: {access_key: 'your_access_key', answer: 'the_signature'}}

Receiving Data

After authentication, the client can receive ‘realtime’ data. At the moment, ACX provides two types of data: Trade and Orderbook. Details are

Trade

Trade message means that you have order(s) being filled.

{ "trade":
              { "id":2435,
                "price":"3500.0",
                "volume":"0.0331",
                "funds":"115.85",
                "market":"btcaud",
                "created_at":"2014-06-16T05:02:37Z",
                "side":"bid",
                "bid":{
                  "id":3248, "side":"buy", "price":nil,
                  "avg_price":"3500.0", "state":"done", "market":"btcaud",
                  "created_at":"2014-06-16T05:02:37Z", "volume":"0.0331",
                  "remaining_volume":"0.0", "executed_volume":"0.0331"
                    }
                  }
              }

Notes

• price,volume: filled order price and filled volume.
• funds: filled funds (currency noted in the market pair)
• market: market pair
• side: your order within this trade (ask: sell, bid: buy).
• ask,bid: the order after trade.

Orderbook

Orderbook represents the change of orderbook

{ "orderbook": 
            { "action":"add",
              "order":{
                "id":3252,
                "timestamp":1402898864,
                "type":"ask",
                "volume":"1.0",
                "price":"3500.0",
                "market":"btcaud",
                "ord_type":"limit"}
            }
        }

Notes

• action: orderbook operation, value: add, remove, update
  • add means there is new order joining in orderbook.
  • remove means orderbook removing an order for a possible reason of cancelation/filled.
  • "update means order in orderbook has been updated.
• order: subject order in the action