Binance Spot Rest

⚠️ Upgrade Notice (v0.2.0):
The recvWindow parameter is now strictly a Decimal struct.
Integer values are no longer accepted. Max precision: 3 decimal places.
See changelog for migration examples.

Elixir library for interacting with the Binance Spot REST API. Provides a unified entry point for building, validating, signing, and executing REST requests.

Features

• Up-to-date with Binance Spot REST API — Implements all current Spot endpoints according to official docs.
• Polymorphic query struct interface — Every endpoint is represented by a query struct. Whether it has parameters or not, you always call BinanceSpotRest.request/1.
• Built-in validation — Queries with parameters are validated before sending, preventing mistakes and unnecessary API calls.
• Enum helpers — Use provided Enums to safely build queries consistently.
• Testable and mockable — Easily override execution, base URL, timestamps, or signature functions for testing without hitting Binance servers.
• No automatic retries — All requests are executed exactly once. Users must implement their own retry/backoff logic if needed.

• Built on top of Req and Decimal
• Uses Valpa, Loe, and Numa internally for validation and composition

Installation

Add to your mix.exs:

def deps do
  [
    {:binance_spot_rest, "~> 0.2.1"}
  ]
end

Then fetch deps:

mix deps.get

Configuration

The library reads credentials from your application configuration under :binance_spot_rest.

Direct configuration

import Config

config :binance_spot_rest,
  base_url: "https://testnet.binance.vision",  # or "https://api.binance.com" for production
  api_key: "your_api_key",
  secret_key: "your_secret_key"

Security tip: Do not commit real API keys to your repository.

Environment variables (optional, recommended)

import Config

config :binance_spot_rest,
  base_url: System.get_env("BINANCE_SPOT_REST_BASE_URL"),
  api_key: System.get_env("BINANCE_SPOT_REST_API_KEY"),
  secret_key: System.get_env("BINANCE_SPOT_REST_SECRET_KEY")

Then set your credentials in your environment:

# Linux/macOS
export BINANCE_SPOT_REST_API_KEY="your_real_api_key"
export BINANCE_SPOT_REST_SECRET_KEY="your_real_secret_key"
export BINANCE_SPOT_REST_BASE_URL="https://api.binance.com"   # optional

# Windows (PowerShell)
setx BINANCE_SPOT_REST_API_KEY "your_real_api_key"
setx BINANCE_SPOT_REST_SECRET_KEY "your_real_secret_key"
setx BINANCE_SPOT_REST_BASE_URL "https://api.binance.com"

This keeps credentials out of code and version control.

Validation Behavior

BinanceSpotRest uses Valpa for query parameter validation.

• Default behavior in v0.1.1:

  • In :dev and :test environments, validation errors include full stacktraces.
  • In :prod, stacktraces are hidden; only the error tuple is returned. This prevents leaking internal details in production logs.

• Optional configuration: You can override the default stacktrace behavior by configuring Valpa directly:

import Config

config :valpa, show_stacktrace: true  # or false

Usage

High-level API

All endpoints are represented as query structs. You call them the same way, regardless of whether they have parameters:

# Parameterized query
alias BinanceSpotRest.Endpoints.Trading.OrderPost.LimitQuery

query = %LimitQuery{
  symbol: "LTCBTC",
  side: BinanceSpotRest.Enums.Side._BUY(),
  type: BinanceSpotRest.Enums.OrderType._LIMIT(),
  timeInForce: BinanceSpotRest.Enums.TimeInForce._GTC(),
  quantity: Decimal.new("1.0"),
  price: Decimal.new("0.00029")
}

{:ok, result} = BinanceSpotRest.request(query)

# Empty query (e.g., ping or time endpoints)
query = %BinanceSpotRest.Endpoints.General.Time.Query{}
{:ok, result} = BinanceSpotRest.request(query)

Override behavior for testing:

BinanceSpotRest.request(query,
  execute: false,
  base_url: "https://mock.url",
  timestamp_fn: fn -> 1_740_000_000_000 end,
  signature_fn: fn _qs, _key -> "mock-signature" end
)

Tip for testing: Use execute: false and a mock signature_fn to run tests without hitting Binance.

Low-level API (optional)

You can chain internal steps manually:

import Loe
alias BinanceSpotRest.Endpoints.Trading.OrderPost.LimitQuery

query = %LimitQuery{...}

query
~>> BinanceSpotRest.Query.validate()
~>> BinanceSpotRest.Query.prepare()
~>> BinanceSpotRest.Client.create_request()
~>> BinanceSpotRest.Client.make_request()

With overrides:

query
~>> BinanceSpotRest.Query.prepare()
~>> BinanceSpotRest.Client.create_request(
  base_url: "https://mock.url",
  headers: [{"FAKE_API_KEY", "fake_api_key"}],
  timestamp_fn: fn -> 1_740_000_000_000 end,
  signature_fn: fn _qs, _key -> "mock-signature" end
)

For a detailed low-level workflow and pipeline examples, see the Architecture Guide.

Endpoint Queries

Each endpoint has its own query struct module:

BinanceSpotRest.Endpoints.<Category>.<EndpointPath>.<QueryModule>

Examples:

• /api/v3/ticker/bookTicker (GET) → BinanceSpotRest.Endpoints.MarketData.TickerBookTicker
• /api/v3/order/amend/keepPriority (PUT) → BinanceSpotRest.Endpoints.Trading.OrderAmendKeepPriorityPut

Development / Updating

This library aims to stay aligned with the official Binance Spot REST API.

1. Monitor official docs: Binance REST API
2. Compare endpoints: Look for new endpoints, changed parameters, or removed endpoints.
3. Update query structs: Add new endpoints or adjust parameters/validation using Valpa.
4. Update enums: Adjust Enum modules to reflect new or changed values.
5. Test thoroughly: Use the testnet to verify requests and responses.
6. Document version: Optionally indicate the library version or date it is synced with Binance API.

Tip for contributors: Each PR updating endpoints should reference the official API section it implements or fixes.

Adding a New Endpoint

Contributors can add new endpoints by creating a query struct under the proper module namespace.
The library is designed to be polymorphic — any query struct works with BinanceSpotRest.request/1.
Please refer to existing endpoint modules for examples.

Documentation

Full docs: HexDocs

Contributing

Contributions are welcome via issues or pull requests. Created and maintained by Centib.

License

Released under the MIT License