Skip to content

Websocket API Documentation

Please read the Introduction first.

Websocket API Endpoint

The websocket API endpoint is wss://api.dex.blue/ws

General Protocol Structure

Each websocket frame consists of an JSON-encoded array and can contain multiple packets, which have to be applied in order.

Most Client Input will result in a direct event (Server Packet) and in some cases follow-up events.

Clients can subscribe to market data streams to receive real-time updates. Authenticated connections will automatically subscribe to user updates.

Token Amount Representations

Every amount is represented as an integer in smallest denomination of the token. In the case of ETH this is wei (1 ETH is 1,000,000,000,000,000,000 wei). Most Tokens use 18 decimals, but some use e.g. 8. This means you always have to calculate with the number of decimals specified in the tokens smart contract or the one obtained by getListed (listed event).

To prevent rounding errors, all amounts have to be submitted as a string.

Server Timezone

All timestamps sent by the server are in UTC time, all time input also has to be converted to UTC. Timestamps are transmitted as a unixtime decimal in seconds (or milliseconds, if specifically stated).

Client Inputs

Structure

Client input is sent in a JSON-encoded array of input objects. Each of these objects has to contain a c (command) parameter which specifies the function to invoke.

Next to the command and the parameters, an input object can contain an optional rid (request id) parameter. This will flag server packets which directly resulted from this request (can be used for callbacks).

Example Input Frame:

1
2
3
4
5
6
7
8
[
    {
        "c"   : COMMAND,   // (string)
        "rid" : REQUEST_ID // (uint) (optional) request id
        // (optional) other command-releated parameters
    },
    ... // up to 5 commands per frame
]

If your request should fail you will get an error event back flagged with your rid.

API Limits

  • Maximum connections per IP: 25. If this limit is reached you will receive an error when establishing a connection.
  • Maximum websocket frame length: 5000 characters. If this limit is reached your connection will be immediately closed.
  • Maximum client inputs in one websocket frame: 5. If this limit is reached you will receive error events containing no request id.

Call Limits

Within every 10 second timeframe, each client has a score of 25 points he can use for requests. Different requests cost different amount of points. For example, an order placement costs 1.5 points while subscribing to a market data feed costs only 0.75 Points. The cost of each request is stated in the list below.

If the limit of 25 points is exceeded, you will receive an error event containing the request id.

If your trading activities require higher limits, please do not hesitate to contact us.

Method Cost
announceDelegate 0.5
announceDeposit 0.5
authenticate 1
authenticateDelegate 1
authenticateWithSession 1
cancelOrder 0.5
editOrder 0.5
getAcceptedFee 1
getActiveOrderSnapshot 1
getBarData 0.5
getHistoricalLedgerEntries 0.5
getHistoricalOrders 0.5
getListed 1
getTOTPSalt 0.5
getTokenInfo 0.5
getUserTrades 0.5
getUsername 0.5
logoff 1
ping 0
placeOrder 0.5
registerTOTPSalt 0.5
signDelegationRemoval 0.5
signWithdrawal 0.5
subscribe 0.75
unSubscribe 0.75
updateDelegateLabel 0.5
updateUsername 0.5
withdrawalTransaction 0.5

Client Commands

authenticate

To authenticate your connection you have to sign a message with your private key. This message string can be chosen by you, but it has to end with your nonce. For example "AUTHENTICATE 100" (assuming your nonce is 100).

1
2
3
4
5
6
[{
    "c"         : "authenticate",
    "message"   : SIGNED_MESSAGE,   // (string) including NONCE at the end
    "nonce"     : YOUR_NONCE,       // (uint)
    "signature" : SIGNATURE         // (hexString)
}]

Expected Server Packets: auth, balanceSnapshot, pendingLedgerEntrySnapshot, feeTier

authenticateDelegate

authenticateDelegate works the same way as authenticate. It takes in a signature from a delegate and authenticates the delegating address. A connection authenticated through a delegates will not be able to call signWithdrawal, signDelegationRemoval, updateDelegateLabel, updateUsername and registerTOTPSalt. Delegate authentications will not receive a session id.

authenticateWithSession

You can use the session id obtained via authenticate to authenticate your session without signing a message (this method is used by our web interface to authenticate after page reload).

A session can only be used to authenticate once, that authentication, however, will give you a new session for next time.

There is only one parallel session per account.

1
2
3
4
5
[{
    "c"       : "authenticateWithSession",
    "address" : ETHEREUM_ADDRESS,   // (hexString) (which initiated the session)
    "session" : YOUR_SESSION_ID     // (string)
}]

Expected Server Packets: auth, balanceSnapshot, pendingLedgerEntrySnapshot, feeTier

