DeribitEx.Adapter (deribit_ex v0.2.0)

View Source

WebsockexNova adapter for the Deribit WebSocket API.

Handles connection, authentication, and message processing specifically for the Deribit JSON-RPC WebSocket protocol.

Summary

Functions

Provides connection configuration for the WebsockexNova client.

Generates authentication data for Deribit API.

Generates data for the disable_cancel_on_disconnect operation.

Generates data for the disable_heartbeat operation.

Generates data for the enable_cancel_on_disconnect operation.

Generates data for token exchange operation.

Generates data for token fork operation.

Generates data for the get_cancel_on_disconnect operation.

Generates data for logout operation.

Generates data for the set_heartbeat operation.

Generates data for the unsubscribe_all operation.

Generates data for the unsubscribe operation.

Handles authentication response from Deribit.

Handles the connection established event.

Handles disable_cancel_on_disconnect response from Deribit.

Handles disable_heartbeat response from Deribit.

Handles enable_cancel_on_disconnect response from Deribit.

Handles token exchange response from Deribit.

Handles token fork response from Deribit.

Handles raw WebSocket frames from the Deribit API.

Handles get_cancel_on_disconnect response from Deribit.

Handles various info messages sent to the process.

Handles logout response from Deribit.

Handles messages from Deribit WebSocket API.

Handles set_heartbeat response from Deribit.

Handles subscription response from Deribit.

Handles unsubscribe_all response from Deribit.

Handles unsubscribe response from Deribit.

Initializes the adapter's state.

Sends a JSON-RPC request to the Deribit API.

Creates a subscription request for a specific channel.

Handles termination of the adapter process.

Functions

connection_info(opts)

@spec connection_info(map()) :: {:ok, map()}

Provides connection configuration for the WebsockexNova client.

Merges provided options with sensible defaults for Deribit connection.

Configures optimal authentication refresh thresholds based on Deribit's token expiration patterns. Tokens typically last 900 seconds, and refresh begins at the configured threshold before expiration.

generate_auth_data(state)

@spec generate_auth_data(map()) :: {:ok, String.t(), map()} | {:error, atom(), map()}

Generates authentication data for Deribit API.

Uses client credentials from the connection state to create a proper Deribit authentication request.

generate_disable_cod_data(params, state)

@spec generate_disable_cod_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for the disable_cancel_on_disconnect operation.

This function prepares the JSON-RPC request for the private/disable_cancel_on_disconnect endpoint, which disables automatic cancellation of orders on disconnection.

Parameters

  • params - Parameters for disabling COD (optional scope)
  • state - The current adapter state

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

generate_disable_heartbeat_data(params, state)

@spec generate_disable_heartbeat_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for the disable_heartbeat operation.

This function prepares the JSON-RPC request for the public/disable_heartbeat endpoint, which disables server heartbeat messages for the connection.

Parameters

  • params - Parameters (unused but kept for consistency)
  • state - The current adapter state

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

generate_enable_cod_data(params, state)

@spec generate_enable_cod_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for the enable_cancel_on_disconnect operation.

This function prepares the JSON-RPC request for the private/enable_cancel_on_disconnect endpoint, which enables automatic cancellation of orders on disconnection.

Parameters

  • params - Parameters for COD, includes the scope (connection or account)
  • state - The current adapter state

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

generate_exchange_token_data(params, state)

@spec generate_exchange_token_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for token exchange operation.

This function creates the payload for the public/exchange_token RPC method used to generate a new access token for switching subaccounts.

generate_fork_token_data(params, state)

@spec generate_fork_token_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for token fork operation.

This function creates the payload for the public/fork_token RPC method used to create a new named session via refresh token.

generate_get_cod_data(params, state)

@spec generate_get_cod_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for the get_cancel_on_disconnect operation.

This function prepares the JSON-RPC request for the private/get_cancel_on_disconnect endpoint, which gets the status of automatic order cancellation on disconnection.

Parameters

  • params - Parameters for getting COD (no additional parameters needed)
  • state - The current adapter state

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

generate_logout_data(params, state)

