Binance Pro API Reference

This reference describes the supported Elixir surface for the Binance-first CCXT Pro preview. The canonical implementation remains generated from ts/src/pro/binance.ts; this document explains how to call the generated target from Elixir code.

Entrypoints

Ccxt.Pro.binance/1 creates a CCXT-style Binance Pro instance:

binance =
  Ccxt.Pro.binance(%{
    apiKey: "...",
    secret: "...",
    binanceEnv: "prod",
    options: %{recvWindow: 5_000}
  })

Ccxt.Pro.Binance.new/1 is the exchange-specific constructor behind Ccxt.Pro.binance/1.

Accepted config keys:

Per-call options override instance options.

Watch Semantics

Generated watch_* methods follow CCXT Pro's one-message async model. In Elixir they return {:ok, value} or {:error, reason}:

{:ok, ticker} =
  Ccxt.Pro.Binance.watch_ticker("BTC/USDT",
    binance_env: "prod",
    timeout: 30_000
  )

The websocket subscription remains open on the shared connection after a successful watch_* call. Call the same watch_* method again to wait for the next update.

Most public methods also accept an instance as their first argument:

{:ok, ticker} = Ccxt.Pro.Binance.watch_ticker(binance, "BTC/USDT")

Stream Semantics

Elixir stream_* methods are convenience wrappers over repeated watch_* calls. They return an Enumerable that yields {:ok, value} or {:error, reason}:

Ccxt.Pro.Binance.stream_ticker("BTC/USDT",
  binance_env: "prod",
  timeout: 30_000,
  unwatch_on_halt: true
)
|> Enum.take(10)

unwatch_on_halt: true sends the matching public unwatch request when the enumerable halts. Private stream wrappers do not imply private unwatch support; close the connection explicitly when private user-data streams should stop.

Connection Lifecycle

Ccxt.Pro owns the runtime websocket topology:

unwatch_* methods only send Binance unsubscribe messages and wait for ACK. They do not close the underlying websocket connection. Use Ccxt.Pro.close_connection/1 for shutdown.

Production Worker Pattern

For an OTP-style integration, keep blocking stream consumption out of business process callbacks. The included examples/pro_ticker_worker.exs demonstrates the public stream shape:

children = [
  {Task.Supervisor, name: Ccxt.Pro.Examples.BinanceTickerWorker.TaskSupervisor},
  {Ccxt.Pro.Examples.BinanceTickerWorker,
   symbol: "BTC/USDT", binance_env: "prod", print?: false}
]

Supervisor.start_link(children, strategy: :one_for_one)

The worker uses a GenServer to own the latest ticker snapshot and a Task.Supervisor child to consume Ccxt.Pro.Binance.stream_ticker/2. On stop, the worker terminates the stream task and calls Ccxt.Pro.close_connection/1.

Run the standalone example from ccxt/elixir:

CCXT_PRO_WORKER_SECONDS=10 mix run examples/pro_ticker_worker.exs

examples/pro_order_event_worker.exs uses the same GenServer + Task.Supervisor shape for private order events. It authenticates once, reuses the returned ws_auth for Ccxt.Pro.Binance.stream_orders/4, and requests incremental private windows with newUpdates: true:

CCXT_PRO_ORDER_EVENT_WORKER_SECONDS=30 mix run examples/pro_order_event_worker.exs

Because stream consumption runs in a Task.Supervisor.async_nolink/2 child, a production worker must handle both the task result message ({ref, result}) and the matching :DOWN monitor message. The example demonitor-flushes the matched task result, closes the private websocket connection, records the last error, and restarts through the normal retry path.

Public Market Methods

Public market methods do not require credentials.

Public stream wrappers:

Public unwatch methods:

Private Websocket API Methods

Signed read-only methods:

Signed order mutation methods:

Order mutation tests use non-marketable production orders and immediate cleanup where possible. They are not part of normal mix test.

Private User Data Stream Methods

Private event-driven methods:

Private stream wrappers:

User-data stream helpers:

Options

Common options:

Private snapshot options:

Unified Structures

Generated parsers return CCXT-style maps for ticker, trade, order, balance, position, order book, OHLCV, and liquidation structures. Raw exchange payloads remain available under each structure's :info field.

The structure-to-database planning layer is documented in:

• doc/ccxt-structure-schema.md
• doc/ccxt-pro-structure-coverage.md

The persistence helper modules are intentionally adapter-like. They normalize CCXT structures into stable row maps; they do not require a specific Ecto schema or database migration.

Environment Variables

Production Pro credentials:

BINANCE_PROD_API_KEY=...
BINANCE_PROD_API_SECRET=...
BINANCE_PRO_ENV=prod

Testnet Pro credentials:

BINANCE_TESTNET_API_KEY=...
BINANCE_TESTNET_API_SECRET=...
BINANCE_PRO_ENV=testnet

Demo Pro credentials:

BINANCE_DEMO_API_KEY=...
BINANCE_DEMO_API_SECRET=...
BINANCE_PRO_ENV=demo

REST/manual smoke credentials:

BINANCE_API_KEY=...
BINANCE_API_SECRET=...
BINANCE_ENV=prod

Production, testnet, and demo keys are separate Binance key families.

Validation Commands

Normal gate:

npm run checkElixir

Generate API documentation:

npm run docsElixir

Build a local Hex package dry-run:

npm run buildElixirPackage

Run the path dependency consumer smoke:

npm run testElixirConsumer

Run the packaged consumer smoke:

npm run testElixirPackageConsumer

Run the release preview gate:

npm run releaseElixirPreviewCheck

Short public soak:

CCXT_PRO_SOAK_SECONDS=5 CCXT_PRO_SOAK_MIN_UPDATES=1 npm run testElixirProSoak

Default long public soak:

npm run testElixirProLongSoak