README.md

# ExTwelveData

Unofficial Elixir client for [Twelve Data](https://twelvedata.com/).

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](https://github.com/Azolo/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.

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

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)
  end
end
```

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

```elixir
# 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
ExTwelveData.RealTimePrices.reset(Your.Name)
```

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

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `ex_twelve_data` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ex_twelve_data, "~> 0.1.0"}
  ]
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at <https://hexdocs.pm/ex_twelve_data>.

## Reference

[^1]: https://twelvedata.com/docs#real-time-price-websocket