![CI](https://github.com/theorycraft-trading/binance_spot/actions/workflows/ci.yml/badge.svg)
[![Documentation](https://img.shields.io/badge/hex.pm-docs-green.svg?style=flat)](https://hexdocs.pm/binance_spot)
[![Package](https://img.shields.io/hexpm/v/binance_spot.svg)](https://hex.pm/packages/binance_spot)

# BinanceSpot

[BinanceSpot](https://github.com/theorycraft-trading/binance_spot) is a [TheoryCraft](https://github.com/theorycraft-trading/theory_craft) library for downloading and streaming **historical an live** market data from Binance Spot.

Access free historical data for all Binance Spot trading pairs including trades, aggregate trades, and klines.

## Warning

**This library is under active development and the API is subject to frequent changes.**

Breaking changes may occur between releases as we refine the interface and add new features.

## Installation

Add `binance_spot` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:binance_spot, github: "theorycraft-trading/binance_spot"}
  ]
end
```

## Elixir API

### Search Instruments

```elixir
alias BinanceSpot.Instruments

# Get all symbols
Instruments.all()
# => ["1000BONKUSDT", "1000CATUSDT", ..., "BTCUSDT", "ETHUSDT", ...]

# Search symbols
Instruments.search("BTC")
# => ["BTCUSDT", "ETHBTC", "WBTCBTC", ...]

# Lookup instrument details
Instruments.lookup!("BTCUSDT")
# => %{symbol: "BTCUSDT", base_asset: "BTC", quote_asset: "USDT", ...}
```

### DataFeed (TheoryCraft Integration)

Use `BinanceSpot.DataFeed` with TheoryCraft's `MarketSource` to build trading pipelines:

```elixir
alias TheoryCraft.MarketSource

opts = [
  symbol: "BTCUSDT",
  source: :agg_trade,
  from: ~D[2024-01-01],
  to: ~D[2024-01-31]
]

market =
  %MarketSource{}
  |> MarketSource.add_data({BinanceSpot.DataFeed, opts}, name: "BTCUSDT")
  |> MarketSource.resample("m5", name: "BTCUSDT_m5")
  |> MarketSource.resample("h1", name: "BTCUSDT_h1")

for event <- MarketSource.stream(market) do
  IO.inspect(event)
end
```

## Development

```bash
# Run tests
mix test

# Run CI checks (format + credo + tests)
mix ci

# Run dialyzer
mix dialyzer

# Update instrument metadata from Binance API
mix binance_spot.gen.instruments
```

## License

Copyright (C) 2025 TheoryCraft Trading

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.