logoff

End a connection-user binding and clear the session.

1
2
3
[{
    "c" : "logoff"
}]

Expected Server Packets: auth

getListed

Request the listed tokens and markets.

1
2
3
[{
    "c" : "getListed"
}]

Expected Server Packets: listed

getFeeTier

Request an update on your 30d trailing volume and fee tier. Please note that you will automatically receive a snapshot on auth and updates when your fee tier changes, so in most cases, you do not need to call this regularly.

1
2
3
[{
    "c" : "getFeeTier"
}]

Expected Server Packets: feeTier

getActiveOrderSnapshot

Request a snapshot of your active orders.

1
2
3
[{
    "c" : "getActiveOrderSnapshot"
}]

Expected Server Packets: activeOrderSnapshot

getHistoricalOrders

Request a set of your historical orders.

1
2
3
4
5
6
7
8
[{
    "c"      : "getHistoricalOrders",
    "market" : MARKET,                  // (string) (optional) market from which to query orders
    "from"   : QUERY_FROM_TIMESTAMP,    // (uint)   (optional) unix timestamp from which to query orders
    "to"     : QUERY_TO_TIMESTAMP,      // (uint)   (optional) unix timestamp up to which to query orders
    "before" : LAST_KNOWN_ID,           // (uint)   (optional) query orders before the last known one (if you want to cover a whole timeframe but your history is longer than the limit)
    "limit"  : ROW_LIMIT                // (uint)   (optional) limit the results (max 50, standard 20)
}]

Expected Server Packets: historicalOrders

getUserTrades

Request trades from your personal trade history.

1
2
3
4
5
6
7
8
[{
    "c"      : "getUserTrades",
    "market" : MARKET,                  // (string) (optional) market from which to query trades
    "from"   : QUERY_FROM_TIMESTAMP,    // (uint)   (optional) unix timestamp from which to query trades
    "to"     : QUERY_TO_TIMESTAMP,      // (uint)   (optional) unix timestamp up to which to query trades
    "before" : LAST_KNOWN_ID,           // (uint)   (optional) query trades before the last known one (if you want to cover a whole timeframe but your history is longer than the limit)
    "limit"  : ROW_LIMIT                // (uint)   (optional) limit the results (max 50, standard 20)
}]

Expected Server Packets: userTrades

subscribe

Subscribe to market events.

List Of Events You Can Subscribe To

Market Events

Events you can subscribe to in each market.

  • trades : subscribe to all trades in a market, will answer with a tradeSnapshot event followed by trade events

  • ticker : subscribe to all ticker updates from a market, will answer with the last ticker)

  • book20d5 - book20d1 : subscribe to the order book of a given market with a length of 20 entries for each side and a digit precision of 5-1.

  • book100d5 - book100d1 : subscribe to the order book of a given market with a length of 20 entries for each side and a digit precision of 5-1.

  • bookd5-bookd1 : subscribe to the full order book of a given market with a digit precision of 5-1. Order book subscriptions will answer with a orderBookSnapshot event, followed by orderBook events.

Other Events
  • rate : subscribe to a ETH to fiat conversion rate e.g. ETHUSD, available are ETH traded against the config.conversion_currencies. They represent the global average and are used for internal calculations by the market platform. Subscribe to these by setting the pair name as the market and rate as the event.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[{
    "c"         : "subscribe",
    "markets"   : [     // market ids you want to subscribe to the specified events in
        MARKET,         // (string)
        ...
    ],
    "events" : [        // events you want to subscribe to in the given markets
        EVENT,          // (string)
        ...
    ],
}]

unSubscribe

Unsubscribe from market events. Remove subscriptions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[{
    "c"         : "unSubscribe",
    "markets"   : [     // market ids you want to unSubscribe to the specified events in
        MARKET,         // (string)
        ...
    ],
    "events"    : [     // events you want to unSubscribe to in the given markets
        EVENT,          // (string)
        ...
    ],
}]

placeOrder

