v0.md

WebSocket API Specification v0

Table of Contents

• Websocket API
  • Orderbook channel
    • Request messages
      • Subscribe
    • Response messages
      • Snapshot
      • Update

Websocket API

Orderbook Channel

Request messages

Subscribe

See payload schema

{
    "type": "subscribe",
    "channel": "orderbook",
    "requestId": 1,
    "payload": {
        "baseTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
        "quoteTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
        "snapshot": true,
        "limit": 100
    }
}

• requestId - an integer that will be sent back by the server in response messages so the client can appropriately respond when multiple subscriptions are made
• baseTokenAddress - address of token designated as the baseToken in the currency pair calculation of price (required)
• quoteTokenAddress - address of token designated as the quoteToken in the currency pair calculation of price (required)
• snapshot - if true, a snapshot of the orderbook will be sent before any updates to the orderbook
• limit - maximum number of bids and asks in orderbook snapshot

Response messages

Snapshot

This message is sent in response to a subscribe message with the payload/snapshot property set to true detailed above. It should be the first message received in response to a subscribe message.

See payload schema

{
    "type": "snapshot",
    "channel": "orderbook",
    "requestId": 1,
    "payload": {
        "bids": [
            {
                "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                "makerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
                "takerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
                "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
                "makerTokenAmount": "22000000000000000",
                "takerTokenAmount": "10000000000000000",
                "makerFee": "100000000000000",
                "takerFee": "200000000000000",
                "expirationUnixTimestampSec": "632",
                "salt": "54515451557974875123697849345751275676157243756715784155226239582178",
                "ecSignature": {
                    "v": 27,
                    "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                    "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
                }
            },
            ...
        ],
        "asks": [
            {
                "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
                "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
                "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
                "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
                "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
                "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
                "makerTokenAmount": "10000000000000000",
                "takerTokenAmount": "20000000000000000",
                "makerFee": "100000000000000",
                "takerFee": "200000000000000",
                "expirationUnixTimestampSec": "42",
                "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
                "ecSignature": {
                    "v": 27,
                    "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
                    "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
                }
            },
            ...
        ]
    }

}

• requestId - an integer that corresponds to the requestId sent by the client in the subscribe message
• bids - array of signed orders where takerTokenAddress is equal to baseTokenAddress
• asks - array of signed orders where makerTokenAddress is equal to baseTokenAddress

Bids will be sorted in descending order by price, and asks will be sorted in ascending order by price. Within the price sorted orders, the orders are further sorted first by total fees, then by expiration in ascending order.

Update

This message is sent whenever the relayer receives or hears about a new order.

See payload schema

{
    "type": "update",
    "channel": "orderbook",
    "requestId": 1,
    "payload": {
        "exchangeContractAddress": "0x12459c951127e0c374ff9105dda097662a027093",
        "maker": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
        "taker": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
        "makerTokenAddress": "0x323b5d4c32345ced77393b3530b1eed0f346429d",
        "takerTokenAddress": "0xef7fff64389b814a946f3e92105513705ca6b990",
        "feeRecipient": "0xb046140686d052fff581f63f8136cce132e857da",
        "makerTokenAmount": "10000000000000000",
        "takerTokenAmount": "20000000000000000",
        "makerFee": "100000000000000",
        "takerFee": "200000000000000",
        "expirationUnixTimestampSec": "42",
        "salt": "67006738228878699843088602623665307406148487219438534730168799356281242528500",
        "ecSignature": {
            "v": 27,
            "r": "0x61a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33",
            "s": "0x40349190569279751135161d22529dc25add4f6069af05be04cacbda2ace2254"
        }
    }
}

• requestId - an integer that corresponds to the requestId sent by the client in the subscribe message