Paradigm API v1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Introduction

Paradigm's three major products are Unified Markets (UM), the Future Spread Dashboard (FSPD), and Vault Request for Quote (VRFQ).

Paradigm provides a GUI to access all products via a desktop application as well as your internet browser.

Paradigm provides RESToverHTTP and JSON-RPCoverWebSockets API interfaces for users with workflows consistent with the broader crypto space.

Feel free to reach out to our account management team or technical solutions team as we would love to help!

UM - Brief Overview

Unified Markets (UM) has two products, Directed Request for Quote (DRFQ) and Global Request for Quote (GRFQ), which make up the UM user interface.

DRFQ enables users to create short-lived private auction RFQ markets. Users must specify the structure of the market as well as the counterparties who are able to return prices. In DRFQ, only the creator of the market is able to see the returned prices from the Makers and is able to cross a Maker's order. Makers are unable to see eachother's prices or their order's relative priority. To note, there are two versions of DRFQ, DRFQv1 and DRFQv2. Users should use DRFQv2 as DRFQv1 will be deprecated in due course.

GRFQ enables users to create long-lived public auction Central Limit Order Book markets. Users must specify the structure of the market and anyone is able to participate. In GRFQ, all orders submitted are blind and are actionable by any user.

Deribit, BIT, and Bybit are available as venues.

FSPD - Brief Overview

The Future Spread Dashboard (FSPD) enables users to trade two-legged Spot/Future or Future/Future strategies in long-lived public auction Central Limit Order Book markets. Paradigm manages the availability of markets. In FSPD, all orders submitted are blind and are actionable by any user.

Deribit and Bybit are available as venues.

VRFQ - Brief Overview

Vault Request for Quote (VRFQ) enables vault providers to create short-lived private auction RFQ markets. In VRFQ, only the creator of the market is able to see the returned prices, the associated counterparty & is able to execute upon the market.

Ribbon is available as a venue.

Rate Limits

Desks cannot scale their rate limit capacity by using multiple Paradigm API Keys.

DRFQv2

RESToverHTTP requests are rate limited to 500 requests per second per desk across all API Keys. This applies to all types of requests and is not configurable per desk.

GRFQ

RESToverHTTP requests are rate limited to 500 requests per second per desk across all API Keys. This applies to all types of requests and is not configurable per desk.

FSPD

RESToverHTTP requests are rate limited per desk and type of request. [GET] requests are limited to 100 requests per second, while [POST] / [PATCH] / [DELETE] requests are limited to 10 requests per second. Paradigm is able to configure these limits upon request by the user.

Onboarding

Paradigm offers both test and production environments. We would love to create as many Paradigm test accounts as you would like.

Paradigm's servers are based in AWS eu-west-2. You should ensure Paradigm's IPs have been added to your Settlement Venue API Credentials' IP whitelist.

We would love to create as many test environment accounts as you need. Please reach out to your account management representative or our technical solutions team with the following information:

• A unique email address in Paradigm's test environment with your First and Last Name.
• The "Firm" you would like the desk associated with (if you know).

API Connection URLs

Here are the base connection URLs for Paradigm's API interfaces & product suffixes to be concentated for requests.

Base URL | Live Environment

• RESToverHTTP: https://api.prod.paradigm.trade

• JSON-RPCoverWebSocket: wss://ws.api.prod.paradigm.trade

• FSPD only: RESToverHTTP: https://api.fs.prod.paradigm.trade

• FSPD only: JSON-RPCoverWebSocket: wss://ws.api.fs.prod.paradigm.trade

Base URL | Test Environment

• RESToverHTTP: https://api.testnet.paradigm.trade

• JSON-RPCoverWebSocket: wss://ws.api.testnet.paradigm.trade

• FSPD only: RESToverHTTP: https://api.fs.testnet.paradigm.trade

• FSPD only: JSON-RPCoverWebSocket: wss://ws.api.fs.testnet.paradigm.trade

Product & Version

• DRFQ: /v2/drfq
• GRFQ: /v1/grfq
• FSPD: /v1/fs
• VRFQ: /v1/vrfq

Test Environment Examples

• DRFQ - [GET] /counterparties - Example: [GET] https://api.testnet.paradigm.trade/v2/drfq/counterparties

• DRFQ - WS Connection URL - Example: wss://ws.api.testnet.paradigm.trade/v2/drfq?api-key=ABC123

• GRFQ - [GET] /rfqs/ - Example: [GET] https://api.testnet.paradigm.trade/v1/grfq/rfqs/

• GRFQ - WS Connection URL - Example: wss://ws.api.testnet.paradigm.trade/v1/grfq?api-key=ABC123

• FSPD - [GET] /instruments - Example: [GET] https://api.fs.testnet.paradigm.trade/v1/fs/instruments

• FSPD - WS Connection URL - Example: wss://ws.api.fs.testnet.paradigm.trade/v1/fs?api-key=ABC123

• VRFQ - [GET] /rfqs/ - Example: [GET] https://api.testnet.paradigm.trade/v1/vrfq/rfqs/

• VRFQ - WS Connection URL - Example: wss://ws.api.testnet.paradigm.trade/v1/vrfq?api-key=ABC123

Helpful Reminders

• You CANNOT create RFQs, cross Orders, or trade against yourself on Paradigm.
• All instruments on Paradigm are the same instruments you trade on the underlying settlement venue. As such, this means that all instruments traded on Paradigm must conform to the contract specifications of the underlying settlement venue. Supported Venue & Instrument Contract Specifications
• You will need to use multiple desks associated with different settlement venue subaccounts if you wish to trade against yourself on Paradigm. You cannot use the same venue subaccount's venue API Credentials to trade against one's self even if use separate Paradigm desks.

Settlement Venue Testnet URLs

• Deribit's Testnet: test.deribit.com
• BIT's Testnet: beta.bitexch.dev
• Bybit's Testnet: testnet.bybit.com

High Level Implementation Notes

Your solution should

• Use the JSON-RPCoverWebSocket interface to receive real-time updates about events.
• For JSON-RPCoverWebSocket connections, ensure a heartbeat has been initiated and is being maintained.
• Use the RESToverHTTP interface to interact with Paradigm.
• Wait for responses to RESToverHTTP requests to confirm successful or erroneous interactions.
• Ensure each request has the necessary authentication attributes as each request must be authenticated.

Your solution should not

• Use the RESToverHTTP interface to poll for event updates.
• Use the JSON-RPCoverWebSockets interface to send payload requests to Paradigm.

Taker Limits & Maker Protections

Paradigm enforces a number of limitations to ensure markets operate fairly and discourage negative practices. These limitations to specific user actions are at the sole discretion of Paradigm with changes communicated as they occur.

Taker Execution Limits

Taker Execution Limits limit the number of times Takers are able to execute upon markets in a rolling time window. Presently, this is one execution within a 2-second rolling window per product.

This applies only to products apart of Unified Markets, specifically DRFQ & GRFQ.

Taker Market Creation Limits

Taker Market Creation Limits limit the number of RFQs and Order Book markets users are able to create. Presently, users are able to create one market every three seconds on a rolling basis per product.

This applies only to products apart of Unified Markets, specifically DRFQ & GRFQ.

Market Maker Protection (MMP)

Market Maker Protection (MMP) protects Makers from rapid executions of orders in the market.

MMP is triggered when as a Maker two of your resting orders are executed upon within a one second rolling window.

When triggered:

• All of desks' existing Orders, for the product wherein the protection was triggered, are canceled by Paradigm.
• The desk is unable to create additional orders until the protection has been removed.