Place a new order from the account authenticated in the connection. Signature and order types are specified below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
[{
    "c"               : "placeOrder",
    "market"          : MARKET,            // (string)
    "type"            : TYPE,              // (string)      order type: limit, limit-fok, fiat-limit
    "buy"             : BUY_TOKEN,         // (hexString)   buy token contract address
    "sell"            : SELL_TOKEN,        // (hexString)   sell token contract address
    "buyAmount"       : BUY_AMOUNT,        // (uintString)  total amount to buy
    "sellAmount"      : SELL_AMOUNT        // (uintString)  total amount to sell
    "nonce"           : NONCE,             // (uint)
    "signature"       : SIGNATURE,         // (string)
    "signatureFormat" : FORMAT,            // (string)      sign or signTypedData

    // optional parameters:
    "cid"             : CLIENT_IDENTIFIER, // (uint)        (optional) a client-submitted identifier for the order
    "hidden"          : HIDDEN,            // (bool)        (optional)
    "peggedTo"        : PEGGED_TO,         // (string)      (optional) mandatory for fiat-limit orders, value from config.conversion_currencies.
    "peggedRate"      : PEGGED_RATE,       // (floatString) (optional) mandatory for fiat-limit orders
    "buyBookAmount"   : BUY_BOOK_AMOUNT,   // (uintString)  (optional) insert the order with a different book amount
    "sellBookAmount"  : SELL_BOOK_AMOUNT   // (uintString)  (optional) insert the order with a different book amount
}]

Expected Server Packets: orderStatus, balanceStatus (userTrade & ledgerEntryStatus, when the order gets executed)

Signature Formats

All submited orders have to be signed with your private key. The dex.blue smart contract accepts two signature formats: sign and signTypedData (EIP712).

sign

This signature format is the common standart. It is suited to be used in algorithmic trading or where there is no graphical user interface. The web3 1.0 method used for this signature format is web3.eth.personal.sign(), which prepends \x19Ethereum Signed Message:\n+MESSAGE_LENGTH to the message (the order hash) before signing it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
var orderHash = web3.utils.soliditySha3(
    {type : 'address', value : BUY_TOKEN_CONTRACT_LOWERCASE},
    {type : 'address', value : SELL_TOKEN_CONTRACT_LOWERCASE},
    {type : 'uint256', value : BUY_TOKEN_AMOUNT},
    {type : 'uint256', value : SELL_TOKEN_AMOUNT},
    {type : 'uint64',  value : NONCE},  
    {type : 'address', value : EXCHANGE_CONTRACT_ADDRESS} // config.contractAddress
)
web3.eth.personal.sign(orderHash, YOUR_ETHEREUM_ADDRESS, function(error, signature){
    if(!error){
        //signature
    }
})
signTypedData

This scheme follows signature method (EIP 712). It is suited for graphical user interfaces as it presents the data to sign to the signee. Using web3 1.0 it can be implemented with:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
var EIP712Domain = {
        name              : "dex.blue",
        version           : "1",
        chainId           : 1,                        // 1 is mainnet, 4 for rinkeby
        verifyingContract : EXCHANGE_CONTRACT_ADDRESS // config.contractAddress
    },
    Domain = [
        { name: "name",              type: "string" },
        { name: "version",           type: "string" },
        { name: "chainId",           type: "uint256" },
        { name: "verifyingContract", type: "address" }
    ],
    Order = [
        {name : "buyTokenAddress",   type : "address"},
        {name : "sellTokenAddress",  type : "address"},
        {name : "buyTokenAmount",    type : "uint256"},
        {name : "sellTokenAmount",   type : "uint256"},
        {name : "nonce",             type : "uint64"}
    ],
    signData = JSON.stringify({
        types: {
            Order        : Order,
            EIP712Domain : Domain
        },
        domain      : EIP712Domain,
        primaryType : "Order",
        message     : {
            "buyTokenAddress"  : BUY_TOKEN_CONTRACT_LOWERCASE,
            "sellTokenAddress" : SELL_TOKEN_CONTRACT_LOWERCASE,
            "buyTokenAmount"   : BUY_TOKEN_AMOUNT,
            "sellTokenAmount"  : SELL_TOKEN_AMOUNT,
            "nonce"            : NONCE
        }
    });

web3.currentProvider.sendAsync(
    {
        method: "eth_signTypedData_v3",
        params: [YOUR_ETHEREUM_ADDRESS, signData],
        from: YOUR_ETHEREUM_ADDRESS
    },
    function(err, signature) {
        if(!err && !signature.error){
            // signature.result
        }
    }
);

Order Types

limit

Standart limit orders.

limit-fok

Limit-Fill-Or-Kill orders are limit orders which are either fully executed when placed or canceled. You can use this to mimic market order behaviour by submiting a limit-fok order with the maximum slippage you would accept.

fiat-limit

You can peg your orders rate to a Fiat amount equivalent by setting pegged_to to one of the currencies from config.conversion_currencies (e.g. USD) and pegged_rate to the rate you want to peg your order to (e.g. 10).

editOrder

