Bitnomial DCM Edition (AIEX)

§0Principles

This edition is a stopgap, not a platform, and every design call follows from that. The four invariants below — plus one deliberate carve-out from the first — explain the whole shape of the work; everything in the tracker is mechanics.

§1Progress & Dependencies

This is not a linear sequence — it's nine parallel tracks, mostly one per forked service and one per owner, that converge on a working edition. The flat order would hide what actually matters: which tracks can run independently, and the handful of hard dependencies where one track genuinely blocks another. The dependency map shows those edges; the swimlanes below show progress per track. Snapshot 2026-06-06.

Dependency map

How the tracks block one another. Solid arrows are hard blockers (the downstream work cannot finish first); dashed arrows are foundational or soft. Node colour is status. The critical path to a demoable edition runs drop-copy → risk-engine and accounts → order-gateway, both converging — with the api-gateway seam — on Edition works E2E; the external-dependency tail then gates go-live.

§2aThe "aiex" strategy — fork, don't abstract

AX is an exchange built over Connamara EP3. The Bitnomial Edition (nicknamed AIEX = ax + bitnomial) lets Architect operate a US-regulated venue now — listing Architect-licensed products on Bitnomial's DCM and introducing customers to Bitnomial's FCM — while Architect's own DCM spins up. Because the edition may run only a few months, the preferred shape is separate, copy-pasted services wherever that reduces abstraction work and risk.

The reason a generic EP3 adapter was rejected: EP3 coupling is not isolated to one seam. It appears in service-layer assumptions around identity, account provisioning, instruments, order lifecycle, market data, and settlement — order-gateway logs into EP3 at startup, loads instruments from EP3, converts requests into EP3 protobuf, and drives lifecycle off EP3 drop-copy semantics. Bitnomial is different enough at each point (binary BTP DMA not gRPC; ConnectionId+AuthToken not user impersonation; modify-in-place not two-order replace; FIX 4.4 drop copy not EP3 drop copy; top-10 aggregated depth not book entries) that forcing it through EP3 shapes would create misleading compatibility.

§2bThe protocol split

Bitnomial exposes several protocols; each is assigned the job it's best at, and lifecycle truth is deliberately separated from the fast path.

Fills from drop copy are single-sided — we get our account's view, not both sides of the trade as EP3 trade ingestion pairs them — so fills are attributed to AX accounts through the order-mapping table rather than matched. REST /fills is the recovery source when the FIX session gaps. Ports in UAT: 11000 BTP order entry, 12000 BTP pricefeed, 10001 FIX drop copy.

§2cThe omnibus connection & attributed-open routing

The RFC's first and most important question was whether one BTP order-entry connection can route to multiple clearing accounts — public BTP Open carries only orderId, productId, side, price, quantity, timeInForce, with no documented account field. If the answer were no, AX would need one connection per customer.

Self-match handling is "cancel on self-match" and is always enabled / not caller-configurable, so exercising both sides of a market in test requires distinct accounts (Bitnomial provisioned UBU00005–UBU00008 for Architect). One consequence for identity: the mapping is AX account_id → Bitnomial clearing account, and Bitnomial account IDs may not be globally unique across FCMs — so the mapping must also carry the clearing firm.

§2dIdentity & account mapping at the seam

AX currently encodes user/account identity into EP3 participant/account names (users.ep3_username, users.ep3_account, trading_accounts.ep3_username, trading_accounts.ep3_account). Bitnomial needs its own mapping, and the cleanest place to put it is new nullable Bitnomial columns on trading_accounts plus a publication/replica into the risk engine — not a restructuring of the EP3 columns.

Provisioning, by contrast, is an ops/admin workflow, not an API: Bitnomial's public docs expose no programmatic user/account/connection creation, so AX stores Bitnomial account/connection mappings in Postgres and treats creation as a portal/manual step until Bitnomial ships an onboarding API.

§2eMargin, positions & reconciliation authority

Positions are a solved problem — exact dead reckoning, reconciled daily. What is intentionally unresolved is final authority over margin, and the reason is structural, not a missing feature.

Working model, therefore — and note the deliberate split between positions and margin:

• Positions are exact, not approximate. AX dead-reckons positions precisely from its own order/fill stream (the authoritative FIX drop-copy lifecycle) and reconciles them against the FCM record at end of day. The goal is an exact intraday position that ties out daily — not a best-effort estimate.
• Margin is the approximate part. AX may ultimately run a different risk model than the FCM, so the intraday margin/equity figure is an internal estimate used for AX's own risk controls — it is not expected to be byte-identical to the clearing margin.
• FCM / Bitnomial daily margin and balance state is authoritative for settlement; daily reconciliation corrects any position drift and is the only window onto the authoritative margin/settlement numbers (reached via the FCM, not a direct Bitnomial API).

The residual correctness risk is concentrated in margin, not positions: the intraday margin view has no independent intraday cross-check, and the contract-multiplier handling in margin/PnL (A-3544) is a known open gap on top of it.

§2fAX API semantics over BTP

We preserve AX's two-order replace model at the client/API boundary even though Bitnomial modifies orders in place. A replacement creates a new AX order_id; venue-side it's a BTP modify against the original Bitnomial orderId with a new modifyId.

Unsupported or unconfirmed AX features are rejected (or documented) rather than faked:

• post_only — reject unless Bitnomial confirms BTP support.
• GTC — reject for BTP unless confirmed; public BTP documents only Day and IOC.
• Custom self-trade-prevention flags — reject/ignore with clear docs; Bitnomial SMP is always on and not caller-configurable.

Cancel-all is implemented by iterating known open orders per connection unless Bitnomial provides an admin cancel API. A reported (unanswered) concern: order state after partial fills, and after a replace mid-partial-fill, was historically hard to read on Bitnomial — see §3.4.