To remove this protection, users are able to immediately request the [PATCH] /v1/{product}/mmp/status/ endpoint. The protection is automatically removed within 10 seconds of triggered by Paradigm without any neccessary interaction by the user.

This feature is enabled for all Paradigm users and cannot be disabled. The conditions of MMP being triggered cannot be configured by the user.

This applies only to products apart of Unified Markets, specifically DRFQ & GRFQ.

Errors

All RESToverHTTP error responses follow the same basic format. An Error object is returned in response to an erroneous RESToverHTTP request, accompanied by an HTTP status code of 400.

Specific error codes are listed with each RESToverHTTP endpoint.

Error Object

An example of an erroneous Response message

{
    "code": 1002,
    "message": "Invalid enumeration set value",
    "data": {
        "member": "side",
        "value": "CROSS"
    }
}

The Error object is expressed as a single JSON Object, with the following members:

Error Codes

The following general error codes are supported by Paradigm:

Authentication

All Paradigm API endpoints are considered private and require authentication.

Paradigm uses token-based authentication for API access to both the RESToverHTTP and JSON-RPCoverWebSocket API endpoints.

As an additional protection measure against replay attacks in environments where SSL trust is not properly configured, Paradigm requires all RESToverHTTP requests to be signed using your Paradigm API Key's <secret-key>.

Important Notes:

• Paradigm does not currently provide fine-grained token scopes or permissions. Please ensure your API credentials are stored securely.
• If you have an IP whitelist set for your Venue API Keys, on the Venue, you will need to include Paradigm's IP addresses in your Venue API Key whitelists.

There are a number of Authentication methods available across both the RESToverHTTP and JSON-RPCoverWebSocket interfaces, these include:

• Token-based Authentication
• HTTP Header
• Cookie
• Query String Parameter (JSON-RPCoverWebSocket only)

Error Codes

The following error codes relate to Authentication Errors:

Generating a Paradigm API Key

Before accessing any RESToverHTTP or JSON-RPCoverWebSocket API endpoints, you must generate the necessary Paradigm API credentials. This can be accomplished via the Paradigm Admin Dashboard.

You use the same Paradigm API <access-key> & <secret-key> to authenticate requests for all Paradigm products.

Live Environment

Paradigm Admin Dashboard URL: https://admin.paradigm.trade/

Test Environment

Paradigm Admin Dashboard URL: https://admin.testnet.paradigm.trade/

Once Created

When you have generated Paradigm API credentials, you will be presented with two keys:

1. Access Key: used to authenticate the API.
2. Secret Key: used to sign requests against the API.

Be sure to save these two keys somewhere secure as both the Access Key and the Secret Key will only be visible once during creation.

If you lose either the <access-key> or the <secret-key>, you will need to generate a new Paradigm API Key via the Admin Dashboard.

Token-based Authentication

Only the <access-key> is needed for authenticating requests. The different methods are presented below in order of our preference.

HTTP Header

Authorization example with an HTTP Header

{
    "Authorization": "Bearer SXDlhLKYX6GH6InhBxcCzoW4"
}

When possible, authentication should be performed using the Authorization HTTP header. The header should supply the Paradigm API <access-key> in plain text, preceded by the text "Bearer ".

Authorization: Bearer <access-key>

Cookie

In some cases, providing custom HTTP headers may not be possible. This is particularly true when connecting to JSON-RPCoverWebSockets via browser APIs.

In these cases, the Paradigm API Key Access Key may be provided by a special HTTP cookie. The cookie should be defined as follows:

Paradigm-API-Key = <access-key>

Query String Parameter (for JSON-RPCoverWebSocket connections only)

In the unlikely scenario that you are unable to use HTTP headers or Cookies for authentication against the JSON-RPCoverWebSocket API, Paradigm supports a special HTTP query parameter.

The query parameter can be provided as part of the WebSocket connection URL.

Live Environment | URL Examples

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

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

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

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

Test Environment | URL Examples

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

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

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

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

Signing Requests

Paradigm requires all RESToverHTTP requests to be signed.

GET RESToverHTTP example demonstrating signing of requests

# A GET RESToverHTTP sample demonstrating the generation of signatures and signing of requests.

import base64
import hmac
import time
from urllib.parse import urljoin

import requests


def sign_request(secret_key, method, path, body):
    signing_key = base64.b64decode(secret_key)

    timestamp = str(int(time.time() * 1000)).encode('utf-8')
    message = b'\n'.join([timestamp, method.upper(), path, body])
    digest = hmac.digest(signing_key, message, 'sha256')
    signature = base64.b64encode(digest)

    return timestamp, signature


access_key = '<access-key>'
secret_key = '<secret-key>'
host = 'https://api.testnet.paradigm.trade'

# GET example
method = b'GET'
path = b'/v1/drfq/instruments/?venue=DBT&asset=BTC'
body = b''

timestamp, signature = sign_request(secret_key, method, path, body)
headers = {
    'Authorization': 'Bearer {}'.format(access_key),
    'Paradigm-API-Timestamp': timestamp,
    'Paradigm-API-Signature': signature,
}
url = urljoin(host, path.decode())
response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

POST RESToverHTTP example demonstrating signing of requests

# A POST RESToverHTTP sample demonstrating the generation of signatures and signing of requests.

import base64
import hmac
import json
import time
from urllib.parse import urljoin

import requests


def sign_request(secret_key, method, path, body):
    signing_key = base64.b64decode(secret_key)

    timestamp = str(int(time.time() * 1000)).encode('utf-8')
    message = b'\n'.join([timestamp, method.upper(), path, body])
    digest = hmac.digest(signing_key, message, 'sha256')
    signature = base64.b64encode(digest)

    return timestamp, signature


access_key = '<access-key>'
secret_key = '<secret-key>'
host = 'https://api.testnet.paradigm.trade'

# POST example
method = b'POST'
path = b'/v1/echo/'
data = {'message': 'hello'}
body = json.dumps(data).encode('utf-8')

timestamp, signature = sign_request(secret_key, method, path, body)
headers = {
    'Authorization': 'Bearer {}'.format(access_key),
    'Paradigm-API-Signature': signature,
    'Paradigm-API-Timestamp': timestamp,
    'Accept': 'application/json',
}
url = urljoin(host, path.decode())
response = requests.post(url, headers=headers, json=data)
print(response.status_code)
print(response.text)

Important Note: Signing is not currently supported for JSON-RPCoverWebSocket API endpoints.

Request signatures are generated by applying the HMAC-SHA256 function to your Paradigm API <secret-key> and a concatenated message consisting of the request timestamp, request method, request path, query parameters, and body. The key provided to the HMAC function must be the base64-decoded version of the <secret-key>. The signature must then be base64-encoded and passed via a special header value.

Some important considerations are:

• The timestamp must be a UNIX timestamp (milliseconds since epoch in UTC).
• The request method must be capitalized (e.g. GET).
• The request path must include the entire base path of the request (e.g. /rfq/).
• The request parameters must include ? (e.g. ?cursor=a2Ed&venue=DBT) unless none are used.
• The request body should be substituted with an empty string for GET requests.

Once the signature is generated, the timestamp and signature should be provided as HTTP headers:

Note: Signed requests are only valid for 30 seconds from when the timestamp is captured. Requests received after the 30-second window are rejected.

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

Cancel on Disconnect mode is enabled on all JSON-RPCoverWebSocket connections by default and must be specifed as false to disable.

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:

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:

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:

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:

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:

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:

Notification Channels

A Notification is a Request object without an id member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server must not reply to a Notification, including those that are within a batch request.

Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. "Invalid params", "Internal error").