Edit one of your active orders.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[{
    "c"              : "editOrder",
    "id"             : ID,              // (uint)        (optional)
    "cid"            : CID,             // (uint)        (optional)
    "hidden"         : HIDDEN,          // (bool)        (optional)
    "peggedTo"       : PEGGED_TO,       // (string)      (optional) from config.conversion_currencies
    "peggedRate"     : PEGGED_RATE,     // (floatString) (optional) required if pegged_to is set
    "buyBookAmount"  : BUY_BOOK_AMOUNT, // (uintString)  (optional) change the orders book amount
    "sellBookAmount" : SELL_BOOK_AMOUNT // (uintString)  (optional) change the orders book amount
}]

Expected Server Packets: orderStatus, balanceStatus

cancelOrder

Cancel one of your active orders.

1
2
3
4
5
[{
    "c"   : "cancelOrder",
    "id"  : ID            // (uint) (optional) id of the order to cancel
    "cid" : CID           // (uint) (optional) cid of the order to cancel
}]

Expected Server Packets: orderStatus, balanceStatus

cancelOrders

Cancel all your order in a specific market or all markets.

1
2
3
4
[{
    "c"      : "cancelOrders",
    "market" : MARKET,    // (string) (optional) only cancel orders from a specified market.
}]

Expected Server Packets: orderStatus, balanceStatus

getBarData

Request bar (charting candle) data from the server.

1
2
3
4
5
6
7
[{
    "c"         : "getBarData",
    "from"      : FROM,         // (uint)
    "to"        : TO,           // (uint)
    "market"    : MARKET,       // (string)
    "precision" : PRECISION,    // (string) from config.barDataPrecisions
}]

Expected Server Packets: barData

signWithdrawal

Request a multi-sig to instantly withdraw from your available balance.

1
2
3
4
5
[{
    "c"      : "signWithdrawal",
    "token"  : TOKEN,           // (hexString)  contract address of the token to withdraw
    "amount" : AMOUNT           // (uintString) amount to withdraw
}]

Expected Server Packets: signedWithdrawal, ledgerEntryStatus

announceDelegate

There is no need to call this function, it just displays the pending delegate in interfaces.

With this method, you can tell the platform that you initiated a delegation transaction on the blockchain, this will create a temporary delegate object on the market platfrom which has no rights to authenticate or sign orders.

1
2
3
4
5
6
[{
    "c"              : "announceDelegate",
    "address"        : DELEGATE, // (hexString) the address you are about to delegate
    "label"          : LABEL,    // (string)    label the delegate (max 30 characters)
    "isTradingLogin" : BOOL      // (bool)      mark the delegate as trading login
}]

Expected Server Packets: delegateStatus

updateDelegateLabel

Update the Label of a Delegated Signing Key.

1
2
3
4
5
[{
    "c"              : "updateDelegateLabel",
    "address"        : DELEGATE, // (hexString) the address of the delegate you want to re-label
    "label"          : LABEL     // (string)    the new label for the delegate (max 30 characters)
}]

Expected Server Packets: delegateStatus

signDelegationRemoval

Request a multi-sig to dedelegate a delegated signing address. When calling this, all this delegates orders will be canceled and this delegate will not be able to authenticate or place further orders.

1
2
3
4
[{
    "c"       : "signDelegationRemoval",
    "address" : DELEGATE // (hexString) the address of the delegate you want to remove the delegation of
}]

Expected Server Packets: delegateStatus, which contains the signature.

withdrawalTransaction

You will only want to use this method if you are building a frontend application displaying the ledgerEntries to the user.

With this method, you can tell the platform the txhash of a withdrawal you initiated via multisig. The txhash will be temporarily added to the ledgerEntry, nothing else. When another tx with this multisig will be mined the txhash will be replaced.

1
2
3
4
5
[{
    "c"         : "withdrawalTransaction",
    "id"        : ID,      // (uint)       id of the withdrawals ledgerEntry
    "txhash"    : TXHASH   // (hexString)  transaction hash of your withdrawal transaction
}]

Expected Server Packets: ledgerEntryStatus

announceDeposit

You will only want to use this method if you are building a frontend application displaying the ledgerEntries to the user.

With this method, you can tell the platform that you initiated a deposit to the market platform. This will create a temporary pending ledger entry with the given txhash and amount.

1
2
3
4
5
6
[{
    "c"         : "announceDeposit",
    "token"     : TOKEN,    // (hexString)  contract address of the token you deposited
    "amount"    : AMOUNT,   // (uintString) amount of the token you deposited
    "txhash"    : TXHASH,   // (hexString)  transaction hash of your deposit transaction
}]

Expected Server Packets: ledgerEntryStatus

getHistoricalLedgerEntries

1
2
3
4
5
6
7
[{
    "c"      : "getHistoricalLedgerEntries",
    "from"   : QUERY_FROM_TIMESTAMP,    // (uint) (optional) unix timestamp from which to query ledger entries
    "to"     : QUERY_TO_TIMESTAMP,      // (uint) (optional) unix timestamp up to which to query ledger entries
    "before" : LAST_KNOWN_ID,           // (uint) (optional) query entries before the last known one (if you want to cover a whole timeframe but your history is longer than the limit)
    "limit"  : ROW_LIMIT                // (uint) (optional) limit the results (max 50, standard 20)
}]

Expected Server Packets: historicalLedgerEntries

getHistoricalTrades

1
2
3
4
5
6
7
8
[{
    "c"      : "getHistoricalTrades",
    "market" : MARKET,                  // (string) (optional) market from which to query trades
    "from"   : QUERY_FROM_TIMESTAMP,    // (uint)   (optional) unix timestamp from which to query trades
    "to"     : QUERY_TO_TIMESTAMP,      // (uint)   (optional) unix timestamp up to which to query trades
    "before" : LAST_KNOWN_ID,           // (uint)   (optional) query trades before the last known one (if you want to cover a whole timeframe but your history is longer than the limit)
    "limit"  : ROW_LIMIT                // (uint)   (optional) limit the results (max 50, standard 20)
}]

Expected Server Packets: historicalTrades

Server Packets

Structure

Websocket frames sent from the server consist of an outer array containing a single or multiple packets which should be applied in order. These packets are arrays containing the message and packet metadata in the following format:

Example Server Frame:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[           // array of packets
    [       // packet array
        CHANNEL,     // (string) market id or a 0 for general and personal packets
        EVENT_ID,    // (string) e.g. 'ob' for order book updates
        MESSAGE,     // (array / object, depensing on event)
                        // contains the message bodies specified below
        RID          // (uint)   (optional) client request id if a rid was sent with the request
    ]
    // (optional) more packets
]

General Stream Event Packets

config

Event ID: 'c'

You will receive this packet once you establish a websocket connection. It contains useful information, such as the smart contract address and available conversion currencies.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    contractAddress : SMART_CONTRACT_ADDRESS, // (hexString) etheruem address from the dex.blue smart contract address
    network         : NETWORK_NAME,           // (string)    e.g. 'main' or 'rinkeby'
    conversionCurrencies: {  // The currencies available for conversions
        "ETH" : "Ξ",
        "BTC" : "₿",
        "USD" : "$",
        "EUR" : "€"
        ...
    },
    barDataPrecisions: {     // precisions name and interval amount in seconds
        "1m"  :   60,
        "5m"  :  300,
        "15m" :  900,
        "30m" : 1800
        ...
    }
}

listed

Event ID: 'l'

The listed tokens and market pairs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    tokens : {
        TOKEN_SYMBOL : {                        // (string) the tokens symbol on the platform e.g. ETH
            contract : TOKEN_CONTRACT_ADDRESS,  // (hexString) e.g. "0x0000000000000000000000000000000000000000"
            name     : TOKEN_NAME,              // (string)    e.g. "Ethereum"
            decimals : TOKEN_DECIMALS           // (uint)      e.g. 18 (ETH has 18 decimal places behind the comma)
        },
        ... // more tokens
    },
    markets : {
        MARKET_SYMBOL : {           // (string) the markets symbol on the platform e.g. ETHDAI
            traded : TRADED_TOKEN,  // (string) the symbol of the traded token (the traded token in ETHUSD would be ETH)
            quote  : QUOTING_TOKEN  // (string) the symbol of the quote token (the quote token in ETHUSD would be USD)
        },
        ... // more markets
    }
}

message

Event ID: 'm'

When your client has a UI, these messages can be informative for the user.

1
MESSAGE // (string) message string

error

Event ID: 'e'

Error events are sent when an input resulted in an error. The rid indicated which request was malformed.

1
ERROR   // (string) the error your input resulted in

pingPong

Event ID: 'p'

This can be used to test wether your connection is still active, request a "pong" by sending a [{"c":"ping"}] packet to the server.

1
"pong"  // (string) a string containing "pong"

reconnect

Event ID: 'rc'

In the case of infrastructure or software upgrades, the server can send a reconnect command to the client. This will be sent on channel 0.

1
2
3
4
[
    SECONDS_TILL_RECONNECT, // (uint)              The packets just contains the numbers of seconds after which to reconnect (can be 0, if internal routing is changed).
    MESSAGE                 // (string) (optional) The message to display to the user. This field may not always be set.
]

Market Data Events

Market data events are sent in the markets channel (markets id is the channels id).

orderBookSnapshot

Event ID: 'obs'

Is an array of orderBook objects

