DeribitEx

View Source

An Elixir library for interacting with the Deribit cryptocurrency exchange API via WebSocket.

Hex.pm Documentation License

Features

  • WebSocket-based communication: Efficient and real-time communication with Deribit API
  • Authentication management: Automatic token refresh, exchange, and forking
  • Request/response handling: Clean JSON-RPC implementation
  • Subscription management: Easy subscription to public and private channels
  • Automatic resubscription: After reconnection or authentication changes
  • Rate limiting: Adaptive rate limiting to avoid 429 errors
  • Time synchronization: Keeps local time in sync with server time
  • Cancel-on-disconnect: Automatic setup of safety measures
  • Telemetry integration: Comprehensive event instrumentation

Installation

Add deribit_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:deribit_ex, "~> 0.1.0"}
  ]
end

Configuration

Configure your Deribit API credentials in your config:

# config/config.exs
config :deribit_ex,
  client_id: System.get_env("DERIBIT_CLIENT_ID"),
  client_secret: System.get_env("DERIBIT_CLIENT_SECRET"),
  test_mode: true # Set to false for production API

# Optional settings
config :deribit_ex,
  rate_limit_mode: :normal, # Options: :cautious, :normal, :aggressive
  request_timeout: 5000     # Default timeout in milliseconds

Or provide credentials directly when connecting:

{:ok, client} = DeribitEx.Client.connect(
  client_id: "your_client_id",
  client_secret: "your_client_secret",
  test_mode: true
)

Usage Examples

Connecting to Deribit

# Connect with configured credentials
{:ok, client} = DeribitEx.Client.connect()

# Or connect with explicit credentials
{:ok, client} = DeribitEx.Client.connect(
  client_id: "your_client_id",
  client_secret: "your_client_secret"
)

Making API Requests

# Get available instruments
{:ok, instruments} = DeribitEx.Client.get_instruments(client, %{
  currency: "BTC",
  kind: "future"
})

# Get account summary
{:ok, summary} = DeribitEx.Client.get_account_summary(client, %{
  currency: "BTC"
})

# Place an order
{:ok, order} = DeribitEx.Client.buy(client, %{
  instrument_name: "BTC-PERPETUAL",
  amount: 100,
  type: "limit",
  price: 30000,
  post_only: true
})

Subscriptions

# Define a callback module
defmodule MyApp.DeribitHandler do
  use GenServer

  def start_link(_opts) do
    GenServer.start_link(__MODULE__, %{})
  end

  def init(state) do
    {:ok, state}
  end

  # Handle subscription notifications
  def handle_info({:deribit_notification, channel, data}, state) do
    IO.puts("Received notification from #{channel}")
    # Process the data
    {:noreply, state}
  end
end

# Start the handler
{:ok, handler_pid} = MyApp.DeribitHandler.start_link([])

# Subscribe to orderbook updates
{:ok, _sub_id} = DeribitEx.Client.subscribe_book(
  client,
  "BTC-PERPETUAL",
  handler_pid
)

# Subscribe to your account updates (requires authentication)
{:ok, _sub_id} = DeribitEx.Client.subscribe_user_orders(
  client,
  "BTC",
  handler_pid
)

# Unsubscribe when done
:ok = DeribitEx.Client.unsubscribe(client, sub_id)

Token Management

# Exchange your token to access a sub-account
{:ok, _new_client} = DeribitEx.Client.exchange_token(client, "subaccount_name")

# Create a named session
{:ok, _named_client} = DeribitEx.Client.fork_token(client, "session_name")

Telemetry Events

DeribitEx emits telemetry events that you can handle in your application:

:telemetry.attach(
  "deribit-request-handler",
  [:deribit_ex, :request, :stop],
  fn name, measurements, metadata, _config ->
    # Handle request completion event
  end,
  nil
)

Key events include:

  • [:deribit_ex, :request, :start]
  • [:deribit_ex, :request, :stop]
  • [:deribit_ex, :subscription, :notification]
  • [:deribit_ex, :auth, :refresh]
  • [:deribit_ex, :rate_limit, :delay]

Testing with Deribit Testnet

The library uses Deribit's testnet when test_mode: true is set. You can create a testnet account at test.deribit.com.

Documentation

Full documentation is available at HexDocs.

License

DeribitEx is released under the MIT License. See the LICENSE file for details.