Key Note: DRFQ, GRFQ, VRFQ, and the FSPD are separate products with separate JSON-RPCoverWebSocket connection URLs & subscriptions required. You must subscribe to the specific channels of each product you would like to receive notifications for.

DRFQv2 WebSocket Notification Channels

DRFQ JSON-RPCoverWebSocket notification channels are:

• rfqs - Private Updates relating to the availability of the RFQ market.
• rfq_orders - Private Updates relating to the available Orders upon RFQ markets.
• orders - Private Updates relating to the creation, cancellation and interactions of the user's Orders.
• trades - Private Updates relating to success or rejection of a the user's Trades.
• bbo.{rfq_id} - Public Updates relating to the prices+amounts of the RFQ's composite instruments from the underlying settlement venue.
• market_maker_protection - Private Updates relating to Market Maker Protection being triggered.

GRFQ WebSocket Notification Channels

GRFQ JSON-RPCoverWebSocket notification channels are:

• rfq - Public Updates relating to the creation and expiration of RFQs.
• quote_book - Public Updates relating to the creation and availability of Quotes.
• order - Private Updates relating to the creation and execution of Orders upon Quotes.
• quote - Private Updates relating to creation, execution, and cancellation of Quotes upon RFQs.
• trade - Private Updates relating to executions solely involving the Taker and Maker.
• trade_tape - Public Updates relating to all completed Trades on Paradigm through GRFQ.
• market_maker_protection - Private Updates relating to Market Maker Protection being triggered.

VRFQ WebSocket Notification Channels

VRFQ JSON-RPCoverWebSocket notification channels are:

• rfq - Public Updates relating to the creation and expiration of RFQs.
• quote - Private Updates relating to creation, execution, and cancellation of Quotes upon RFQs.
• trade - Private Updates relating to executions solely involving the Taker and Maker.

FSPD WebSocket Notification Channels

FSPD JSON-RPCoverWebSocket notification channels are:

• strategy_state.{venue}.{kind} - Public Updates relating to the creation, settlement, and expiration of Strategies.
• order_book.{strategy_id}.{level} - Public Updates relating to delta of Orders being added and removed from the Order Book.
• orders.{venue}.{kind}.{strategy_id} - Private Updates relating to the creation, cancellation and interactions of the user's Orders.
• trades.{venue}.{kind}.{strategy_id} - Private Updates relating to success or rejection of a the user's Trades.
• trade_tape.{venue}.{kind}.{strategy_id} - Public Updates relating to all completed Trades on Paradigm through FSPD.
• venue_bbo.{strategy_id} - Public Updates relating to the prices+amounts of the Strategies' composite instruments from the underlying settlement venue.

Shared - REST Endpoints

The following REST Endpoints have no version or product identifier in the Connection URL as they are shared across the Paradigm API.

[POST] /echo/

/echo/ Request example

# You can also use wget
curl -X POST https://api.testnet.paradigm.trade/v1/echo/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access-key>'

const inputBody = `{"message": "string"}`;
const headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <access-key>'
};

fetch('https://api.testnet.paradigm.trade/v1/echo/',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

# built ins
import base64
import hmac
import time
from urllib.parse import urljoin
import json

# installed
import requests


access_key = '<access-key>'
secret_key = '<secret-key>'

signing_key = base64.b64decode(secret_key)

print('Paradigm Account Access Key: {}'.format(access_key))
print('Paradigm Account Secret Key: {}'.format(signing_key))

# Request Body

host = 'https://api.testnet.paradigm.trade'

# POST /echo/
method = 'POST'
path = '/v1/echo/'

body = b''

payload = {
            "message": "this is a test echo message"
            }

json_payload = json.dumps(payload).encode('utf-8')

message = method.encode('utf-8') + b'\n'
message += path.encode('utf-8') + b'\n'
message += json_payload

timestamp = str(int(time.time() * 1000))
message = timestamp.encode('utf-8') + b'\n' + message
digest = hmac.digest(signing_key, message, 'sha256')
signature = base64.b64encode(digest)


headers = {
            'Paradigm-API-Timestamp': timestamp,
            'Paradigm-API-Signature': signature,
            'Authorization': f'Bearer {access_key}'
            }

# Send request
response = requests.post(urljoin(host, path),
                         headers=headers,
                         json=payload)

print(response.status_code)
print(response.text)

package main

import (
       "bytes"
       "net/https"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Authorization": []string{"Bearer <acces-key>"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := https.NewRequest("POST", "https://api.testnet.paradigm.trade/v1/echo/", data)
    req.Header = headers

    client := &https.Client{}
    resp, err := client.Do(req)
    // ...
}

/echo/ Response example

{
  "message": "this is a test echo message"
}

A [POST] /echo/ request returns the message specified in the request.

It is designed to allow users to test their authentication as well as connection to Paradigm's API.

Parameters

Response Schema

Status Code 200

Shared - WebSocket Notification Channels

market_maker_protection

An example of MMP being triggered

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params": {
    "channel": "market_maker_protection",
    "data": {
      "kind": "TRIGGERED"
    }
}
}

An update is sent to the market_maker_protection WebSocket Notification Channel when MMP has been triggered. There is no message published when it has been reset by the user or the system.

You must subscribe to this channel using the Connection URL with the Version and Product URL suffix of the respective products below. For example: wss://ws.api.testnet.paradigm.trade/v1/grfq.

If MMP is triggered from the DRFQ product, you will be notified on the market_maker_protection channel even if you subscribed using the GRFQ Version and Product URL.

The response "params" data object has the following members:

DRFQv2 - API Workflows

In our test environment, Paradigm runs "Auto Market Makers". These desks, when included as counterparties in RFQs, will return + update prices and you are able to cross. This allows RFQ Creators to experience the end to end workflow.

Their desk names are "DSK2", "DSK3", "DSK4", "DSK5", and "MT2". They are a part of the LP counterparty list returned from [GET] /counterparties.

DRFQv2: High Level

RFQ Creators are referred to as Taker's and receivers of RFQs are referred to as Maker's throughout the documentation.

DRFQv2 is centred around the concepts of "RFQs", "Orders" and "Trades":

• RFQs are created by a single desk, the Taker, and are composed of one or more legs with attributes defined by the creator.
• Makers, who are included as counterparties in the RFQ, are able to submit Orders with leg pricing.
• Takers are able to submit an order with a LIMIT price to cross an existing Maker order.
• Trades occur when a Taker submits a crossing Order and the trade is sent to the underlying settlement venue for clearing.

At a high level, the DRFQv2 workflow is:

1. Taker creates an RFQ and chooses which counterparties to send it too.
2. Maker(s) submits an order to the RFQ.
3. Taker receives the order(s).
4. Taker submits an order with a crossing price and the trade is sent for clearing on the underlying settlement venue.
5. Taker & Maker receive confirmation that the trade has been successfully cleared or rejected at clearing by the underlying settlement venue.

Notes:

• Users who create the RFQ are regarded as the Taker in the trade by Paradigm and the underlying settlement venue.
• RFQ Markets have "Price" then "Time" matching prioritization. Meaning two Orders with the same price, but different created_at time attributes will result in the Order with the earlier created_at attribute having priority.
• Paradigm expires RFQs which do not trade after 5 minutes from creation.

Key DRFQv2 Concepts

In DRFQv2,

• Specific counterparties must be selected by the Taker to participate in the RFQ.
• There are NO partial fills. Makers must submit orders with corresponding order sizes that match the RFQ's quantity attribute.
• There is NO concept of a Order Book or a public auction. Only the RFQ creator is able to see all of the Makers' returned orders.
• Takers can choose to create an RFQ on a disclosed or an anonymous basis.
• Makers can NOT choose to submit Orders on an anonymous basis.
• It is possible for a Trade to be rejected at clearing by the underlying settlement venue.

