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:

CodeMeaning
HTTP 403An invalid or incorrect Paradigm API Access Key was used to authenticate the JSON-RPCoverWebSocket connection.
HTTP 403Incorrect connection query string used.

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:

AttributeTypeReqDescription
idstring or numberNAn identifier established by the Client. The id is omitted if the method is a Notification.
jsonrpcstringYThe version of the JSON-RPC protocol. Always “2.0”.
methodstringYThe name of the method to be invoked.
paramsobjectNThe parameter values to be used during the invocation of the method. This field may be omitted if the method has no parameters.

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:

AttributeTypeReqDescription
idstring or numberNThe same value of the id field specified on the Request object. The value is null if there is an error parsing the Request object. The value is omitted in a Notification.
jsonrpcstringYThe version of the JSON-RPC protocol. Always “2.0”.
resultobjectNThe result of a successful request. The value is determined by the specific method invoked. Not present if there is an erroneous result.
errorError objectNThe result of an erroneous request. Not present if there is a successful result.
> codenumberNError code.
> messagestringNError message.
> dataobjectNArray of information relating to error.
>> methodstringNErroneous request method.
>> timestampdecimalNThe time the error occurred as the number of unix milliseconds since epoch (January 1, 1970).

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.

The Request does not have a params object and the Response does not have a results object.

Error Codes

The following error code relates to maintaining a heartbeat:

CodeMeaning
4005Paradigm did not receive a heartbeat from the WebSocket connection within the past 10 seconds.

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:

AttributeTypeReqDescription
jsonrpcstringYAlways "2.0".
methodstringYAlways subscription.
paramsobjectYArray of returned data.
> channelstringYThe name of the channel.
> dataobjectYData specific to the channel.

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 Response result is a JSON array of all channels currently subscribed to (DRFQ+GRFQ).

The Request params object has the following attributes:

AttributeTypeReqDescription
channelstringYThe channel to subscribe to.
dataobjectNAn channel-specific object that specifies parameters for the channel.

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 Response result is a JSON array of all channels currently subscribed to.

The Request params object has the following attributes:

AttributeTypeReqDescription
channelstringYThe channel to unsubscribe from.

Built with