@spec get_quote(
  String.t(),
  keyword()
) ::
  {:ok, YfQuote.Quote.t()}
  | {:error, :no_data | :invalid_symbol | :conversion_failed}

Fetches asset price with optional currency conversion

Parameters:

• symbol - Exact ticker (e.g. "BTC-USD", "AAPL", "EURCHF=X") (required)

Options:

• :to - Target currency (e.g. "CHF", "EUR") (optional, default: native currency)
• :date - Date struct (e.g. ~D[2024-12-31]) (optional)

Ticker formats:

• Crypto: "BTC-USD", "ETH-USD"
• Stocks: "AAPL", "TSLA", "GOOGL"
• Forex: "EURCHF=X", "GBPUSD=X"

Examples

# Bitcoin in USD (default)
iex(1)> {:ok, quote} = YfQuote.get_quote("BTC-USD")
{:ok,
%YfQuote.Quote{
  price: 109409.086,
  currency: "USD",
  symbol: "BTC-USD",
  datetime: ~U[2025-09-04 16:42:00Z],
  market_timezone: "UTC"
}}


# Bitcoin in CHF
iex(1)>  {:ok, quote} = YfQuote.get_quote("BTC-USD", to: "CHF")
{:ok,
%YfQuote.Quote{
  price: 88227.4869504,
  currency: "CHF",
  symbol: "BTC-USD",
  datetime: ~U[2025-09-04 16:42:00Z],
  market_timezone: "UTC"
}}


# Apple stock
iex(1)> {:ok, quote} = YfQuote.get_quote("AAPL")
{:ok,
%YfQuote.Quote{
  price: 237.05,
  currency: "USD",
  symbol: "AAPL",
  datetime: ~U[2025-09-04 16:43:52Z],
  market_timezone: "America/New_York"
}}


# Historical price
iex(1)> YfQuote.get_quote("BTC-USD", date: ~D[2024-12-31])
{:ok,
%YfQuote.Quote{
  price: 93429.203125,
  currency: "USD",
  symbol: "BTC-USD",
  datetime: ~U[2024-12-31 23:59:59Z],
  market_timezone: "UTC"
}}

# Date too old
iex(1)> YfQuote.get_quote("BTC-USD", date: ~D[2014-08-01])
{:error, :no_data}

Returns: {:ok, %Quote{}} | {:error, reason} Error reasons:

• :no_data - No data available
• :invalid_symbol - Ticker not recognized
• :conversion_failed - Currency conversion failed

@spec get_quote!(
  String.t(),
  keyword()
) :: YfQuote.Quote.t()

Fetches asset price (bang version, raises exception on error)

Same parameters as get_quote/2 but returns the Quote directly or raises an exception.

Examples

# Success case
iex> quote = YfQuote.get_quote!("BTC-USD")
iex> is_struct(quote, YfQuote.Quote)
true

# Error case (raises exception)
YfQuote.get_quote!("INVALID_TICKER")
# ** (RuntimeError) Failed to get quote: invalid_symbol