Release 0.1.0-binance-pro-preview

Date: 2026-06-11

This is the first productized Elixir target checkpoint for the Binance-first CCXT Pro work. It is a Hex preview publication candidate for controlled Binance REST and Binance Pro integration work.

Release Boundary

This release is scoped to:

• Binance REST raw endpoint generation.
• Binance selected unified REST generation.
• Binance Pro high-level websocket method coverage.
• CCXT-style Pro instance configuration through Ccxt.Pro.binance/1.
• OTP-owned websocket lifecycle through Registry and DynamicSupervisor.
• Public watch, stream, unwatch, cache, parser, telemetry, and cleanup flows.
• Private websocket API signing, request-id routing, response parsing, and read-only live smoke.
• Private user-data stream subscription, event routing, cache, snapshot preload, and lifecycle helpers.
• Order websocket API mutation support with explicit production risk gates.
• CCXT unified structure normalization and persistence planning helpers.

This release is not scoped to:

• General multi-exchange Elixir Pro support.
• Publishing to Hex.
• Full REST method maturity for every Binance funding/margin/savings mutation.
• Automatic safe execution of withdraw, transfer, borrow, repay, convert, or gift-code REST surfaces.
• Always-on live tests that require real fills or private liquidation events.

Package State

The Elixir package metadata now identifies this target as:

version: "0.1.0-binance-pro-preview"

Recommended integration after publishing is through the Hex preview version:

{:ccxt, "== 0.1.0-binance-pro-preview"}

smoke/consumer_app verifies the source-checkout consumption model from a separate Mix project with:

{:ccxt, path: "../.."}

The package includes:

• lib
• priv
• doc
• mix.exs
• README.md

Generated ExDoc output is written to _build/docs so it does not overwrite the tracked doc source directory.

Supported User Entrypoints

Main modules:

• Ccxt.Pro
• Ccxt.Pro.Binance
• Ccxt.Exchanges.Binance
• Ccxt.Raw.Binance
• Ccxt.StructureNormalizer
• Ccxt.StructurePersistence
• Ccxt.StructureSchema

Production-style examples:

• examples/pro_ticker_worker.exs: GenServer + Task.Supervisor public ticker worker that stores the latest ticker snapshot and performs explicit websocket cleanup.
• examples/pro_order_event_worker.exs: GenServer + Task.Supervisor private order event worker that authenticates once, reuses ws_auth, and consumes stream_orders/4 with newUpdates: true.

Primary Pro usage:

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

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

Public streams:

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

Connection shutdown:

Ccxt.Pro.connections()
|> Enum.each(&Ccxt.Pro.close_connection(&1.pid))

Evidence Snapshot

Latest verified evidence recorded for this release:

• npm run inspectElixirPro: 107/107 Binance Pro source methods covered.
• Generated/runtime split: 66 generated and 41 runtime-owned.
• unsupportedMethods: [].
• Exchange instance wrappers: 52/52 required callable public methods wrapped.
• Runtime lifecycle coverage: 18/18 required features covered.
• Structure coverage: 44 covered structure rows, 71 classified non-structure rows, 0 unclassified rows.
• npm run checkElixir: 509 tests, 0 failures (60 excluded).
• mix test --include live --exclude prod_order_live test/ccxt_pro_binance_live_test.exs --timeout 180000: 34 tests, 0 failures. This refreshed public streams and signed read-only private websocket/API paths without enabling production order placement.
• Default long soak: npm run testElixirProLongSoak ran for 901.0 seconds with 883 ticker updates, 1767 websocket messages, maximum update gap 2992 ms, first update latency 2353 ms, 0 disconnects, and 0 terminations.
• Production-style worker smoke: CCXT_PRO_WORKER_SECONDS=5 mix run examples/pro_ticker_worker.exs received 3 public ticker updates for BTC/USDT, returned a snapshot with last_error: nil, and then stopped the worker with explicit connection cleanup.
• Production order live gate: CCXT_PRO_ENABLE_PROD_ORDER_LIVE=true BINANCE_PROD_ORDER_SYMBOL=BTC/USDT BINANCE_PROD_ORDER_AMOUNT=0.0002 mix test --only prod_order_live test/ccxt_pro_binance_live_test.exs --timeout 180000 ran 3 tests with 0 failures and 31 excluded, covering non-marketable production order create, fetch, edit, cancel, and stream_orders/4 execution-report handling.
• Private order event worker smoke: BINANCE_PRO_ENV=prod CCXT_PRO_ORDER_EVENT_WORKER_SECONDS=90 mix run examples/pro_order_event_worker.exs ran while CCXT_PRO_ENABLE_PROD_ORDER_LIVE=true mix run examples/pro_safe_order_lifecycle.exs created, fetched, edited, and canceled a non-marketable BTC/USDT order. The worker received 3 private execution-report updates (NEW, original order CANCELED, edited order CANCELED), retained them in its final snapshot, and exited normally. The retry path also surfaced Binance -2035 User Data Stream subscription already active, which is recorded as an exchange lifecycle condition.
• Path dependency consumer smoke: npm run testElixirConsumer compiled smoke/consumer_app with {:ccxt, path: "../.."} and ran 1 live public Binance Pro test with 0 failures, covering Ccxt.Pro.binance/1, watch_ticker/2, stream_ticker/2, and Ccxt.Pro.close_connection/1 from outside the package project.
• Hex package dry-run: npm run buildElixirPackage built ccxt-0.1.0-binance-pro-preview.tar with package metadata, runtime dependencies (jason, telemetry, websockex), lib, priv, doc, mix.exs, and README.md. mix hex.build --unpack also succeeded; the unpacked package contained the runtime/docs payload, including doc/real-project-integration.md and doc/release-checklist.md, and excluded test, examples, and smoke.
• Hex metadata audit: mix.exs keeps the preview version 0.1.0-binance-pro-preview, package name CCXT Elixir, MIT license, CCXT source/doc links, package files limited to lib, priv, doc, mix.exs, and README.md, and ExDoc extras for the API reference, real project integration guide, release checklist, release note, target maturity record, cache/lifecycle/structure coverage docs, structure schema guide, and live testing plan.
• Packaged consumer smoke: npm run testElixirPackageConsumer built and unpacked the local Hex package into a temporary directory, copied smoke/consumer_app into a clean temporary consumer project, pointed CCXT_CONSUMER_CCXT_PATH at the unpacked package, and ran 1 live public Binance Pro test with 0 failures against the package payload.
• Release preview gate: npm run releaseElixirPreviewCheck runs checkElixir, docsElixir, and testElixirPackageConsumer in order. Latest local run completed all three phases, including docs generation and the packaged consumer smoke with 1 test and 0 failures.
• Cache parity hardening: Ccxt.Pro.IndexedArrayCache adds reusable symbol/key-indexed cache semantics and Ccxt.Pro.OrderCache now uses it for symbol/id order replacement instead of id-only replacement.
• Timestamp cache hardening: Ccxt.Pro.TimestampArrayCache adds reusable timestamp-indexed replacement semantics and Binance OHLCV public cache uses it for raw kline payloads keyed by k.t.
• Position cache hardening: Ccxt.Pro.PositionCache now preserves Binance hedge-mode position updates by symbol -> side while keeping the existing per-symbol payload shape for watch_positions/4.
• New update counter hardening: Ccxt.Pro.CacheUpdates owns CCXT Pro getLimit-style allNewUpdates, newUpdatesBySymbol, nested id/side, and timestamp counter semantics. Public cached watch streams and private list/order watchers can opt into that incremental window with newUpdates: true or new_updates: true.

Risk Policy

Public market data methods are safe to run against production because they do not require credentials and do not mutate exchange state.

Signed read-only methods require production, testnet, or demo credentials that match the selected environment.

Order mutation methods are available but must stay gated in automation:

• create_order_ws/6
• edit_order_ws/7
• cancel_order_ws/3
• cancel_all_orders_ws/2

Production order tests require CCXT_PRO_ENABLE_PROD_ORDER_LIVE=true and use non-marketable orders with immediate cancel when possible. cancel_all_orders_ws/2 remains manual-confirmed only because it can cancel unrelated user orders.

REST funding and account-mutation surfaces such as withdraw, transfer, borrow, repay, convert, and gift code are outside the Pro manifest and remain manual-confirmed/dry-run/signature-only work for this release.

Known Boundaries

• Binance-only Pro scope.
• The long soak evidence is 15 minutes, not yet 6-hour or 24-hour soak.
• Event-driven private live tests cannot deterministically prove real fills or private liquidations without causing actual account events.
• Hex publication metadata exists, but the intended consumption model is still local/path dependency.
• Generated modules should not be edited by hand. Update the generator or runtime-owned modules instead.

Release Commands

Normal local gate:

npm run checkElixir

Generate ExDoc output:

npm run docsElixir

Short long-soak sanity:

CCXT_PRO_LONG_SOAK_SECONDS=5 CCXT_PRO_LONG_SOAK_MIN_UPDATES=1 npm run testElixirProLongSoak

Default long soak:

npm run testElixirProLongSoak