Request format

When interacting with Deriv’s WebSocket API, all requests must be sent as JSON in text frames, with one request per frame.

To help you manage the flow of requests and responses, each API call follows a standardized structure. This structure aids in caching, validation, and synchronizing requests and responses, making your WebSocket connection smoother and more efficient.

API call method name

Every request must include a method name field, which serves as a unique identifier. Typically, this is set to 1, but it can sometimes be a string.

🚧

The method name is always required, as it defines the specific data you’ll receive from the WebSocket server.

Required fields

Each request contains required fields and may also have optional fields. For example, a Residence List call returns a list of countries and their two-letter codes, suitable for populating an account opening form.

Example request data for residence list:

{
  "residence_list": 1, // Method Name
  "passthrough": {},   // Optional
  "req_id": 2          // Optional
}

The residence_list field is the method name and is mandatory. Other fields like passthrough and req_id are optional and depend on your specific needs.

Optional fields

API calls often include optional fields that you can choose to use or ignore:

1. passthrough: This field returns any data you provide within the response object. It’s useful for maintaining state across requests and responses.
2. req_id: This field allows you to tag requests, making it easier to map them to responses.

🚧

For more details on optional fields for each API call, visit the API Explorer.

Response data

Responses from the API will include a field named after the method name you used in your request. This field contains the actual data.

Example response for residence list:

{
  "echo_req": {
    "req_id": 1,
    "residence_list": 1
  },
  "msg_type": "residence_list",
  "req_id": 1,
  "residence_list": [
    {
      "identity": {
        "services": {
          "idv": {
            "documents_supported": {},
            "has_visual_sample": 0,
            "is_country_supported": 0
          },
          "onfido": {
            "documents_supported": {
              "driving_licence": {
                "display_name": "Driving Licence"
              }
            },
            "is_country_supported": 0
          }
        }
      },
      "phone_idd": "35818",
      "text": "Aland Islands",
      "value": "ax"
    },
    {
      "identity": {
        "services": {
          "idv": {
            "documents_supported": {},
            "has_visual_sample": 0,
            "is_country_supported": 0
          },
          "onfido": {
            "documents_supported": {
              "driving_licence": {
                "display_name": "Driving Licence"
              },
              "national_identity_card": {
                "display_name": "National Identity Card"
              },
              "passport": {
                "display_name": "Passport"
              }
            },
            "is_country_supported": 1
          }
        }
      },
      "phone_idd": "355",
      "text": "Albania",
      "tin_format": [
        "^[A-Ta-t0-9]\\d{8}[A-Wa-w]$"
      ],
      "value": "al"
    }
  ]
}

The residence_list field in this response contains the requested data. For the complete response, check the API Explorer.

Response fields

1. echo_req: This field returns the exact request data that was sent to the server, useful for verification and debugging.
2. msg_type: Identifies the type of message received from the server, which is helpful for managing responses in your WebSocket onmessage event handler.
3. req_id: An optional field used for validation, synchronization, or caching.

JavaScript example for handling responses:

socket.onmessage = (event) => {
  const receivedMessage = JSON.parse(event.data);

  switch (receivedMessage.msg_type) {
    case "residence_list":
      console.log("The residence list is:", receivedMessage.residence_list);
      break;
    case "other_request_identifier":
      console.log("The response:", receivedMessage.some_other_request_identifier);
      break;
    default:
      console.log("Received message:", receivedMessage);
      break;
  }
};

📘

The msg_type field is always present in the response data, helping you manage the incoming messages efficiently.