orderBookUpdate

orderBookUpdate updates are sent when a line in a subscribed order book changes. When the amount and order count are 0, the line is removed.

Event ID: 'ob'

1
2
3
4
5
6
[
    DIRECTION,  // 1 for bids, 0 for asks
    RATE,       // (floatString) the rate, the amount is offered at
    AMOUNT,     // (uintString)  the amount offered to buy or sell
    ORDER_COUNT // (uint)        the total amount of orders at this rate
]

tradeSnapshot

Event ID: 'ts'

Is an array of trade objects

trade

trade updates are sent when a new trade was initiated in a market you subscribed to.

Event ID: 't'

1
2
3
4
5
6
7
[   //market trade object
    ID,
    DIRECTION,   // 1 if it was a buy trade, 0 if it was a sell trade
    RATE,        // (floatString) the rate the trade was executed at
    AMOUNT,      // (uintString)  the amount of the markets traded token which was traded
    TIMESTAMP    // (uint)        the trades timestamp (in ms)
]

historicalTrades

Sends historical orders queried by getHistoricalTrades.

Event ID: 'ht'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    trades : [
        [   //historicalTrade object
            ID,
            MARKET,      // (string)
            DIRECTION,   // 1 if it was a buy trade, 0 if it was a sell trade
            RATE,        // (floatString) the rate the trade was executed at
            AMOUNT,      // (uintString)  the amount of the markets traded token which was traded
            TIMESTAMP    // (uint)        the trades timestamp (in ms)
        ],
        ...
    ]
    from   : FROM_PARAMETER,   // (uint) (optional) input parameter if it was set
    to     : TO_PARAMETER,     // (uint) (optional) input parameter if it was set
    before : BEFORE_PARAMETER, // (uint) (optional) input parameter if it was set
    limit  : LIMIT_PARAMETER   // (uint) (optional) input parameter if it was set
}

ticker

trade updates are sent when the ticket of a market you subscribed to changed.

Event ID: 'ti'

1
2
3
4
5
6
7
8
[
    RATE,              // (floatString) the last traded rate
    CHANGE_24H,        // (floatString) percentage change to the ticker rate 24h ago
    VOLUME_TRADED_24H, // (floatString) 24h volume in the traded token
    VOLUME_QUOTE_24H,  // (floatString) 24h volume in the pricing token
    HIGH_24H,          // (floatString) highest ticker rate in the last 24h
    LOW_24H            // (floatString) lowest ticker rate in the last 24h
]

barData

barData is send when requested through getBarData

Event ID: 'bd'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    bars : [       // array of bar objects
        [   // bar object
            TIMESTAMP,  // (float) bars open timestamp in ms
            OPEN_RATE,  // (float)
            HIGH_RATE,  // (float)
            LOW_RATE,   // (float)
            CLOSE_RATE, // (float)
            VOLUME      // (float) volume in traded token (no digits devision necessary)
        ],
        ...
    ],
    from      : FROM_TIMESTAMP, // (uint)
    to        : TO_TIMESTAMP,   // (uint)
    precision : PRECISION       // (string) from config.barDataPrecisions (e.g. "1h")
    last      : IS_LAST         // (bool)   tells you if this timeframe is the oldest one containing any data
}

Conversion Rate Events

You can subscribe to the internal FIAT conversion rates used by the market platform. These will be sent in a channel whose id is the conversion pair, e.g. "ETHUSD".

rate

Event ID: 'r'

1
RATE // (float) this packet just contains the rate, the pair is the channel id

Personal Events

Personal Events are all sent on channel 0 if not stated otherwise.

auth

auth status is sent as a response to authenticate, authenticateWithSession and logoff

Event ID: 'auth'

1
2
3
4
5
6
[
    STATUS,      // (string)    "authenticated", or "loggedOff"
    ADDRESS,     // (hexString) the authenticated address (check this when implementing to ensure you used the right signing scheme)
    SESSION_ID,  // (string)    can be used to authenticate with authenticateWithSession
    DELEGATE     // (hexString) address of the delegate you authenticated with
]

SESSION_ID can be used to authenticate with authenticateWithSession

balanceSnapshot

balanceSnapshot is sent after a successful authentication of the connection.

Event ID: 'bs'

1
2
3
4
5
6
7
8
9
[   // array of your balances
    [   // balance object
        TOKEN,            // (string)
        SETTLED_BALANCE,  // (uintString) the settled balance on the blockchain
        USABLE_BALANCE,   // (uintString) the available balance you can use on the exchange to place orders
        BLOCKED_BALANCE   // (uintString) the amount you blocked in the smart contract for single-sig withdrawal
    ],
    ...
]