DRFQv2: Taker's Perspective

1. Taker creates an RFQ using [POST] /rfqs. You can pull available instruments from [GET] /instruments and counterparties from [GET] /counterparties.
2. Taker is able to cancel an RFQ if they wish to do so with [DELETE] /rfqs/{rfq_id}.
3. Maker, who is a requested counterparty to the RFQ, and is notified over the rfqs JSON-RPCoverWebSockets Notification channel, is then able to submit an order to the RFQ.
4. Taker, who will be notified of RFQ Orders on the rfq_orders JSON-RPCoverWebSockets Notification channel, is able to attempt to cross by submiting an order using [POST] /orders.
5. Taker will receive updates about the state of their order via the orders JSON-RPCoverWebSockets Notification channel.
6. Taker will receive clearing finality via the trades JSON-RPCoverWebSockets Notification channel where the result can either be success or rejection.

DRFQv2: Maker's Perspective

1. Taker will create an RFQ and the Maker will be notified on the rfqs JSON-RPCoverWebSockets Notification channel.
2. Maker is able to create an order using [POST] /orders.
3. Maker is able to cancel an existing order with [DELETE] /orders or [DELETE] /orders/{order_id}.
4. Taker submits a crossing Order that matches with the Maker's existing order.
5. Maker will receive updates about the state of their order via the orders JSON-RPCoverWebSockets Notification channel.
6. Maker will receive clearing finality via the trades JSON-RPCoverWebSockets Notification channel where the result can either be success or rejection.

DRFQv2: Maker managing Orders

• Each RFQ has a side_layering_limit attribute which communicates to Makers how many orders per side they are able to have with a state == OPEN at any one time. By default, and Takers are not able to configure this, all RFQs for the moment will have a side_layering_limit == 1. Therefore, Makers are only able to have 1x state == OPEN order per side per RFQ at any point in time.
• Users are able to create Orders via [POST] /orders.
• Users are able to replace existing Orders via [PUT] /orders/{order_id}.
• Users are able to cancel an Order via [DELETE] /orders/{order_id}.
• Users are able to cancel all Orders via [DELETE] /orders.
• Creating and replacing Orders will always return with a state == PENDING in response to the RESToverHTTP request. This indicates the Order is being processed by the matching engine. The Order only becomes actionable by any user when it's state value changes to OPEN. This is communicated via the orders JSON-RPCoverWebSockets Notification channel.
• Replacing an Order is an atomic Cancel & Create request in the system. This means the original Order will lose it's time priority.

DRFQv2: Taker managing an RFQ's Orders

As a Taker, the desk who has created the RFQ, you will receive Orders from the Makers associated with the RFQ.

This pattern describes how as a Taker to build/store/manage Orders from Makers in relation to your RFQ:

1. Subscribe to the rfq_orders JSON-RPCoverWebSockets WebSockets Notifications channel. Store all of the received events.
2. Request the [GET] /rfqs/{rfq_id}/orders endpoint for the specific RFQ to return all OPEN associated Orders.
3. Apply the received events for the associated {rfq_id} to associated group of Orders from the previous step.
4. From the rfq_orders JSON-RPCoverWebSockets WebSockets Notifications channel, when you receive an event == ADDED, add this order to your storage of RFQ Orders.
5. From the rfq_orders JSON-RPCoverWebSockets WebSockets Notifications channel, when you receive an event == REMOVED, add this order to your storage of RFQ Orders.

Updates about an RFQ's Orders are communicated via the rfq_orders JSON-RPCoverWebSockets WebSockets Notifications channel. They are communicated in a manner most similar to that of an Order Book with a depth of L3. As such, you will find your system adding and removing specific associated orders. At the present moment, partial fills are not possible and your system will not receive any update messages.

DRFQv2: Consequences of a Trade Rejection

All trades on Paradigm are submitted as "Block Trades" to the underlying settlement venue. The two key characteristics of "Block Trades" are atomicity of clearing and either complete success or rejection at clearing. As such, when Paradigm submits a "Block Trade" to an underlying settlement venue, all legs must successfully clear or the entire "Block Trade" is rejected.

With this being said, when two orders cross on Paradigm, Paradigm submits a "Block Trade" to the underlying settlement venue for clearing. Two orders crossing in DRFQv2 will result in each Orders state == CLOSED and a Trade object with the state == PENDING_SETTLEMENT. If the trade successfully clears, both the Taker and the Maker will receive a Trade message with the state == FILLED, if not, state == REJECTED.

In the event of a successful trade, the positions will appear in your underlying settlement account. In the event of a rejected trade, the positions will NOT appear in your underlying settlement account.

DRFQv2: Enums & Explanations

There are six resources present through the DRFQv2 API. They are the Instrument, RFQ, Order, RFQ Orders, Trade, and Trade Tape resources.

Users are able to engage with Paradigm via the RESToverHTTP and JSON-RPCoverWebSockets interfaces.

Resources have a state attribute which denotes the status or availability of the object.

The JSON-RPCoverWebSockets interface publishes messages which include an event key to help communicate what update the message is referring too.

DRFQv2: Instrument

This information is available from the RESToverHTTP inferface, but not the JSON-RPCoverWebSockets interface.

Valid state values include ACTIVE, EXPIRED.

There are no valid event values as there is no corresponding WebSockets Notifications channel.

Instrument objects with the following state values, mean the following things to users:

• An Instrument is instantiated as ACTIVE when made available to trade by Paradigm.
• An Instrument becomes EXPIRED when it reaches settlement or is no longer available to trade upon Paradigm.

The Instrument state enums can only transition from ACTIVE -> EXPIRED.

DRFQv2: RFQ

This information is available from both the RESToverHTTP and the JSON-RPCoverWebSockets interfaces.

Valid state values include OPEN, CLOSED.

Valid event values include ADDED, REMOVED.

RFQ objects with the following state values, mean the following things to users:

• An RFQ is instantiated as OPEN when it is available to be actioned by users.
• An RFQ becomes CLOSED when it is no longer actionable by any user.

Published via the rfqs JSON-RPCoverWebSockets notifications channel, event values mean the following to users:

• ADDED indicates a new RFQ is available to be actioned.
• REMOVED indicates an existing RFQ is no longer available to be actioned.

DRFQv2: Order

This information is available from both the RESToverHTTP and the JSON-RPCoverWebSockets interfaces.

Users are strongly encouraged to use the quantity, pending_fill_quantity, canceled_quantity, filled_quantity attributes of an Order to be certain of the value at risk.

Valid state values include PENDING, OPEN, CLOSED.

Valid event values include NEW, CANCELED, PENDING_FILL, FILLED.

Order objects with the following state values, mean the following things to users:

• An Order is instantiated as PENDING when it is being processed by the Paradigm matching engine.
• An Order becomes OPEN when it is available to be actioned by users.
• An Order becomes CLOSED when it is no longer actionable by any user.

Published via the orders JSON-RPCoverWebSockets notifications channel, event values mean the following to users:

• NEW indicates a new order is available to be actioned by the user.
• CANCELED indicates an existing order has been canceled by the user or is apart of a trade rejection.
• PENDING_FILL indicates an order is in the process of being cleared as apart of a trade by the underlying settlement venue.
• FILLED indicates an order's quantity has been completed filled and there is no more available amount to trade.

DRFQv2: RFQ Orders

This information is available from both the RESToverHTTP and the JSON-RPCoverWebSockets interfaces.

