WebSocket API Specification v3

November 9, 2019 ยท View on GitHub

Table of Contents

Chain Id

The Standard Relayer API V3 does not specify how to deal with different chain ids (formerly called network ids). The recommendation is to provide a different SRA URL for every chain id that you support. For example, if your mainnet SRA websocket endpoint is hosted at ws://api.relayer.com/sra/v3/ then the Kovan endpoint could be hosted at ws://kovan.api.relayer.com/sra/v3/.

Websocket API

The SRA Websocket API is meant to supplement the REST API by providing updates without resorting to polling.

Orders Channel

Request messages

Subscribe

See payload schema

Minimum request:

{
    "type": "subscribe",
    "channel": "orders",
    "requestId": "123e4567-e89b-12d3-a456-426655440000"
}

This will subscribe to all new orders and order state changes in the orderbook.

Filtered request:

{
    "type": "subscribe",
    "channel": "orders",
    "requestId": "123e4567-e89b-12d3-a456-426655440000",
    "payload": {
        "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
        "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063"
    }
}

This will subscribe to all new Kovan orders and Kovan order state changes in the orderbook with makerAssetData and takerAssetData equal to the values specified in the subscribe request.

Parameters

General:

  • requestId: a string uuid that will be sent back by the server in response messages so the client can appropriately respond when multiple subscriptions are made

Filter parameters (optional):

  • makerAssetProxyId : returns orders where the maker asset is of certain asset proxy id (example: 0xf47261b0 for ERC20, 0x02571792 for ERC721)
  • takerAssetProxyId: returns orders where the taker asset is of certain asset proxy id(example: 0xf47261b0 for ERC20, 0x02571792 for ERC721)
  • makerAssetAddress: subscribes to new orders where the contract address for the maker asset matches the value specified
  • takerAssetAddress: subscribes to new orders where the contract address for the taker asset matches the value specified

Order specific parameters (optional):

  • makerAssetData: subscribes to new orders with the specified makerAssetData
  • takerAssetData: subscribes to new orders with the specified takerAssetData
  • traderAssetData: subscribes to new orders where either makerAssetData or takerAssetData has the value specified

While there is some redundancy in supporting maker/takerAssetType, maker/takerAssetAddress, and maker/takerAssetData, they are actually all needed. For example, you cannot query "all ERC712 orders", or "all Cryptokitties orders", or "all ERC20 orders" with just maker/takerAssetData and need the other query params to do so.

Response messages

Update

This message is sent whenever the relayer receives a new order, or when the relayer deems an update necessary (such as when the state of the order changes). For example, some relayers may implement the remainingTakerAssetAmount field. If this is the case, the scenarios where an update may occur include:

  • The relayer received a new order.
  • An order was fully or partially filled, so remainingTakerAssetAmount has changed.
  • The order is cancelled.

An update is not necessary for order expiration, as that information can be derived from the expirationTimeSeconds field in the order.

Updates can be sent in bulk since the payload of the message specifies a collection of updated or new orders.

See payload schema

{
    "type": "update",
    "channel": "orders",
    "requestId": "123e4567-e89b-12d3-a456-426655440000",
    "payload":  [
        {
          "order": {
              "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
              "domainHash" "0x78772b297e1b0b31089589a6608930cceba855af9d3ccf7b92cf47fa881e21f7",
              "makerAddress": "0x9e56625509c2f60af937f23b7b532600390e8c8b",
              "takerAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
              "feeRecipientAddress": "0xb046140686d052fff581f63f8136cce132e857da",
              "senderAddress": "0xa2b31dacf30a9c50ca473337c01d8a201ae33e32",
              "makerAssetAmount": "10000000000000000",
              "takerAssetAmount": "20000000000000000",
              "makerFee": "100000000000000",
              "takerFee": "200000000000000",
              "expirationTimeSeconds": "1532560590",
              "salt": "1532559225",
              "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
              "takerAssetData": "0x02571792000000000000000000000000371b13d97f4bf77d724e78c16b7dc74099f40e840000000000000000000000000000000000000000000000000000000000000063",
              "exchangeAddress": "0x12459c951127e0c374ff9105dda097662a027093",
              "makerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
              "takerFeeAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498",
              "signature": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33"
            },
            "metaData": {
              "remainingTakerAssetAmount": "500000000"
            }
        },
        ...
    ]
}
  • requestId - a string uuid that corresponds to the requestId sent by the client in the subscribe message