JSON-RPC over Websocket

JSON-RPC

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. It uses JSON (RFC 4627) as the data format.

All member names exchanged between the Client and the Server that are considered for matching of any kind should be considered to be case-sensitive. The Client is defined as the origin of Request objects and the handler of Response objects. The Server is defined as the origin of Response objects and the handler of Request objects. A trader using the API can fill both the role of the Client and the Server depending on the Request.

Error Codes

The following error codes relate to establishing a JSON-RPCoverWebSocket connection:

Cancel on Disconnect (COD)

Cancel on Disconnect mode is enabled on all JSON-RPCoverWebSocket connections by default and must be specified as false to disable. Every connection must be set to false in order to disable Cancel-on-Disconnect.

In Unified Markets:

• Cancel on Disconnect will cancel all OPEN created RFQ markets.
• Cancel on Disconnect will cancel all OPEN created Orders in DRFQ, GRFQ, and VRFQ.

In FSPD:

• Cancel on Disconnect will cancel all OPEN created Orders.

Cancel on Disconnect mode will cancel all created RFQs & Orders that have been requested with the same Paradigm API Key used to authenticate the WebSocket connection & will only trigger when all associated WebSocket connections disconnect.

Connection String Examples

To disable Cancel on Disconnect mode, specify cancel_on_disconnect=false as a query string parameter in the connection URL to the JSON-RPCoverWebSocket interface.

DRFQ - JSON-RPCoverWebSocket Connection URL: wss://ws.api.testnet.paradigm.trade/v2/drfq/?api-key=<access-key>&cancel_on_disconnect=false

GRFQ - JSON-RPCoverWebSocket Connection URL: wss://ws.api.testnet.paradigm.trade/v1/grfq/?api-key=<access-key>&cancel_on_disconnect=false

VRFQ - JSON-RPCoverWebSocket Connection URL: wss://ws.api.testnet.paradigm.trade/v1/vrfq/?api-key=<access-key>&cancel_on_disconnect=false

FSPD - JSON-RPCoverWebSocket Connection URL: wss://ws.api.fs.testnet.paradigm.trade/v1/fs/?api-key=<access-key>&cancel_on_disconnect=false

Request Objects

An example of a JSON-RPCoverWebSocket Request message

1
{
2
    "id": "1",
3
    "jsonrpc": "2.0",
4
    "method": "subscribe",
5
    "params": {
6
        "channel": "rfq"
7
    }
8
}

An RPC call is represented by sending a Request object to a Server.

The Request object has the following attributes:

Response Objects

An example of a Successful Response message

1
{
2
    "id": "1",
3
    "jsonrpc": "2.0",
4
    "result": [
5
        "rfq",
6
        "trade"
7
    ]
8
}

An example of an Erroneous Response message

1
{
2
    "id": "1",
3
    "jsonrpc": "2.0",
4
    "error": {
5
        "code": -32601,
6
        "message": "method not found",
7
        "data": {
8
           "method": "unsubscribe-all",
9
           "timestamp": 1597326842.415
10
        }
11
    }
12
}

When an RPC call is made, the Server replies with a Response, except for in the case of Notifications. The Response is expressed as a single JSON Object, with the following attributes:

Session Methods

Heartbeat

An example of a JSON-RPCoverWebSocket heartbeat Request Object

1
{
2
    "id": 1,
3
    "jsonrpc": "2.0",
4
    "method": "heartbeat"
5
}

An example of a JSON-RPCoverWebSocket heartbeat Response Object

1
{
2
    "id": 1,
3
    "jsonrpc": "2.0"
4
}

The client is required to regularly send heartbeat Requests to the user over a WebSocket connection at least once every 10 seconds.

If the user does not send a heartbeat in a given 10-second window, the WebSocket connection will be closed by Paradigm.

Paradigm will respond to a heartbeat Request with a heartbeat Response.

Error Codes

The following error code relates to maintaining a heartbeat:

Subscription Methods

Subscriptions work as Notifications, so users will automatically (after subscribing) receive messages from the server.

They are the primary means through which you should intend to receive updates regarding RFQs, Quotes, Orders (GRFQ+FSPD) and Trades.

Subscriptions are only available through WebSockets as these are sent asynchronously from Paradigm to the user as they happen.

Subscription Notification objects have the following attributes:

Subscribe

An example of a subscribe Request Object

1
{
2
   "id": 123,
3
   "jsonrpc": "2.0",
4
   "method": "subscribe",
5
   "params": {
6
            "channel": "rfq"
7
   }
8
}

An example of a subscribe Response Object

1
{
2
    "id": 123,
3
    "jsonrpc": "2.0",
4
    "result": [
5
               "rfq",
6
               "trade"
7
    ]
8
}

For DRFQ, there are four subscription channels you can subscribe to: rfq, quote, trade, and trade_confirmation.

For GRFQ, there are six subscription channels you can subscribe to: rfq, quote_book, order, quote, trade, and trade_tape.

For VRFQ, there are three subscription channels you can subscribe to: rfq, quote, and trade.

For FSPD, there are six subscription channels you can subscribe to: strategy_state.{venue}.{kind}, order_book.{strategy_id}.{level}, orders.{venue}.{kind}.{strategy_id}, trades.{venue}.{kind}.{strategy_id}, trade_tape.{venue}.{kind}.{strategy_id}, and venue_bbo.{strategy_id}.

To subscribe to multiple channels, send a separate subscribe request for each channel.

The Request params object has the following attributes:

Unsubscribe

An example of an unsubscribe Request Object

1
{
2
   "id": 123,
3
   "jsonrpc": "2.0",
4
   "method": "unsubscribe",
5
   "params": {
6
      "channel": "rfq"
7
   }
8
}

An example of an unsubscribe Response Object

1
{
2
   "id": 123,
3
   "jsonrpc": "2.0",
4
   "result": [
5
            "trade"
6
   ]
7
}

To unsubscribe from multiple channels, send a separate unsubscribe request for each channel.

The Request params object has the following attributes: