# ExTwelveData

Unofficial Elixir client for [Twelve Data](

Currently, it only covers the real-time prices WebSocket API.

Happy to accept contributions to support the other endpoints.

## Usage

### Real-time prices client

Twelve Data offers a WebSocket based API for real-time prices[^1].
ExTwelveData uses the [WebSockex](
library to access this endpoint.
Because of this, the WebSocket client runs as a supervised process.

The `ExTwelveData.RealTimePrices.Handler` behaviour requires a single callback,
invoked whenever the client receives a price update from Twelve Data.

defmodule Your.Handler do
  @behaviour ExTwelveData.RealTimePrices.Handler
  @impl true
  def handle_price_update(price) do
    # Here you can process inbound price updates

defmodule Your.Application do
  use Application
  alias ExTwelveData.RealTimePrices
  def start(_type, _args) do
    children = [
      {RealTimePrices, name: Your.Name, api_key: "abc", handler: Your.Handler},
    Supervisor.start_link(children, strategy: :one_for_one)

With the process running, you can now subscribe, unsubscribe, and reset the subscriptions.

# Send a list of Twelve Data symbols to subscribe to
ExTwelveData.RealTimePrices.subscribe(Your.Name, ["BTC/USD", "AAPL"])

# Use the PID or process name to address the messages
ExTwelveData.RealTimePrices.unsubscribe(Your.Name, ["AAPL"])

# This stops listening for all updates, while keeping the client running

The client currently takes care of reconnecting, and sending the heartbeat every 10 seconds.

## Installation

If [available in Hex](, the package can be installed
by adding `ex_twelve_data` to your list of dependencies in `mix.exs`:

def deps do
    {:ex_twelve_data, "~> 0.1.0"}

Documentation can be generated with [ExDoc](
and published on [HexDocs]( Once published, the docs can
be found at <>.

## Reference