@spec chain(module(), map(), keyword()) :: {:ok, chain_result()} | {:error, term()}

Fetch a complete enriched option chain from Deribit.

Parameters

• ccxt - Bourse dispatcher module (the top-level Bourse module) (value)
• exchange - Built %Bourse.Exchange{} handle from Bourse.exchange(:deribit) (value)

Options

• currency - Currency to fetch (default: "BTC")
• enrich - :none or :greeks (default: :none)
• enrich_limit - Max instruments to enrich by OI (default: 50)
• max_concurrency - Parallelism for enrichment (default: 10)

Returns

{:ok, %{chain, spot, enriched_count}} or {:error, reason} (tuple)

Example

{:ok,
 %{
   spot: 83500.0,
   chain: %{"BTC-31JAN26-84000-C" => %{open_interest: 1200.0}},
   enriched_count: 25
 }}

Errors

• :exchange_error - Pass-through error from ccxt.fetch_option_chain/2

Composes With

• gamma_walls

# descripex:contract
%{
  opts: %{
    currency: %{default: "BTC", type: :string, description: "Currency to fetch"},
    max_concurrency: %{
      default: 10,
      type: :integer,
      description: "Parallelism for enrichment"
    },
    enrich: %{default: :none, type: :atom, description: ":none or :greeks"},
    enrich_limit: %{
      default: 50,
      type: :integer,
      description: "Max instruments to enrich by OI"
    }
  },
  params: %{
    exchange: %{
      description: "Built `%Bourse.Exchange{}` handle from `Bourse.exchange(:deribit)`",
      kind: :value
    },
    ccxt: %{
      description: "Bourse dispatcher module (the top-level `Bourse` module)",
      kind: :value
    }
  },
  errors: [exchange_error: "Pass-through error from ccxt.fetch_option_chain/2"],
  returns: %{
    type: :tuple,
    description: "{:ok, %{chain, spot, enriched_count}} or {:error, reason}"
  },
  returns_example: {:ok,
   %{
     spot: 83500.0,
     chain: %{"BTC-31JAN26-84000-C" => %{open_interest: 1200.0}},
     enriched_count: 25
   }},
  composes_with: [:gamma_walls]
}

@spec dvol(module(), map(), keyword()) :: {:ok, dvol_result()} | {:error, term()}

Fetch and parse Deribit DVOL volatility index history.

Parameters

• ccxt - Bourse dispatcher module (the top-level Bourse module) (value)
• exchange - Built %Bourse.Exchange{} handle from Bourse.exchange(:deribit) (value)

Options

• currency - Currency to fetch (default: "BTC")

Returns

{:ok, %{current, history}} or {:error, reason} (tuple)

Example

{:ok, %{history: [{~U[2026-02-25 12:00:00Z], 44.8}], current: 45.2}}

Errors

• :exchange_error - Pass-through error from ccxt.fetch_volatility_history/3
• :empty_history - No valid DVOL rows in response
• :invalid_input - DVOL payload shape is invalid

# descripex:contract
%{
  opts: %{
    currency: %{default: "BTC", type: :string, description: "Currency to fetch"}
  },
  params: %{
    exchange: %{
      description: "Built `%Bourse.Exchange{}` handle from `Bourse.exchange(:deribit)`",
      kind: :value
    },
    ccxt: %{
      description: "Bourse dispatcher module (the top-level `Bourse` module)",
      kind: :value
    }
  },
  errors: [
    exchange_error: "Pass-through error from ccxt.fetch_volatility_history/3",
    empty_history: "No valid DVOL rows in response",
    invalid_input: "DVOL payload shape is invalid"
  ],
  returns: %{
    type: :tuple,
    description: "{:ok, %{current, history}} or {:error, reason}"
  },
  returns_example: {:ok,
   %{history: [{~U[2026-02-25 12:00:00Z], 44.8}], current: 45.2}}
}

@spec expiry(String.t()) :: {:ok, Date.t()} | {:error, :invalid_format}

Extract expiry date from a Deribit option symbol.

Parameters

• symbol - Deribit option symbol (value)

Returns

