# WebSocket API Specification v3

## Table of Contents

- [WebSocket API Specification v3](#websocket-api-specification-v3)

    - [Websocket API](#websocket-api)
        - [Orders Channel](#orders-channel)
            - [Request messages](#request-messages)
                - [Subscribe](#subscribe)
            - [Response messages](#response-messages)
                - [Update](#update)

## 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](https://github.com/0xProject/standard-relayer-api/blob/master/http/v3.md) by providing updates without resorting to polling.

### Orders Channel

#### Request messages

##### Subscribe

[See payload schema](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_channel_subscribe_schema.json#L1)

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](https://0xproject.com/docs/0x.js#types-AssetProxyId) (example: `0xf47261b0` for `ERC20`, `0x02571792` for `ERC721`)
*   `takerAssetProxyId`:  returns orders where the taker asset is of certain [asset proxy id](https://0xproject.com/docs/0x.js#types-AssetProxyId)(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](https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/relayer_api_orders_channel_update_response_schema.json#L1)

```
{
    "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