balanceStatus

balanceStatus is sent when the balance in one of your wallets changes.

Event ID: 'b'

1
2
3
4
5
6
[   // balance object
    TOKEN,            // (string)
    SETTLED_BALANCE,  // (uintString) the settled balance on the blockchain
    USABLE_BALANCE,   // (uintString) the available balance you can use on the exchange to place orders
    BLOCKED_BALANCE   // (uintString) the amount you blocked in the smart contract for single-sig withdrawal
]

delegateSnapshot

Is an array of delegate objects which are specified in delegateStatus

Event ID: 'ds'

delegateStatus

delegateStatus is sent when the status/label of one of your Delegated Signing Keys changes.

Event ID: 'd'

1
2
3
4
5
6
7
8
[   // balance object
    DELEGATE_ADDRESS,   // (hexString) the delegates address
    ACTIVE,             // (bool)      indicating wether the delegate is active on the blockchain
    ACCEPTED,           // (bool)      indicating wether the delegates signatures are accepted by the server (can be false despite active, if removal signature was issued)
    REMOVAL_SIGNATURE,  // (hexString) the amount you blocked in the smart contract for single-sig withdrawal
    LABEL,              // (string)    the delegates label (if set)
    IS_TRADING_LOGIN,   // (bool)      indicating wether the delegate is a trading login (to differenciate in graphical interfaces)
]

pendingLedgerEntrySnapshot

Is array of ledgerEntry objects which are specified in ledgerEntryStatus

Event ID: 'les'

historicalLedgerEntries

Sends ledger entries queried by getHistoricalLedgerEntries.

Event ID: 'hle'

1
2
3
4
5
6
7
8
9
{
    ledgerEntries : [
        // is an array of ledgerEntry objects which are specified in the ledgerEntryStatus event
    ]
    from   : FROM_PARAMETER,   // (uint) (optional) input parameter if it was set
    to     : TO_PARAMETER,     // (uint) (optional) input parameter if it was set
    before : BEFORE_PARAMETER, // (uint) (optional) input parameter if it was set
    limit  : LIMIT_PARAMETER   // (uint) (optional) input parameter if it was set
}

ledgerEntryStatus

ledgerEntryStatus events are sent when a new ledger entry is created of the status of the underlying transaction updates.

Event ID: 'le'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[   //Ledger Entry Objects
    ID,               // (uint)
    TYPE,             // (string) deposit, trade, withdrawal
    CHANGES,          // (array)  [[TOKEN_SYMBOL (string), AMOUNT (intString), FEES (intString), NET_AMOUNT (intString)], ...]
    APPLIED,          // (array)  Which wallet these changes were or will be applied to
                          // [[SETTLED_BALANCE (int), USABLE_BALANCE (int), BLOCKED_BALANCE] (int), ...]
                          // (1: is applied, 0: will be applied, -1 not affected)
    SIGNATURE,        // (object) { v : (uint), r : (hexString), s : (hexString), nonce : (uint) }
    TRANSACTION_HASH, // (hexString)
    BLOCK_NUMBER,     // (uint)
    BLOCK_HASH,       // (hexString)
    CANCELED,         // (bool)
    TIMESTAMP,        // (uint)
    DESCRIPTION       // (string)
]

activeOrderSnapshot

Is an array of order objects which are specified in orderStatus

Event ID: 'os'

historicalOrders

Sends historical orders queried by getHistoricalOrders.

Event ID: 'ho'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    orders : [
        // is an array of order objects which are specified in the orderStatus event
    ]
    market : MARKET_PARAMETER, // (uint) (optional) input parameter if it was set
    from   : FROM_PARAMETER,   // (uint) (optional) input parameter if it was set
    to     : TO_PARAMETER,     // (uint) (optional) input parameter if it was set
    before : BEFORE_PARAMETER, // (uint) (optional) input parameter if it was set
    limit  : LIMIT_PARAMETER   // (uint) (optional) input parameter if it was set
}

Is an array of order objects which are specified in orderStatus

orderStatus

orderStatus events are sent when a new order is created or its status changes (it gets executed, updated or canceled).