There are no valid state values as the RFQ Orders resource solely communicates actionable Maker Orders to the Taker.

Valid event values include ADDED, REMOVED, UPDATED.

Published via the rfq_orders JSON-RPCoverWebSockets notifications channel, event values mean the following to users:

• ADDED indicates a new Order upon an RFQ is available to be actioned.
• REMOVED indicates an existing Order upon an RFQ is no longer available to be actioned.
• UPDATED indicates an existing Order upon an RFQ has had an attribute updated.

DRFQv2: Trade

This information is available from both the RESToverHTTP and the JSON-RPCoverWebSockets interfaces.

Valid state values include PENDING_SETTLEMENT, FILLED, REJECTED.

Valid event values include PENDING_SETTLEMENT, FILLED, REJECTED.

Trade objects with the following state values, mean the following things to users:

• A Trade is instantiated as PENDING_SETTLEMENT when it is being cleared by the underlying settlement venue.
• A Trade becomes as FILLED when it is has reached settlement finality and has been successfully cleared by underlying settlement venue.
• A Trade becomes REJECTED when it is has reached settlement finality and has been rejected at clearing by underlying settlement venue.

Published via the trades JSON-RPCoverWebSockets notifications channel, event values mean the following to users:

• PENDING_SETTLEMENT indicates a trade is being cleared by the underlying settlement venue.
• FILLED indicates a trade has reached settlement finality and has been successfully cleared by the underlying settlement venue.
• REJECTED indicates a trade has reached settlement finality and has been rejected at clearing by the underlying settlement venue.

DRFQv2: Trade Tape

This information is available from both the RESToverHTTP and the JSON-RPCoverWebSockets interfaces.

Valid state values include FILLED.

Valid event values include FILLED.

Trade Tape objects with the following state values, mean the following things to users:

• A Trade Tape is instantiated as FILLED given it has reached settlement finality and been successfully cleared by the underlying settlement venue.

Published via the trade_tape JSON-RPCoverWebSockets notifications channel, event values mean the following to users:

• FILLED indicates a trade has reached settlement finality and been successfully cleared by the underlying settlement venue.

DRFQv2: Differences to DRFQv1

DRFQv1 was released at the beginnning of 2021 when both Paradigm & crypto were in very different places to where they are today. DRFQv1 was built in response to direct user feedback and was an iteration upon our first product; "Chat". "Chat" required users to bilaterally negotiate with multiple counterparties the same structure for each trade. As such, DRFQv1 (or MDRFQ), was created to solve this user problem.

With time, DRFQv1 has becoming increasingly slow, but has also become increasingly challenging to extend & to deliver the functionality requested by users today. As such, DRFQv2 has been created to address the existing performance & feature challenges of DRFQv1, but to also enable rapid solutions to future user requests.

DRFQv2 includes many of the elements of other Paradigm products, such as FSPD & GRFQ, that users have expressed positive feedback about. The intentions of DRFQv2 are threefold:

1. To remedy the decreasing performance of DRFQv1.
2. To include product functionality missing, but frequently requested & required by users.
3. To provide an experience more akin to that of FSPDs & GRFQ + crypto exchanges. The intention is to reduce the amount of integration work required for users stemming from critically different workflows and patterns between both Paradigm products as well as the broader space.

With that said, the DRFQv2 API workflow is incredibly similar to that of what users are used to interacting with in FSPDs & GRFQ and also crypto exchanges.

Some small notes:

• CME is only available for the DRFQv1 API and NOT the DRFQv2 API. CME is not available as a venue yet in the Unified Markets interface.
• It is no longer possible to customize the expiration period of RFQs as you could in DRFQv1. They are now set by default to be approximately five minutes.
• The DRFQv1 [POST] /quote/create expires_in key now only accepts the following values 30, 60, 90.
• RFQs' legs are denominated by a ratio. These values must have a precision or less of 12 values for Options and 17 values for Futures.
• It is no longer possible to create RFQs with a single SELL sided leg. Single-legged RFQs must have a side == BUY.

DRFQv2: DRFQv1 Support

DRFQv1 will continue to be supported for an extended period of time. A deprecation timeline will be communicated and the result of feedback & consensus of users.

Existing users of DRFQv1 will be able to continue until such a time without any disruption or changes required to existing systems.

The core motivations for existing DRFQv1 users to integrate with DRFQv2 are:

• Significantly improved relative performance.
• Access to newly supported Venues and Contract Types.
• Access to new product features and functionality.

If you have any questions, we strongly recommend you reach out to your account manager as we would greatly appreciate any feedback.

DRFQv2 - Code Examples

Reach out if you ever need any help! We are more than happy to help.

You will need to update the provided Code Examples with your own Paradigm Access Key and Secret Key.

You can find all existing examples on our GitHub: https://github.com/tradeparadigm/code-samples

Note: All examples in this section are in Python3.

DRFQv2: JSON-RPCoverWebSockets

DRFQv2: Authentication + Heartbeat + Subscribe to Notification Channel

Authenticate, establish & maintain a heartbeat and subscribe rfqs JSON-RPCoverWebSockets Notification Channel.

DRFQv2: Auto Market Maker

We encourage you to RFQ all counterparties marked as an "LP" from the [GET] /counterparties as this includes all of Paradigm's Auto Market Makers.

The desk names of some Auto Market Makers are "DSK2", "DSK3", "DSK4", "DSK5", and "MT2" on the Test environment.

To note, this is purely a QA tool and not in any way to be used as apart of a trading system.

You can download the Auto Market Maker from here.

DRFQv2: Auto Market Taker

The Auto Market Taker will create random RFQ structures and cross them. You will need to update the counterparties you wish to RFQ (ie your desk acting as a Maker).

To note, this is purely a QA tool and not in any way to be used as apart of a trading system.

You can download the Auto Market Taker from here.

DRFQv2 - WebSocket Notification Channels

DRFQv2: rfqs

An example, as the RFQ Creator, role == TAKER, when state == OPEN

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"rfqs",
      "data":{
         "account_name":"ParadigmTestNinetyFive",
         "base_currency":"BTC",
         "clearing_currency":"USD",
         "closed_reason":"None",
         "counterparties":[
            "DSK3",
            "DSK2"
         ],
         "created_at":1670473243746.937,
         "description":"Future  16 Dec 22",
         "expires_at":1670473543747.062,
         "id":"r_2IcG1WoqoCCtjA0C0EhJxotCSu2",
         "is_taker_anonymous":true,
         "kind":"FUTURE",
         "label":"None",
         "last_trade":"None",
         "last_updated_at":1670473243747.062,
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "product_code":"CF",
               "quantity":"200000",
               "ratio":"1",
               "side":"BUY"
            }
         ],
         "product_codes":[
            "CF"
         ],
         "quantity":"200000",
         "quote_currency":"USD",
         "role":"TAKER",
         "side_layering_limit":1,
         "state":"OPEN",
         "strategy_code": "FT",
         "strategy_description":"CF_BTC-16DEC22",
         "group_signature":"891e9830b2dcd30747caea878323e30d52356f0c1b50449ccb666e0e530b296a",
         "taker_desk_name":"DSK95",
         "venue":"DBT"
      },
      "event":"ADDED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

