Deribit Subscription Management API

openapi: 3.2.0
info:
  title: Deribit Subscription Management API
  version: 2.1.1
  description: Subscription works as [notifications](#notifications), so users will automatically (after subscribing) receive messages from the server. Overview for each channel response format is described in [subscriptions](#subscriptions) section.
servers:
- url: https://test.deribit.com/api/v2
tags:
- name: Subscription Management
  description: Subscription works as [notifications](#notifications), so users will automatically (after subscribing) receive messages from the server. Overview for each channel response format is described in [subscriptions](#subscriptions) section.
paths:
  /public/subscribe:
    get:
      tags:
      - Subscription Management
      parameters:
      - name: channels
        in: query
        schema:
          type: array
          items:
            type: string
            example: deribit_price_index.btc_usd
          example:
          - deribit_price_index.btc_usd
        required: true
        description: A list of channels to subscribe to. See [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications) for all available channels.
        style: form
        explode: true
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubscribeResponse'
        '401':
          $ref: '#/components/responses/ErrorMessageResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 3600
                  method: public/subscribe
                  params:
                    channels:
                    - deribit_price_index.btc_usd
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Subscribe to one or more channels. This is the same method as `/private/subscribe`, but it can only be used for ''public'' channels.


        For a complete list of available subscription channels and their notification formats, see [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications).


        **Note - This method has distinct API rate limiting requirements:** Sustained rate: ~3.3 requests/second. For more information, see [Rate Limits](https://docs.deribit.com/articles/rate-limits).


        **📖 Related Article:** [Market Data Collection Best Practices](https://docs.deribit.com/articles/market-data-collection-best-practices)


        [Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fsubscribe)


        '
      x-mint:
        metadata:
          title: public/subscribe
          og:title: public/subscribe
          keywords:
          - public/subscribe
          - channels
        href: /api-reference/subscription-management/public-subscribe
  /public/unsubscribe:
    get:
      tags:
      - Subscription Management
      parameters:
      - name: channels
        in: query
        schema:
          type: array
          items:
            type: string
            example: deribit_price_index.btc_usd
          example:
          - deribit_price_index.btc_usd
        required: true
        description: A list of channels to unsubscribe from. Only successfully unsubscribed channels will be returned in the result. See [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications) for all available channels.
        style: form
        explode: true
      responses:
        '200':
          $ref: '#/components/responses/Getunsubscribe200response'
        '401':
          $ref: '#/components/responses/ErrorMessageResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 8691
                  method: public/unsubscribe
                  params:
                    channels:
                    - deribit_price_index.btc_usd
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Unsubscribe from one or more channels. The response contains only the channels that were successfully unsubscribed in this request.


        For a complete list of available subscription channels and their notification formats, see [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications).


        **Note:** The `result` field in the response contains only the channels that were successfully processed and unsubscribed from this specific request. It does not include all previously subscribed topics. If a channel in the request is invalid, not subscribed, or fails validation, it will not appear in the result.


        [Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Funsubscribe)


        '
      x-mint:
        metadata:
          title: public/unsubscribe
          og:title: public/unsubscribe
          keywords:
          - public/unsubscribe
          - channels
        href: /api-reference/subscription-management/public-unsubscribe
  /public/unsubscribe_all:
    get:
      tags:
      - Subscription Management
      responses:
        '200':
          $ref: '#/components/responses/OkResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 153
                  method: public/unsubscribe_all
                  params: {}
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Unsubscribe from all the channels subscribed so far. This method takes no parameters.


        [Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Funsubscribe_all)


        '
      x-mint:
        metadata:
          title: public/unsubscribe_all
          og:title: public/unsubscribe_all
          keywords:
          - public/unsubscribe_all
        href: /api-reference/subscription-management/public-unsubscribe_all
  /private/subscribe:
    get:
      tags:
      - Subscription Management
      parameters:
      - name: channels
        in: query
        schema:
          type: array
          items:
            type: string
            example: deribit_price_index.btc_usd
          example:
          - deribit_price_index.btc_usd
        required: true
        description: A list of channels to subscribe to. See [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications) for all available channels.
        style: form
        explode: true
      - name: label
        in: query
        required: false
        schema:
          type: string
          example: TestLabel1
        description: Optional label which will be added to notifications of private channels (max 16 characters).
      responses:
        '200':
          $ref: '#/components/responses/PrivateSubscribeResponse'
        '401':
          $ref: '#/components/responses/ErrorMessageResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 4235
                  method: private/subscribe
                  params:
                    channels:
                    - deribit_price_index.btc_usd
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Subscribe to one or more channels. The name of the channel determines what information will be provided, and in what form.


        For a complete list of available subscription channels and their notification formats, see [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications).


        **Note - This method has distinct API rate limiting requirements:** Sustained rate: ~3.3 requests/second. For more information, see [Rate Limits](https://docs.deribit.com/articles/rate-limits).


        **📖 Related Article:** [Market Data Collection Best Practices](https://docs.deribit.com/articles/market-data-collection-best-practices)


        [Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fsubscribe)


        '
      x-mint:
        metadata:
          title: private/subscribe
          og:title: private/subscribe
          keywords:
          - private/subscribe
          - channels
          - label
        href: /api-reference/subscription-management/private-subscribe
  /private/unsubscribe:
    get:
      tags:
      - Subscription Management
      parameters:
      - name: channels
        in: query
        schema:
          type: array
          items:
            type: string
            example: deribit_price_index.btc_usd
          example:
          - deribit_price_index.btc_usd
        required: true
        description: A list of channels to unsubscribe from. Only successfully unsubscribed channels will be returned in the result. See [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications) for all available channels.
        style: form
        explode: true
      responses:
        '200':
          $ref: '#/components/responses/Getunsubscribe200response'
        '401':
          $ref: '#/components/responses/ErrorMessageResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 3370
                  method: private/unsubscribe
                  params:
                    channels:
                    - deribit_price_index.btc_usd
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Unsubscribe from one or more channels. The response contains only the channels that were successfully unsubscribed in this request.


        For a complete list of available subscription channels and their notification formats, see [Notifications and Subscriptions](https://docs.deribit.com/articles/notifications).


        **Note:** The `result` field in the response contains only the channels that were successfully processed and unsubscribed from this specific request. It does not include all previously subscribed topics. If a channel in the request is invalid, not subscribed, or fails validation, it will not appear in the result.


        [Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Funsubscribe)


        '
      x-mint:
        metadata:
          title: private/unsubscribe
          og:title: private/unsubscribe
          keywords:
          - private/unsubscribe
          - channels
        href: /api-reference/subscription-management/private-unsubscribe
  /private/unsubscribe_all:
    get:
      tags:
      - Subscription Management
      responses:
        '200':
          $ref: '#/components/responses/OkResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 154
                  method: private/unsubscribe_all
                  params: {}
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Unsubscribe from all the channels subscribed so far. This method takes no parameters.


        [Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Funsubscribe_all)


        '
      x-mint:
        metadata:
          title: private/unsubscribe_all
          og:title: private/unsubscribe_all
          keywords:
          - private/unsubscribe_all
        href: /api-reference/subscription-management/private-unsubscribe_all
components:
  responses:
    Getunsubscribe200response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Getunsubscribe200response'
          examples:
            jsonObject:
              value:
                jsonrpc: '2.0'
                id: 3370
                result:
                - deribit_price_index.btc_usd
            response:
              value:
                jsonrpc: '2.0'
                id: 3370
                result:
                - deribit_price_index.btc_usd
              description: Response example
      description: Successfully unsubscribed from channels
    PrivateSubscribeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateSubscribeResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 4235
                result:
                - deribit_price_index.btc_usd
              description: Response example
      description: Success response
    OkResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OkResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 1569
                result: ok
              description: Response example
      description: Success response
    ErrorMessageResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageResponse'
      description: Success response
  schemas:
    Getunsubscribe200response:
      type: object
      properties:
        jsonrpc:
          type: string
          example: '2.0'
        id:
          type: integer
          example: 8691
        result:
          type: array
          items:
            type: string
            x-deribit-type: channel
          example:
          - deribit_price_index.btc_usd
          description: List of channels that were successfully unsubscribed in this request
    ErrorMessageResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        message:
          type: string
        error:
          type: integer
      required:
      - jsonrpc
      - message
      - error
      type: object
    PrivateSubscribeResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          type: array
          items:
            type: string
            example: deribit_price_index.btc_usd
          description: A list of subscribed channels.
      required:
      - jsonrpc
      - result
      type: object
    OkResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          type: string
          enum:
          - ok
          description: Result of method execution. `ok` in case of success
      required:
      - jsonrpc
      - result
      type: object