Event ID: 'o'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[ //Order object
    ID,                     // (uint)
    CID,                    // (uint)
    HASH,                   // (hexString)
    MARKET,                 // (string)
    ACTIVE,                 // (bool)
    CANCELED,               // (bool)

    SELL_TOKEN,             // (string) symbol of the token to be sold
    BUY_TOKEN,              // (string) symbol of the token to buy
                            // (order is a buy order if BUY_TOKEN is the markets traded token)

    SELL_TOKEN_AMOUNT,      // (uintString) signed amount of SELL_TOKEN to sell
    BUY_TOKEN_AMOUNT,       // (uintString) signed amount of BUY_TOKEN to buy

    SELL_TOKEN_REMAINING,   // (uintString) remaining (unmatched) sell amount (portion of the signed amount)
    BUY_TOKEN_REMAINING,    // (uintString) remaining (unmatched) buy amount (portion of the signed amount)

    SELL_TOKEN_BOOK_AMOUNT, // (uintString) portion of the remaining sell amount which is in the books
    BUY_TOKEN_BOOK_AMOUNT,  /* (uintString) portion of the remaining buy amount which is in the books
                                            This can be higher than the remaining amount if you plan to match at a better
                                            than the signed rate or got matched at a better rate in the past. */

    BOOK_RATE,              /* (floatString) the rate the order is at in the order book
                                             for buy orders this is:
                                             (SELL_TOKEN_BOOK_AMOUNT / (10 ^ SELL_TOKEN_DIGITS)) / (BUY_TOKEN_BOOK_AMOUNT  / (10 ^ BUY_TOKEN_DIGITS))
                                             for sell orders:
                                             (BUY_TOKEN_BOOK_AMOUNT  / (10 ^ BUY_TOKEN_DIGITS))  / (SELL_TOKEN_BOOK_AMOUNT / (10 ^ SELL_TOKEN_DIGITS))
                                             rounded to a Precision of 5 significant digits and a maximum of 8 digits
                                             (round down for buy orders and up for sell orders) */

    PEGGED_CURRENCY,        // (string)      e.g. "USD" or "EUR" if the order is a pegged order
    PEGGED_RATE,            // (floatString) the rate the order is pegged to

    HIDDEN,                 // (bool)   indicating if the order is hidden
    TRADES,                 // (array)  [TRADE_ID (uint), ...]
    INFO_STRING,            // (string) can contain information about the orders status
    NONCE,                  // (uint)   the nonce the order was signed with
    TIMESTAMP,              // (uint)   the timestamp (in ms) the order was placed at
    LAST_ACTIVE_TIMESTAMP   // (uint)   the timestamp (in ms) the order was last active at
]

userTrades

Sends ledger entries queried by getUserTrades.

Event ID: 'uts'

1
2
3
4
5
6
7
8
9
{
    trades : [
        // is an array of userTrade objects which are specified in the userTrade event
    ]
    from   : FROM_PARAMETER,   // (uint) (optional) input parameter if it was set
    to     : TO_PARAMETER,     // (uint) (optional) input parameter if it was set
    before : BEFORE_PARAMETER, // (uint) (optional) input parameter if it was set
    limit  : LIMIT_PARAMETER   // (uint) (optional) input parameter if it was set
}

userTrade

userTrade events will be pushed when the authenticated address was involved in a trade. They will not be pushed in the personal channel, but in the market channel the trade happened in.

Event ID: 'ts'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[   //userTrade object
    ID,                 // (uint)
    MARKET,             // (string)
    DIRECTION,          // 1 if it was a buy trade, 0 if it was a sell trade
    RATE,               // (floatString) the rate the trade was executed at
    AMOUNT,             // (uintString)  the amount of the markets traded token which was traded
    TRADE_FEE,          // (uintString)  the trade fee payed
    SETTLEMENT_FEE,     // (uintString)  the settlement fee payed to the ethereum network
    MAKER_REBATE,       // (uintString)  the amount of rebate you received
    REBATE_TOKEN,       // (string)      the token in which you received the rebate
    TIMESTAMP,          // (uint)        the trades timestamp (in ms)
    INVOLVED_ORDER_ID,  // (uint)        the id of your involved order
    INVOLVED_ORDER_CID  // (uint)        the cid of your involved order
]

signedWithdrawal

This event is sent as an answer to signWithdrawal. It contains the signatures needed for a multisignature withdrawal. The signature will be attached to the corresponding ledgerEntry afterwards.

Event ID: 'sw'

1
2
3
4
{
    sig : SIGNATURE,      // (object) { v : (uint), r : (hexString), s : (hexString), nonce : (uint) }
    id  : LEDGER_ENTRY_ID
}

feeTier

This event will tell you your 30d trailing volume and the maker and taker fees for your tier.

You will receive this event when you authenticate and receive updates when your fee tier changes. If you want an update on your traded volume in the meantime, call getFeeTier.

Event ID: 'ft'

1
2
3
4
5
[
    TRAILING_ETH_VOLUME_30D, // (float) the ETH value of your 30 day trailing trading volume
    MAKER_FEE,               // (float) your maker fee
    TAKER_FEE                // (float) your taker fee
]