§2gService fork map & branch reality

The components and how each maps to an EP3 service — plus where the code actually lives today.

§2hConnectivity & environments

Network and environment facts that shape testing and deploy:

• Order entry is private-only — BTP order entry and FIX drop copy run over PrivateLink / VPN / DirectConnect, not the public internet. Dev started on VPN/Tailscale; prod targets PrivateLink. Market data is available over the public WebSocket.
• Session identity — SenderCompID is ARCHITECT; connection id 79 (parsed as hex, not decimal) plus an auth token. Env vars standardize on a BTNL_* prefix; the edition is selected by EXCHANGE_EDITION=aiex.
• REST catalog is served (currently unauthenticated, internet-only, not yet on PrivateLink) from 85is.net: /product/specs/, /product/data/{id}. Bitnomial manages product provisioning on the test env.
• Sandbox vs prod is murky — orders against sandbox product IDs were rejected ("account not found") while a prod product went through; the team was directed to the prod /product/specs path. Carries a real risk of accidentally trading against prod products in test (§3.6).

§3Open Questions

The questions the code can't answer — most are dependencies on Bitnomial. Each carries its current resolution.

1. Can one BTP order-entry connection route to multiple clearing accounts? And where is the account specified?
   • Answered — yes Bitnomial confirmed a single connection can specify the account via an "attributed open" message (reserved for FCM-class partners), confirmed live in UAT. The AttributedOpen body shipped in #2208. AX runs one omnibus connection and owns subaccounting (§2c).
2. Does BTP support GTC or post_only outside the public docs?
   • Not yet answered No answer from Bitnomial in any channel. Public BTP documents only Day and IOC. Current plan: reject both at the API boundary until confirmed (§2f).
3. What is the authoritative margin/settlement API, and the recovery process after disconnect/crash/DR failover?
   • Answered — blocked Bitnomial's margin/settlement APIs are gated behind contract execution; AX gets no direct access as an interim IB — the authoritative numbers come through the FCM (Dorman) via GMI on the daily cycle. No confirmed public Position REST API. The accepted model: positions dead-reckoned exact + reconciled daily, margin approximate (possibly a different risk model than the FCM). The residual risk lives in margin, not positions (§2e, step 13).
4. How does order state read after partial fills, and after a replace mid-partial-fill?
   • Not yet answered Raised from an ex-Bitnomial market-maker's report that this was historically hard to determine; the thread to Bitnomial went unanswered. An unmitigated protocol risk on the order-gateway lifecycle path — needs a definitive spec answer before production (§2f).
5. Does Bitnomial expose programmatic account / connection / risk provisioning & onboarding APIs?
   • Partially — coming Not today. Bitnomial says they'll expose the onboarding API "as soon as they can"; the institutional portal link is also outstanding. Interim: a manual/portal ops workflow, mappings stored in Postgres (§2d, step 14).
6. What are the sandbox limitations vs prod for production-like testing?
   • Partially answered Real confusion observed — sandbox product IDs rejected ("account not found") while a prod product went through; team directed to the prod /product/specs path. The sandbox/UAT/prod boundary remains murky, with a live risk of submitting against prod products in test (§2h).
7. How long does the Bitnomial Edition run before cutaway to Architect's own DCM?
   • Strategic — open By design, "as soon as regulatorily possible" once Architect's own DCM is live. The fork-don't-abstract strategy (§2a) is the bet on this being short. The actual window depends on the DCM standup and the Bitnomial LOI (exclusivity, no certification-timing commitment, assignable to an affiliate) — outside engineering's control (step 15).
8. Internal gate: must the account/identity rekey land before the order-gateway?
   • Answered — yes Yes. The order-gateway stack was explicitly put on hold pending the accounts rekey; without splitting identity from ownership and removing from_default_account_id shortcuts, the edition "is gonna really have a bad time." This is the internal critical path (§2d, steps 11–12).

§4Documentation

The reference material this project is built against — internal design docs, the in-repo BTP specs that are our source of truth for the wire, Bitnomial's public API docs, and the related AX plans.

Internal — design & specs

• RFC: Bitnomial DCM Integration — the founding design (docs/rfc/bitnomial-dcm-integration.md); this plan tracks its execution.
• BTP wire-format reference — rs/bitnomial/BTP_SPEC.md; the source of truth for every byte the ax-btp codec and ax-btp-mock emit/accept.
• BTP REST catalog spec — rs/bitnomial/BTP_REST_SPEC.md; the authoritative reference for the GET /product/specs/ JSON used by instrument loading.
• BTNL_FORK.md — fork reference doc. on develop-bitnomial — not on main

Bitnomial — public API docs

• BTP order-entry / pricefeed protocol
• REST API overview · authentication (HMAC) · products · orders
• REST base: https://bitnomial.com/exchange/api/v1/ — prod (prod/product/specs/) vs sandbox (sandbox/product/specs/). The sandbox/prod boundary is murky — see §2h, §3.6.
• bitnomial/wireshark-btp — upstream Wireshark BTP dissector, cross-referenced by the wire spec.
• Onboarding / private-doc requests: help@exchange.bitnomial.com (BTP certification guide, FIX recovery spec, Position API, provisioning APIs — see RFC §"Private Or Missing Docs To Request").

Linear — epics

All under the Perpetuals exchange project · Integrations milestone. There is no standalone Bitnomial Linear project — issues carry the AIEx label.

Related AX plans

• Multi-Accounts — the identity/ownership rekey the Bitnomial account mapping rides on (the internal critical path, §2d).
• Position Feed Promotion — the EP3-side position-cache cutover; adjacent risk/margin work.