{:ok, Date.t()} or {:error, :invalid_format} (tuple)

Example

{:ok, ~D[2026-01-31]}

Errors

• :invalid_format

# descripex:contract
%{
  params: %{symbol: %{description: "Deribit option symbol", kind: :value}},
  errors: [:invalid_format],
  returns: %{
    type: :tuple,
    description: "{:ok, Date.t()} or {:error, :invalid_format}"
  },
  returns_example: {:ok, ~D[2026-01-31]}
}

@spec gamma_walls(module(), map(), keyword()) ::
  {:ok, gamma_walls_result()} | {:error, term()}

Fetch option chain and compute gamma exposure walls.

Parameters

• ccxt - Bourse dispatcher module (the top-level Bourse module) (value)
• exchange - Built %Bourse.Exchange{} handle from Bourse.exchange(:deribit) (value)

Options

• currency - Currency to fetch (default: "BTC")
• enrich_limit - Max instruments to enrich (default: 50)
• max_concurrency - Parallelism (default: 10)
• side - :dealer or :customer sign convention (default: :dealer)
• min_oi - Minimum OI to include (default: 0)
• top_n - Return only top N walls

Returns

{:ok, %{walls, spot, chain_size, enriched_count}} or {:error, reason} (tuple)

Example

{:ok,
 %{
   spot: 83500.0,
   enriched_count: 50,
   walls: [%{type: :support, strike: 84000.0, gex: 1250.0}],
   chain_size: 120
 }}

Errors

• :no_spot_price - Spot extracted from chain is <= 0
• :exchange_error - Pass-through error from chain/2 or exchange module

# descripex:contract
%{
  opts: %{
    currency: %{default: "BTC", type: :string, description: "Currency to fetch"},
    max_concurrency: %{default: 10, type: :integer, description: "Parallelism"},
    side: %{
      default: :dealer,
      type: :atom,
      description: ":dealer or :customer sign convention"
    },
    enrich_limit: %{
      default: 50,
      type: :integer,
      description: "Max instruments to enrich"
    },
    min_oi: %{default: 0, type: :number, description: "Minimum OI to include"},
    top_n: %{
      default: nil,
      type: :integer,
      description: "Return only top N walls"
    }
  },
  params: %{
    exchange: %{
      description: "Built `%Bourse.Exchange{}` handle from `Bourse.exchange(:deribit)`",
      kind: :value
    },
    ccxt: %{
      description: "Bourse dispatcher module (the top-level `Bourse` module)",
      kind: :value
    }
  },
  errors: [
    no_spot_price: "Spot extracted from chain is <= 0",
    exchange_error: "Pass-through error from chain/2 or exchange module"
  ],
  returns: %{
    type: :tuple,
    description: "{:ok, %{walls, spot, chain_size, enriched_count}} or {:error, reason}"
  },
  returns_example: {:ok,
   %{
     spot: 83500.0,
     enriched_count: 50,
     walls: [%{type: :support, strike: 84000.0, gex: 1250.0}],
     chain_size: 120
   }}
}

@spec option_type(String.t()) :: {:ok, :call | :put} | {:error, :invalid_format}

Extract option type (:call or :put) from a Deribit option symbol.

Parameters

• symbol - Deribit option symbol (value)

Returns

{:ok, :call | :put} or {:error, :invalid_format} (tuple)

Example

{:ok, :call}

Errors

• :invalid_format

# descripex:contract
%{
  params: %{symbol: %{description: "Deribit option symbol", kind: :value}},
  errors: [:invalid_format],
  returns: %{
    type: :tuple,
    description: "{:ok, :call | :put} or {:error, :invalid_format}"
  },
  returns_example: {:ok, :call}
}

@spec parse_dvol(term()) ::
  {:ok, dvol_result()} | {:error, :empty_history | :invalid_input}

Parse raw DVOL volatility index history into structured data.

Parameters

• history_data - List of [unix_ms, value] pairs or parsed volatility-history maps with :timestamp/:volatility (value)

Returns

{:ok, %{current, history}} or {:error, :empty_history | :invalid_input} (tuple)

Example

