RFC: Bitnomial DCM Integration

Date: 2026-05-24

Status: Draft, blocked on Bitnomial API/provisioning details

AX is currently built as an exchange over Connamara EP3. We want to build a temporary Bitnomial Edition of AX while our own DCM is being spun up. Because this edition may only run for a few months, the preferred implementation shape is separate, copy-pasted services where that reduces abstraction work and risk.

This document summarizes the current recommendation after reviewing AX's EP3 integration seams and Bitnomial's public API documentation.

Build the Bitnomial Edition as separate hot-path services backed by a shared ax-bitnomial client crate. Do not do a broad EP3 abstraction refactor now.

Use this protocol split:

• BTP DMA Order Entry for open, modify, cancel-as-modify, and order-entry replies.
• FIX Drop Copy for authoritative private order/fill lifecycle and reconciliation.
• REST for products, funding rates, orders/fills backfill, and reference data.
• BTP Pricefeed or public WebSocket for market data.

Reuse common AX components where practical: public SDK protocols, auth/session machinery, DB/Redis/ClickHouse helpers, transaction-engine, and risk-engine2. Copy or fork EP3-shaped services that directly encode venue behavior: order-gateway, marketdata-publisher, and fill/trade ingestion.

AX's EP3 dependency is not isolated to one adapter. It appears in service-layer assumptions around identity, account provisioning, instruments, order lifecycle, market data, and settlement.

Important current coupling points:

• order-gateway connects and logs into EP3 at startup.
• order-gateway loads instruments from EP3 and treats EP3 as authoritative for scale, tick size, minimum order size, and schedule.
• Order requests are converted directly into EP3 protobuf requests.
• Order lifecycle is driven by EP3 drop copy semantics.
• AX user/account IDs are encoded in EP3 participant/account names and stored in users.ep3_username, users.ep3_account, trading_accounts.ep3_username, and trading_accounts.ep3_account.
• Market data, trade ingestion, risk ingestion, and settlement all consume EP3-specific APIs or streams.

Bitnomial is different enough that forcing it through EP3-shaped abstractions would create misleading compatibility:

• Order entry is BTP binary TCP DMA, not gRPC.
• Authentication is ConnectionId + AuthToken, not EP3 user impersonation.
• BTP orderId is a uint64 unique per connection.
• Cancels are represented as modify requests with a closing quantity.
• Bitnomial modifies orders in place; AX should preserve its two-order replace model at the API boundary.
• Drop copy is FIX 4.4 execution reports, not EP3 drop copy.
• Market data is top-10 aggregated levels, not EP3-style book entries.
• Public docs do not expose admin/user/account provisioning APIs.

The public docs do not describe an API for programmatic user or account provisioning.

What the docs do say:

• Accounts, connections, risk settings, orders, and settlement are managed through the Customer Portal.
• Customer roles can add accounts, request/add/approve/enable/disable connections, adjust risk settings, and cancel orders depending on role.
• A Bitnomial connection is a ConnectionId plus AuthToken.
• A connection can be associated with any number of clearing accounts.
• REST and FIX can see all orders/fills for accounts associated with the connection.

What the docs do not show:

• No public API to create accounts.
• No public API to create users.
• No public API to create, enable, disable, or approve connections.
• No public API to configure account risk settings.
• No public position endpoint in the public API docs, even though the risk docs mention a Position REST API.

Practical AX implication: treat Bitnomial account and connection setup as an ops/admin workflow unless Bitnomial provides private APIs. Store Bitnomial account/connection mappings in Postgres, but do not assume api-gateway can provision Bitnomial users/accounts the way it provisions EP3 participants.

We would strongly prefer one Bitnomial connection that multiplexes many AX users/accounts. Public docs make this only partly viable.

The docs support one connection associated with many accounts for visibility:

• REST GET /orders and GET /fills can filter by account_id.
• FIX execution reports include Account(1).
• The connection docs say a connection can see all orders for associated accounts through REST and FIX.

However, public BTP order entry does not show per-order account routing. The BTP Open request only contains:

• orderId
• productId
• side
• price
• quantity
• timeInForce

There is no documented account_id, clearing firm, CTI, customer capacity, or give-up field on BTP order entry. Public BTP reject reasons mention account and give-up errors, so there may be connection-level defaults or private routing configuration, but it is not documented publicly.

Practical interpretation:

• If AX trades through one omnibus Bitnomial clearing account, one BTP connection can multiplex many AX users internally and AX owns subaccounting.
• If every AX trading account must map to a distinct Bitnomial clearing account, public BTP is insufficient unless Bitnomial has private account-routing fields or per-connection account selection not present in public docs.
• REST order submission does take account_id, but public docs show no REST cancel or modify endpoints, so REST is not viable as the primary trading path.

This is the first question to ask Bitnomial: can one BTP order-entry connection route orders to multiple clearing accounts? If yes, where is account/give-up specified?