@spec generate_logout_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for logout operation.

This function creates the payload for the private/logout RPC method used to gracefully close the session and optionally invalidate tokens.

Parameters

  • params - Parameters for the logout request:
    • "invalidate_token" - Whether to invalidate all tokens (defaults to true)
  • state - Current adapter state containing the access token

Returns

  • {:ok, payload, updated_state} - The JSON-RPC request as a string and updated state
  • Raises an error if no access token is found in the state

Examples

# Generate payload to logout and invalidate tokens
params = %{"invalidate_token" => true}
{:ok, payload, updated_state} = generate_logout_data(params, state)

# Generate payload to logout without invalidating tokens
params = %{"invalidate_token" => false}
{:ok, payload, updated_state} = generate_logout_data(params, state)

generate_set_heartbeat_data(params, state)

@spec generate_set_heartbeat_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for the set_heartbeat operation.

This function prepares the JSON-RPC request for the public/set_heartbeat endpoint, which enables server heartbeat messages for the connection.

Parameters

  • params - Parameters containing at least the heartbeat interval in seconds (minimum 10s)
  • state - The current adapter state

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

generate_unsubscribe_all_data(params, state)

@spec generate_unsubscribe_all_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for the unsubscribe_all operation.

This function prepares the JSON-RPC request for the public/unsubscribe_all endpoint, which stops all active subscriptions.

Parameters

  • params - Parameters (unused but kept for consistency)
  • state - The current adapter state

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

generate_unsubscribe_data(params, state)

@spec generate_unsubscribe_data(map(), map()) :: {:ok, String.t(), map()}

Generates data for the unsubscribe operation.

This function prepares the JSON-RPC request for the public/unsubscribe or private/unsubscribe endpoint, which stops the stream for specified channels.

Parameters

  • params - Parameters for unsubscribe, includes the channels to unsubscribe from
  • state - The current adapter state

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

handle_auth_response(response, state)

@spec handle_auth_response(map(), map()) :: {:ok, map()} | {:error, map(), map()}

Handles authentication response from Deribit.

Processes different types of responses:

  • Success: Stores token and expiration time
  • Error: Stores error details
  • Other: Passes through

Uses WebsockexNova's built-in authentication refresh mechanism to handle token renewal before expiration.

handle_connect(conn_info, state)

@spec handle_connect(map(), map()) :: {:ok, map()} | {:authenticate, map()}

Handles the connection established event.

Executes telemetry events for connection opening, updates the state, and handles reconnection logic by resetting reconnect_attempts counter.

Leverages WebsockexNova's connection event callbacks to automatically trigger authentication and resubscription after reconnections.

handle_disable_cod_response(arg1, state)

@spec handle_disable_cod_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles disable_cancel_on_disconnect response from Deribit.

Updates the state to reflect the COD status after disabling it.

handle_disable_heartbeat_response(arg1, state)

@spec handle_disable_heartbeat_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles disable_heartbeat response from Deribit.

Updates the state to reflect the heartbeat status after disabling it.

handle_enable_cod_response(arg1, state)

@spec handle_enable_cod_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles enable_cancel_on_disconnect response from Deribit.

Updates the state to reflect the COD status after enabling it.

handle_exchange_token_response(response, state)

@spec handle_exchange_token_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles token exchange response from Deribit.

Processes response from the public/exchange_token endpoint and updates state with new tokens and expiration information.

handle_fork_token_response(response, state)

@spec handle_fork_token_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles token fork response from Deribit.

Processes response from the public/fork_token endpoint and updates state with new tokens and expiration information.

handle_frame(type, data, state)

@spec handle_frame(atom(), String.t(), map()) ::
  {:ok, map()} | {:reply, atom(), String.t(), map()}

Handles raw WebSocket frames from the Deribit API.

This function is called for each incoming WebSocket frame before JSON parsing. Handles heartbeat test_request messages directly at the frame level.

handle_get_cod_response(arg1, state)

@spec handle_get_cod_response(map(), map()) :: {:ok, map()} | {:error, map(), map()}