An example, as the RFQ Creator, role == TAKER, when state == CLOSED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"rfqs",
      "data":{
         "account_name":"ParadigmTestNinetyFive",
         "base_currency":"BTC",
         "clearing_currency":"USD",
         "closed_reason":"CANCELED_BY_CREATOR",
         "counterparties":[
            "DSK3",
            "DSK2"
         ],
         "created_at":1670473243746.937,
         "description":"Future  16 Dec 22",
         "expires_at":1670473581046.396,
         "id":"r_2IcG1WoqoCCtjA0C0EhJxotCSu2",
         "is_taker_anonymous":true,
         "kind":"FUTURE",
         "label":"None",
         "last_trade":"None",
         "last_updated_at":1670473281046.396,
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "product_code":"CF",
               "quantity":"200000",
               "ratio":"1",
               "side":"BUY"
            }
         ],
         "product_codes":[
            "CF"
         ],
         "quantity":"200000",
         "quote_currency":"USD",
         "role":"TAKER",
         "side_layering_limit":1,
         "state":"CLOSED",
         "strategy_code":"FT",
         "strategy_description":"CF_BTC-16DEC22",
         "group_signature":"891e9830b2dcd30747caea878323e30d52356f0c1b50449ccb666e0e530b296a",
         "taker_desk_name":"DSK95",
         "venue":"DBT"
      },
      "event":"REMOVED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

An example, as an RFQ receiver, role == MAKER, when state == OPEN

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"rfqs",
      "data":{
         "account_name":null,
         "base_currency":"BTC",
         "clearing_currency":"USD",
         "closed_reason":"None",
         "counterparties": [],
         "created_at":1670473348810.261,
         "description":"Future  16 Dec 22",
         "expires_at":1670473648810.403,
         "id":"r_2IcGEiv9eQEA1CU4H1hfe9ZogAJ",
         "is_taker_anonymous":true,
         "kind":"FUTURE",
         "label":"None",
         "last_trade":"None",
         "last_updated_at":1670473348810.403,
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "product_code":"CF",
               "quantity":"200000",
               "ratio":"1",
               "side":"BUY"
            }
         ],
         "product_codes":[
            "CF"
         ],
         "quantity":"200000",
         "quote_currency":"USD",
         "role":"MAKER",
         "side_layering_limit":1,
         "state":"OPEN",
         "strategy_code":"FT",
         "strategy_description":"CF_BTC-16DEC22",
         "group_signature":"891e9830b2dcd30747caea878323e30d52356f0c1b50449ccb666e0e530b296a",
         "taker_desk_name":"None",
         "venue":"DBT"
      },
      "event":"ADDED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

An example, as an RFQ receiver, role == MAKER, when state == CLOSED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"rfqs",
      "data":{
         "account_name":null,
         "base_currency":"BTC",
         "clearing_currency":"USD",
         "closed_reason":"CANCELED_BY_CREATOR",
         "counterparties": [],
         "created_at":1670473348810.261,
         "description":"Future  16 Dec 22",
         "expires_at":1670473663770.951,
         "id":"r_2IcGEiv9eQEA1CU4H1hfe9ZogAJ",
         "is_taker_anonymous":true,
         "kind":"FUTURE",
         "label":"None",
         "last_trade":"None",
         "last_updated_at":1670473363770.951,
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "product_code":"CF",
               "quantity":"200000",
               "ratio":"1",
               "side":"BUY"
            }
         ],
         "product_codes":[
            "CF"
         ],
         "quantity":"200000",
         "quote_currency":"USD",
         "role":"MAKER",
         "side_layering_limit":1,
         "state":"CLOSED",
         "strategy_code":"FT",
         "strategy_description":"CF_BTC-16DEC22",
         "group_signature":"891e9830b2dcd30747caea878323e30d52356f0c1b50449ccb666e0e530b296a",
         "taker_desk_name":"None",
         "venue":"DBT"
      },
      "event":"REMOVED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

All updates relating to RFQs are sent through the rfqs WebSocket Notification channel.

This is a private channel and consumable by only those aparty to the RFQ. Those counterparties include the RFQ's creator as well as the specified counterparties to the RFQ.

Updates received through the rfqs WebSocket Notification channel can include RFQs being created, canceled, expired, filled and traded away.

The availability of an RFQ to be actioned by any user is denoted by the state key of the object. When an RFQ has a state == OPEN, it is actionable by both the RFQ creator and those specified as counterparties. When an RFQ has a state == CLOSED it is no longer actionable by either the RFQ creator or the specified counterparties.

Response Schema

DRFQv2: rfq_orders

An example, as the RFQ Creator, RFQ role == TAKER, when event == ADDED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"rfq_orders",
      "data":{
         "id":"o_2IcGsBLQIwl09jdflpb1iRnUT9B",
         "price":"16795",
         "quantity":"200000",
         "desk":"DSK94",
         "rfq_id":"r_2IcGerUAbHtEyTxzCiupnEgxk9Z",
         "side":"SELL"
      },
      "event":"ADDED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

An example, as the RFQ Creator, RFQ role == TAKER, when event == REMOVED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"rfq_orders",
      "data":{
         "id":"o_2IcGsBLQIwl09jdflpb1iRnUT9B",
         "price":"16795",
         "quantity":"200000",
         "desk":"DSK94",
         "rfq_id":"r_2IcGerUAbHtEyTxzCiupnEgxk9Z",
         "side":"SELL"
      },
      "event":"REMOVED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

All updates relating to an RFQ's Orders are sent through the rfq_orders WebSocket Notifications channel.

This is a private channel and only available to the creator of the RFQ who has the role == TAKER in the RFQ.

Updates received through the rfq_orders WebSocket Notification channel represent events relating to specific related orders. In terms of thinking, it's extremely similar to processing event updates to that of an Order Book with an L3 depth.

• An RFQ Orders event == ADDED message indicates that an order is available and actionable by both the creater & the creator of the RFQ.
• An RFQ Orders event == REMOVED message indicates that an order is no longer available and actionable by any user.

Response Schema

DRFQv2: orders

An example, when Order has a state == OPEN

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"orders",
      "data":{
         "account_name":"ParadigmTestNinetyFour",
         "canceled_quantity":"0",
         "created_at":1670539033867.91,
         "filled_quantity":"0",
         "id":"o_2IePNBE9NPXk0xJnPmUNZSrri2G",
         "label":"just for me",
         "last_updated_at":1670539033868.4849,
         "pending_fill_quantity":"0",
         "price":"16800",
         "quantity":"200000",
         "rfq_id":"r_2IePMAohwEdvzcTT2SchQWSC7Wf",
         "role":"MAKER",
         "side":"SELL",
         "state":"OPEN",
         "time_in_force":"GOOD_TILL_CANCELED",
         "type":"LIMIT",
         "venue":"DBT",
         "legs": [
            {
               "instrument_id": 12312312312,
               "price": "16800"
            }
         ]
      },
      "event":"NEW",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

An example, when Order has a state == CLOSED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"orders",
      "data":{
         "account_name":"ParadigmTestNinetyFive",
         "canceled_quantity":"0",
         "created_at":1670473741899.189,
         "filled_quantity":"0",
         "id":"o_2IcH26wODa1OAPgyCnwcFrJ6EGK",
         "label":"just for me",
         "last_updated_at":1670473741966.041,
         "pending_fill_quantity":"200000",
         "price":"16795",
         "quantity":"200000",
         "rfq_id":"r_2IcGerUAbHtEyTxzCiupnEgxk9Z",
         "role":"TAKER",
         "side":"BUY",
         "state":"CLOSED",
         "time_in_force":"FILL_OR_KILL",
         "type":"LIMIT",
         "venue":"DBT",
         "legs": []
      },
      "event":"PENDING_FILL",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

All updates relating to a desks' Orders are sent through the orders WebSocket Notifications channel.

This is a private channel and provides updates solely about the desks' Orders.

• An Orders state == OPEN message indicates that the order is actionable by any user.
• An Orders state == CLOSED indicates that the order is no longer actionable by any user.

