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:

Code	Meaning
HTTP 403	An invalid or incorrect Paradigm API Access Key was used to authenticate the JSON-RPCoverWebSocket connection.
HTTP 403	Incorrect 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

{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "channel": "rfq"
    }
}

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

The Request object has the following members:

Member	Type	Req	Description
id	string or number	N	An identifier established by the Client. The id is omitted if the method is a Notification.
jsonrpc	string	Y	The version of the JSON-RPC protocol. Always "2.0".
method	string	Y	The name of the method to be invoked.
params	object	N	The 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

{
    "id": "1",
    "jsonrpc": "2.0",
    "result": [
        "rfq",
        "trade"
    ]
}

An example of an Erroneous Response message

{
    "id": "1",
    "jsonrpc": "2.0",
    "error": {
        "code": -32601,
        "message": "method not found",
        "data": {
           "method": "unsubscribe-all",
           "timestamp": 1597326842.415
        }
    }
}

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 members:

Member	Type	Req	Description
id	string or number	N	The 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.
jsonrpc	string	Y	The version of the JSON-RPC protocol. Always "2.0".
result	object	N	The result of a successful request. The value is determined by the specific method invoked. Not present if there is an erroneous result.
error	Error object	N	The result of an erroneous request. Not present if there is a successful result.
> code	number	N	Error code.
> message	string	N	Error message.
> data	object	N	Array of information relating to error.
>> method	string	N	Erroneous request method.
>> timestamp	decimal	N	The 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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "heartbeat"
}

An example of a JSON-RPCoverWebSocket heartbeat Response Object

{
    "id": 1,
    "jsonrpc": "2.0"
}

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.

Note: 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:

Code	Meaning
4005	Paradigm 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 members:

Member	Type	Req	Description
jsonrpc	string	Y	Always "2.0".
method	string	Y	Always subscription.
params	object	Y	Array of returned data.
> channel	string	Y	The name of the channel.
> data	object	Y	Data specific to the channel.

subscribe

An example of a subscribe Request Object

{
   "id": 123,
   "jsonrpc": "2.0",
   "method": "subscribe",
   "params": {
            "channel": "rfq"
   }
}

An example of a subscribe Response Object

{
    "id": 123,
    "jsonrpc": "2.0",
    "result": [
               "rfq",
               "trade"
    ]
}

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.

Note: The Response result is a JSON array of all channels currently subscribed to (DRFQ+GRFQ).

The Request params object has the following members:

Member	Type	Req	Description
channel	string	Y	The channel to subscribe to.
data	object	N	An channel-specific object that specifies parameters for the channel.

unsubscribe

An example of an unsubscribe Request Object

{
   "id": 123,
   "jsonrpc": "2.0",
   "method": "unsubscribe",
   "params": {
      "channel": "rfq"
   }
}

An example of an unsubscribe Response Object

{
   "id": 123,
   "jsonrpc": "2.0",
   "result": [
            "trade"
   ]
}

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

Note: The Response result is a JSON array of all channels currently subscribed to.

The Request params object has the following members:

Member	Type	Req	Description
channel	string	Y	The channel to unsubscribe from.