Handles get_cancel_on_disconnect response from Deribit.

Updates the state with the current COD status from the API.

handle_info(arg1, state)

@spec handle_info(atom() | tuple(), map()) :: {:ok, map()} | {:error, any(), map()}

Handles various info messages sent to the process.

This used to handle manual refresh_auth messages, but now we use WebsockexNova's built-in auth refresh mechanism. This handler remains for backward compatibility with existing tests and other potential custom messages.

handle_logout_response(arg1, state)

@spec handle_logout_response(map(), map()) :: {:ok, map()} | {:error, map(), map()}

Handles logout response from Deribit.

Updates the state to reflect the user is no longer authenticated by:

  • Setting auth_status to :unauthenticated
  • Removing access_token, refresh_token, and related fields

This ensures that after logout, any subsequent operations requiring authentication will require a new authentication process.

Parameters

  • response - The response from Deribit for the logout request
  • state - Current adapter state

Returns

  • {:ok, updated_state} - On successful logout with state cleared of auth data
  • {:error, error, updated_state} - On error response, with error recorded in state
  • {:ok, state} - For unrecognized responses (fallthrough case)

Examples

# Successful logout
response = %{"result" => "ok"}
{:ok, updated_state} = handle_logout_response(response, state)
# updated_state.auth_status == :unauthenticated

# Error response
response = %{"error" => %{"code" => 10011, "message" => "Error message"}}
{:error, error, updated_state} = handle_logout_response(response, state)

handle_message(message, state)

@spec handle_message(map(), map()) ::
  {:needs_auth, map(), map()}
  | {:ok, map(), map()}
  | {:error, any(), map()}
  | {:reply, String.t(), map()}

Handles messages from Deribit WebSocket API.

Processes different message types:

  • Auth errors: Signals need for authentication
  • JSON-RPC responses: Matches with tracked requests and processes appropriately
  • Other messages: Delegates to DefaultMessageHandler

handle_set_heartbeat_response(arg1, state)

@spec handle_set_heartbeat_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles set_heartbeat response from Deribit.

Updates the state to reflect the heartbeat status after enabling it.

handle_subscription_response(response, state)

@spec handle_subscription_response(map(), map()) ::
  {:ok, map()} | {:error, any(), map()}

Handles subscription response from Deribit.

handle_unsubscribe_all_response(arg1, state)

@spec handle_unsubscribe_all_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles unsubscribe_all response from Deribit.

Updates the state to clear all subscriptions.

handle_unsubscribe_response(arg1, state)

@spec handle_unsubscribe_response(map(), map()) ::
  {:ok, map()} | {:error, map(), map()}

Handles unsubscribe response from Deribit.

Updates the state to remove the unsubscribed channels.

init(opts)

@spec init(map() | any()) :: {:ok, map()}

Initializes the adapter's state.

send_rpc_request(method, params, state, options \\ nil)

@spec send_rpc_request(String.t(), map(), map(), map() | nil) ::
  {:ok, String.t(), map()}

Sends a JSON-RPC request to the Deribit API.

This is a general-purpose RPC handler for sending any Deribit API request. It handles request generation, authentication, timeout tracking, and more.

Parameters

  • method - The JSON-RPC method to call (e.g., "public/get_time")
  • params - The parameters to pass to the method (map)
  • state - The current adapter state
  • options - Optional request options

Returns

  • {:ok, encoded_request, updated_state} - The JSON request and updated state

subscribe(channel, params, state)

@spec subscribe(String.t(), map(), map()) :: {:ok, String.t(), map()}

Creates a subscription request for a specific channel.

Handles different subscription types (public vs. private) based on channel name and authentication status.

terminate(reason, state)

@spec terminate(any(), map()) ::
  {:reconnect, map()} | {:reconnect_and_authenticate, map()} | :ok

Handles termination of the adapter process.

Executes telemetry events for connection closing and updates reconnection attempts. Handles graceful shutdowns vs. unexpected disconnections.

Enhanced to better integrate with WebsockexNova's connection lifecycle management for intelligent reconnections with authentication preservation.