{:ok, %{history: [{~U[2026-02-25 12:00:00Z], 44.8}], current: 45.2}}

Errors

• :empty_history
• :invalid_input

# descripex:contract
%{
  params: %{
    history_data: %{
      description: "List of [unix_ms, value] pairs or parsed volatility-history maps with :timestamp/:volatility",
      kind: :value
    }
  },
  errors: [:empty_history, :invalid_input],
  returns: %{
    type: :tuple,
    description: "{:ok, %{current, history}} or {:error, :empty_history | :invalid_input}"
  },
  returns_example: {:ok,
   %{history: [{~U[2026-02-25 12:00:00Z], 44.8}], current: 45.2}}
}

@spec parse_option(String.t()) :: {:ok, parsed_option()} | {:error, :invalid_format}

Parse a Deribit option symbol into structured data.

Parameters

• symbol - Deribit option symbol (e.g., "BTC-31JAN26-84000-C") (value)

Returns

{:ok, %{underlying, expiry, strike, type}} or {:error, :invalid_format} (tuple)

Example

{:ok,
 %{type: :call, strike: 84000.0, expiry: ~D[2026-01-31], underlying: "BTC"}}

Errors

• :invalid_format

Composes With

• strike
• expiry
• option_type
• underlying
• valid_option?

# descripex:contract
%{
  params: %{
    symbol: %{
      description: "Deribit option symbol (e.g., \"BTC-31JAN26-84000-C\")",
      kind: :value
    }
  },
  errors: [:invalid_format],
  returns: %{
    type: :tuple,
    description: "{:ok, %{underlying, expiry, strike, type}} or {:error, :invalid_format}"
  },
  returns_example: {:ok,
   %{type: :call, strike: 84000.0, expiry: ~D[2026-01-31], underlying: "BTC"}},
  composes_with: [:strike, :expiry, :option_type, :underlying, :valid_option?]
}

@spec parse_option!(String.t()) :: parsed_option()

Parse a Deribit option symbol, raising on failure.

Parameters

• symbol - Deribit option symbol (value)

Returns

%{underlying, expiry, strike, type} or raises ArgumentError (map)

Example

%{value: 1.0}

# descripex:contract
%{
  params: %{symbol: %{description: "Deribit option symbol", kind: :value}},
  returns: %{
    type: :map,
    description: "%{underlying, expiry, strike, type} or raises ArgumentError"
  },
  returns_example: %{value: 1.0}
}

@spec strike(String.t()) :: {:ok, float()} | {:error, :invalid_format}

Extract strike price from a Deribit option symbol.

Parameters

• symbol - Deribit option symbol (value)

Returns

{:ok, float()} or {:error, :invalid_format} (tuple)

Example

{:ok, 84000.0}

Errors

• :invalid_format

# descripex:contract
%{
  params: %{symbol: %{description: "Deribit option symbol", kind: :value}},
  errors: [:invalid_format],
  returns: %{
    type: :tuple,
    description: "{:ok, float()} or {:error, :invalid_format}"
  },
  returns_example: {:ok, 84000.0}
}

@spec underlying(String.t()) :: {:ok, String.t()} | {:error, :invalid_format}

Extract underlying asset from a Deribit option symbol.

Parameters

• symbol - Deribit option symbol (value)

Returns

{:ok, String.t()} or {:error, :invalid_format} (tuple)

Example

{:ok, "BTC"}

Errors

• :invalid_format

# descripex:contract
%{
  params: %{symbol: %{description: "Deribit option symbol", kind: :value}},
  errors: [:invalid_format],
  returns: %{
    type: :tuple,
    description: "{:ok, String.t()} or {:error, :invalid_format}"
  },
  returns_example: {:ok, "BTC"}
}

@spec valid_option?(String.t()) :: boolean()

Check if a symbol is a valid Deribit option format.

Parameters

• symbol - String to validate (value)

Returns

true if valid Deribit option symbol (boolean)

Example

true

# descripex:contract
%{
  params: %{symbol: %{description: "String to validate", kind: :value}},
  returns: %{type: :boolean, description: "true if valid Deribit option symbol"},
  returns_example: true
}