When the RFQ creator, role == TAKER, submits an order, the first published orders WebSocket Notification channel message will always indicate state == CLOSED due to the Order either successfully crossing or being canceled due it's time_in_force attribute being FILL_OR_KILL.

Response Schema

DRFQv2: trades

An example, when a trade has a state == PENDING_SETTLEMENT

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"trades",
      "data":{
         "id":"bt_2IeNvhjvSS7NanFGaalF2yZWSXm",
         "exec_id":"None",
         "order_id":"o_2IeNvhjR6zW0iCrkh6Q3T5lOyTn",
         "rfq_id":"r_2IeNtwelJ18OKY88ltCjPFg4NVb",
         "venue":"DBT",
         "kind":"FUTURE",
         "state":"PENDING_SETTLEMENT",
         "role":"TAKER",
         "executed_at":1670538321612.0579,
         "filled_at":"None",
         "side":"BUY",
         "price":"17204",
         "quantity":"200000",
         "filled_quantity":"0",
         "rejected_quantity":"0",
         "rejected_party":"None",
         "rejected_reason":"None",
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "price":"17204",
               "product_code":"CF",
               "quantity":"200000",
               "ratio":"1",
               "side":"BUY",
               "venue_trade_id":"None",
               "fee_quantity":"None",
               "fee_currency":"BTC"
            }
         ],
         "strategy_description":"CF_BTC-16DEC22",
         "description":"Future  16 Dec 22",
         "quote_currency":"USD",
         "mark_price":"17203.49"
      },
      "event":"PENDING_SETTLEMENT",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

An example, when a trade has a state == FILLED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"trades",
      "data":{
         "id":"bt_2IeNvhjvSS7NanFGaalF2yZWSXm",
         "exec_id":"366192",
         "order_id":"o_2IeNvhjR6zW0iCrkh6Q3T5lOyTn",
         "rfq_id":"r_2IeNtwelJ18OKY88ltCjPFg4NVb",
         "venue":"DBT",
         "kind":"FUTURE",
         "state":"FILLED",
         "role":"TAKER",
         "executed_at":1670538321612.0579,
         "filled_at":1670538322000.0,
         "side":"BUY",
         "price":"17204",
         "quantity":"200000",
         "filled_quantity":"200000",
         "rejected_quantity":"0",
         "rejected_party":"None",
         "rejected_reason":"None",
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "price":"17204",
               "product_code":"CF",
               "quantity":"200000",
               "ratio":"1",
               "side":"BUY",
               "venue_trade_id":"141327736",
               "fee_quantity":"0.0116252",
               "fee_currency":"BTC"
            }
         ],
         "strategy_description":"CF_BTC-16DEC22",
         "description":"Future  16 Dec 22",
         "quote_currency":"USD",
         "mark_price":"17203.49"
      },
      "event":"FILLED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

An example, when a trade has a state == REJECTED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"trades",
      "data":{
         "id":"bt_2IeOL5d0Bvh32XgJQMFSu7XMyPc",
         "exec_id":"None",
         "order_id":"o_2IeOL5cYl8HoJHBIAlb1mLWbo13",
         "rfq_id":"r_2IeOIha69NSwfkGG1qjJd7U3jEF",
         "venue":"DBT",
         "kind":"FUTURE",
         "state":"REJECTED",
         "role":"TAKER",
         "executed_at":1670538523874.681,
         "filled_at":"None",
         "side":"BUY",
         "price":"16800",
         "quantity":"200000",
         "filled_quantity":"0",
         "rejected_quantity":"200000",
         "rejected_party":"None",
         "rejected_reason":"Deribit error: Price for trade is lower than min sell price. Your Ask for Future 16 Dec 22 was CANCELED",
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "price":"16800",
               "product_code":"CF",
               "quantity":"200000",
               "ratio":"1",
               "side":"BUY",
               "venue_trade_id":"None",
               "fee_quantity":"None",
               "fee_currency":"BTC"
            }
         ],
         "strategy_description":"CF_BTC-16DEC22",
         "description":"Future  16 Dec 22",
         "quote_currency":"USD",
         "mark_price":"17189.22"
      },
      "event":"REJECTED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

All updates relating to a desks' Trades are sent through the trades WebSocket Notifications channel.

This is a private channel and provides updates solely about the desks' Trades.

• A Trades state == PENDING_SETTLEMENT message indicates that a desks' order has been successfully matched and is being cleared by the underlying settlement venue.
• A Trades state == FILLED message indicates that the trade has reached finality and be successfully cleared on the underlying settlement venue.
• A Trades state == REJECTED message indicates that the trade has reached finality and has been rejected at clearing by the underlying settlement venue.

Response Schema

DRFQv2: trade_tape

An example, when a trade has the state == FILLED

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "channel":"trade_tape",
      "data":{
         "id":"bt_2IeNvhjvSS7NanFGaalF2yZWSXm",
         "rfq_id":"r_2IeNtwelJ18OKY88ltCjPFg4NVb",
         "venue":"DBT",
         "kind":"FUTURE",
         "state":"FILLED",
         "executed_at":1670538321612.0579,
         "filled_at":1670538322000.0,
         "side":"SELL",
         "price":"17204",
         "quantity":"200000",
         "legs":[
            {
               "instrument_id":184255,
               "instrument_name":"BTC-16DEC22",
               "ratio":"1",
               "side":"BUY",
               "price":"17204",
               "product_code":"CF",
               "quantity":"200000"
            }
         ],
         "strategy_description":"CF_BTC-16DEC22",
         "description":"Future  16 Dec 22",
         "quote_currency":"USD",
         "mark_price":"17203.49"
      },
      "event":"FILLED",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

All successfully cleared Trades on Paradigm are sent through the trade_tape WebSocket Notifications channel.

This is a public channel and consumable by all.

As such, no identifiable information is apart of any messages and only successfully cleared trades upon the underlying settlement venue are published.

Response Schema

DRFQv2: bbo.{rfq_id}

An example, of an update message

{
   "jsonrpc":"2.0",
   "method":"subscription",
   "params":{
      "data":{
         "rfq_id":"r_2LA8TjDOjWAHtRJ7CeLWzQXf4Ah",
         "min_price":"23658.58",
         "max_price":"24379.14",
         "mark_price":"24019.18",
         "best_bid_price":"24017.50",
         "best_ask_price":"24018.00",
         "best_bid_amount":"342090.0",
         "best_ask_amount":"42500.0",
         "created_at":1675302554270,
         "legs":[
            {
               "best_bid_price":"24017.50",
               "best_ask_price":"24018.00",
               "best_bid_amount":"342090.0",
               "best_ask_amount":"42500.0",
               "instrument_id":26707,
               "instrument_name":"BTC-PERPETUAL",
               "mark_price":"24019.18"
            }
         ]
      },
      "channel":"bbo",
      "meta": {
        "seq_group": 1692463499,
        "seq_num": 1027
      }
   }
}

All updates relating to an RFQ's composite instrument & structure market data are sent via the bbo.{rfq_id} WebSocket Notification Channel.

This is a public channel and consumable by all.

This channel publishes real-time updates of the underlying market data from the composite instruments' settlement venue.

Parameters

Response Schema

Message Structure with Sequence Numbers

WebSocket messages now include an additional meta field that contains the following properties:

Here's an example of a WebSocket message with sequence numbers:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "channel": "rfq",
    "data": {
    },
    "meta": {
      "seq_group": 1692463499,
      "seq_num": 1027
    }
  }
}

Handling Sequence Numbers