Keep AX's two-order replace model at the client/API boundary.

For Bitnomial:

• A replacement request creates a new AX order_id.
• Venue-side BTP uses a modify against the original Bitnomial orderId plus a new modifyId.
• On Bitnomial replace ack/FIX report, mark the old AX order terminal Replaced and advance the new AX order to Accepted.
• On Bitnomial replace reject, reject the new AX replacement order and leave the old order live.

Reject or document unsupported AX features:

• post_only: reject unless Bitnomial confirms BTP support.
• GTC: reject for BTP unless Bitnomial confirms support; public BTP documents only Day and IOC.
• Custom self-trade prevention behavior: reject or ignore with clear docs; Bitnomial SMP is always enabled and not caller-configurable.

Initial scope is futures and perpetual futures.

Use REST /product/specs/?active=true as the product catalog source. Filter to futures and perpetual futures. Exclude options and spreads initially.

Bitnomial perpetual futures follow future-like notation with a far expiry, for example PBUCZ50. Funding rates are available through REST:

• /funding-rates/
• /funding-rates/estimated/:base_symbol

Store Bitnomial product_id as the routing key. Treat symbol as display/API identity.

Final authority is intentionally unresolved for now.

Working assumption:

• FCM/Bitnomial daily margin and balance state is authoritative.
• AX maintains approximate intraday positions, equity, open-order margin, and risk controls from our order/fill stream.
• Daily reconciliation resets or corrects AX internal state.

Shared Bitnomial client crate:

• BTP codec/session engine: framing, little-endian fields, sequence IDs, heartbeats, disconnect handling.
• BTP order entry client: open, modify, cancel-as-modify, replies, local rate limiting.
• BTP pricefeed or WebSocket market data client: book snapshots, level updates, trades, market state.
• FIX drop copy client/parser: execution reports and FIX session state.
• REST client: products, orders, fills, funding rates, HMAC auth.
• Normalized venue events: accepted, rejected, filled, partially filled, canceled, replaced, closed, market state.

Copied/forked from order-gateway where useful.

Responsibilities:

• Preserve AX REST/WS order API as much as possible.
• Replace Ep3Identity with Bitnomial account/connection routing.
• Persist mapping from AX order_id to Bitnomial connection_id, BTP orderId, latest ackId, current modifyId, and optional Bitnomial account_id.
• Use BTP replies for low-latency acceptance/reject feedback.
• Use FIX drop copy as the authoritative lifecycle source.
• Use REST orders/fills for startup/backfill reconciliation within rate limits.
• Implement cancel-all by iterating known open orders per connection unless Bitnomial provides admin cancel APIs.

Copied/forked from marketdata-publisher where useful.

Responsibilities:

• Load active products from REST.
• Maintain Bitnomial product_id to symbol mapping.
• Publish AX marketdata protocol from BTP pricefeed or public WebSocket.
• Explicitly document top-10 depth only.
• Use receive-time for BTP if BTP provides no exchange timestamp, or prefer WebSocket if exchange timestamps are required.

Do not copy EP3 trade-engine literally. EP3 trade ingestion pairs both sides of the trade. Bitnomial FIX drop copy likely gives our account-side view, so fills should be single-sided and attributed through the order mapping table.

Responsibilities:

• Ingest FIX execution reports.
• Attribute fills to AX users/accounts via order mapping.
• Feed positions, balances, fees, and risk snapshots from normalized fills.
• Backfill from REST /fills when recovering.

There is no public link to private docs. The public docs direct DMA customers to the Customer Portal and help@exchange.bitnomial.com for onboarding.

Ask Bitnomial for:

• BTP certification/onboarding guide.
• Latest BTP schemas, including any private account/give-up routing fields.
• FIX drop copy session, resend, sequence-reset, and recovery spec.
• Position REST API docs.
• Admin/account/connection provisioning API docs, if any.
• Admin cancel or cancel-all API docs, if any.
• Sandbox limitations for order entry, drop copy, and account filters.
• Confirmation whether BTP supports GTC, post-only, and any custom SMP flags.

• Can one BTP order-entry connection route orders to multiple clearing accounts?
• If yes, where is account, clearing firm, CTI, customer capacity, or give-up specified?
• Is an omnibus Bitnomial clearing account acceptable for the temporary Bitnomial Edition?
• Does Bitnomial expose programmatic account/connection/risk provisioning APIs under customer/NDA docs?
• Does BTP support GTC or post-only outside the public docs?
• What is the authoritative position API and recovery process after disconnect, crash, or DR failover?
• What are the sandbox limitations for production-like testing?

1. Build ax-bitnomial BTP codec/session and order-entry client.
2. Build REST product catalog and Bitnomial product mapping.
3. Build bitnomial-order-gateway for one-connection/omnibus routing.
4. Add FIX drop copy ingestion before production use.
5. Add market data and funding-rate ingestion.
6. Add reconciliation/backfill jobs.