Clients should monitor the sequence numbers of the incoming messages to ensure they have not missed any messages. If a client detects a gap in the sequence numbers, it may have missed one or more messages and should take appropriate action, such as refreshing data from REST.

Sequences increase monotonically within the context of a sequence group. Sequences are only relevant within a sequence group, which represents a subscribed channel. Sequences may be re-used between sequence groups.

While messages are sent ordered according to their sequences, sequences are not guaranteed not to repeat.

DRFQv2 - REST Endpoints

DRFQv2: [GET] /instruments

/instruments Request example

# You can also use wget
curl -X GET https://api.testnet.paradigm.trade/v2/drfq/instruments \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ACCESS_KEY'

const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer ACCESS_KEY'
};

fetch('https://api.testnet.paradigm.trade/v2/drfq/instruments',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

# built ins
import base64
import hmac
import time

# installed
import requests

access_key = '<access-key>'
secret_key = b'<secret-key>'


def sign_request(secret_key, method, path, body):
    signing_key = base64.b64decode(secret_key)
    timestamp = str(int(time.time() * 1000)).encode('utf-8')
    message = b'\n'.join([timestamp, method.upper(), path, body])
    digest = hmac.digest(signing_key, message, 'sha256')
    signature = base64.b64encode(digest)
    return timestamp, signature


# Request Host
host = 'https://api.testnet.paradigm.trade'

# GET /v2/drfq/instruments
method = 'GET'
path = '/v2/drfq/instruments?venue=DBT&kind=FUTURE&base_currency=BTC'

payload = ''

timestamp, signature = sign_request(secret_key=secret_key,
                                    method=method.encode('utf-8'),
                                    path=path.encode('utf-8'),
                                    body=payload.encode('utf-8'),
                                    )

headers = {
          'Paradigm-API-Timestamp': timestamp,
          'Paradigm-API-Signature': signature,
          'Authorization': f'Bearer {access_key}'
           }

# Send request
response = requests.get(
    host+path,
    headers=headers
    )

print(response.status_code)
print(response.text)

package main

import (
       "bytes"
       "net/https"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer ACCESS_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := https.NewRequest("GET", "https://api.testnet.paradigm.trade/v2/drfq/instruments", data)
    req.Header = headers

    client := &https.Client{}
    resp, err := client.Do(req)
    // ...
}

A [GET] /instruments request returns all instruments that are or were tradeable on Paradigm.

• When state == ACTIVE users are able to create markets using the instrument.
• When state == EXPIRED users are NOT able to create markets using the instrument.

To return complete results, users must paginate by providing the response's next key value for the cursor query string parameter in the subsequent request.

Parameters

/instruments Response example

{
  "count":2424,
  "next":"cD0xODUyNzc=",
  "results":[
    {
      "id": 3614,
      "name": "ETH-7APR23",
      "created_at": 1679644802000,
      "expires_at": 1680854400000,
      "kind": "FUTURE",
      "venue": "DBT",
      "option_kind": null,
      "strike": null,
      "margin_kind": "INVERSE",
      "base_currency": "ETH",
      "quote_currency": "USD",
      "clearing_currency": "USD",
      "settlement_currency": "ETH",
      "mark_price": "1714.76",
      "min_block_size": "100000",
      "min_order_size_increment": "1",
      "min_tick_size": "0.01",
      "product_code": "AZ",
      "venue_instrument_name": "ETH-7APR23",
      "state": "ACTIVE",
      "greeks": null
    },
    {
      "id": 3613,
      "name": "BTC-7APR23",
      "created_at": 1679644802000,
      "expires_at": 1680854400000,
      "kind": "FUTURE",
      "venue": "DBT",
      "option_kind": null,
      "strike": null,
      "margin_kind": "INVERSE",
      "base_currency": "BTC",
      "quote_currency": "USD",
      "clearing_currency": "USD",
      "settlement_currency": "BTC",
      "mark_price": "27091.94",
      "min_block_size": "200000",
      "min_order_size_increment": "10",
      "min_tick_size": "0.01",
      "product_code": "CF",
      "venue_instrument_name": "BTC-7APR23",
      "state": "ACTIVE",
      "greeks": null
    },
    {
      "id": 3358,
      "name": "ETH-29DEC23-9000-P",
      "created_at": 1679101560000,
      "expires_at": 1703836800000,
      "kind": "OPTION",
      "venue": "DBT",
      "option_kind": "PUT",
      "strike": "9000",
      "margin_kind": "INVERSE",
      "base_currency": "ETH",
      "quote_currency": "ETH",
      "clearing_currency": "ETH",
      "settlement_currency": "ETH",
      "mark_price": "4.1669",
      "min_block_size": "250",
      "min_order_size_increment": "1",
      "min_tick_size": "0.0001",
      "product_code": "EH",
      "venue_instrument_name": "ETH-29DEC23-9000-P",
      "state": "ACTIVE",
      "greeks": {
        "delta": "-0.99534",
        "gamma": "1e-05",
        "mark_price": "4.1669",
        "theta": "-0.02436",
        "vega": "0.206",
        "last_updated_at": 1679944965844
      }
    },
    {
      "id": 3357,
      "name": "ETH-29DEC23-9000-C",
      "created_at": 1679101560000,
      "expires_at": 1703836800000,
      "kind": "OPTION",
      "venue": "DBT",
      "option_kind": "CALL",
      "strike": "9000",
      "margin_kind": "INVERSE",
      "base_currency": "ETH",
      "quote_currency": "ETH",
      "clearing_currency": "ETH",
      "settlement_currency": "ETH",
      "mark_price": "0.0007",
      "min_block_size": "250",
      "min_order_size_increment": "1",
      "min_tick_size": "0.0001",
      "product_code": "EH",
      "venue_instrument_name": "ETH-29DEC23-9000-C",
      "state": "ACTIVE",
      "greeks": {
        "delta": "0.00466",
        "gamma": "1e-05",
        "mark_price": "0.0007",
        "theta": "-0.02436",
        "vega": "0.20599",
        "last_updated_at": 1679944965848
      }
    }
  ]
}

Response Schema

Status Code: 200

Error Codes

DRFQv2: [GET] /instruments/{instrument_id}

/instruments/{instrument_id} Request example

# You can also use wget
curl -X GET https://api.testnet.paradigm.trade/v2/drfq/instruments/123 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ACCESS_KEY'

const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer ACCESS_KEY'
};

fetch('https://api.testnet.paradigm.trade/v2/drfq/instruments/123',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

# built ins
import base64
import hmac
import time

# installed
import requests

access_key = '<access-key>'
secret_key = b'<secret-key>'


def sign_request(secret_key, method, path, body):
    signing_key = base64.b64decode(secret_key)
    timestamp = str(int(time.time() * 1000)).encode('utf-8')
    message = b'\n'.join([timestamp, method.upper(), path, body])
    digest = hmac.digest(signing_key, message, 'sha256')
    signature = base64.b64encode(digest)
    return timestamp, signature


# Request Host
host = 'https://api.testnet.paradigm.trade'

# GET /v2/drfq/instruments/{instrument_id}
method = 'GET'
path = '/v2/drfq/instruments/123'

payload = ''

timestamp, signature = sign_request(secret_key=secret_key,
                                    method=method.encode('utf-8'),
                                    path=path.encode('utf-8'),
                                    body=payload.encode('utf-8'),
                                    )

headers = {
          'Paradigm-API-Timestamp': timestamp,
          'Paradigm-API-Signature': signature,
          'Authorization': f'Bearer {access_key}'
           }

# Send request
response = requests.get(
    host+path,
    headers=headers
    )

print(response.status_code)
print(response.text)