Crypto.com FCM — Technical Integration Design

The existing backend (apps/backend) is a NestJS monorepo with four deployables — api, admin, engine, worker — sharing libs/common. We add a fifth app and one shared lib.

Why a dedicated app and not a module inside api?

1. Single writer to the FIX session. FIX orders/quotes are pinned to the session that placed them and are sequence-numbered. If two api pods both held the socket we'd corrupt the sequence and duplicate orders. fcm-gateway runs as a single active instance (leader-elected via a Redis lock; standby for failover) so exactly one process owns each session.
2. Blast-radius isolation. A FIX resend storm or a reconnect loop must not degrade the customer-facing api.
3. Protocol containment. No FIX tag numbers leak past this boundary. The rest of the platform sees clean domain events (fcm.order.filled, fcm.instrument.settled).

The gateway must survive disconnects without losing or duplicating orders. This is the riskiest part of the integration.

Design rules baked in:

• HMAC signing is per-logon and differs by flow. signature = HEX(HMAC_SHA256(secret, "public/auth" + MsgSeqNum + apiKey + [system_labelONEEX] + nonce)). The system_labelONEEX fragment is present for OE/drop-copy, omitted for MD. Keep the secret in the platform secret store (never in Postgres/Redis).
• Cancel-on-Disconnect (COD) is ON for OE. This is a feature: a gateway crash auto-cancels our resting orders, so we never have unmonitored live risk. On reconnect we rebuild from Execution Reports + a Request For Position (35=AN) truth check, we do not blindly re-place.
• Sequence-number persistence. Inbound/outbound MsgSeqNum per session are persisted (Redis + periodic Postgres checkpoint) so a restart resumes the FIX session instead of forcing a reset.
• Standby instance holds the lock-wait; on leader death it acquires the lock, logs on fresh, and reconciles. Target failover < heartbeat-timeout window.

The vendor gives us two layers of reference data. We normalize both into our own tables so no downstream code ever parses vendor payloads.

1. predict_mapping_json.json — the catalog taxonomy: 11 sports (CBB, CWBB, CFB, GOLF, MLB, MMA, TENNIS, NBA, NFL, NHL, SOCCER), each with a SPORTS_GROUPING_ID, DISPLAY_NAME, and a PREDICT_CONTRACT_TYPE list (e.g. NBA has 472 contract types: Spread, Total Points, Moneyline, To Go To Overtime, …, each with RecordId / Name / Active). This is a static-ish reference file loaded at deploy/refresh time.
2. InstrAttribType 99 JSON blob (per live instrument, arrives inside Security List/Definition) — the event-specific payload: which real match, which teams, the strike, the resolution rule. Its schema lives in the "CDC FCM Appendix – Prediction Markets" document (must be requested from CDC FCM — see §11).

How a tradable market shows up in the Swivel UI.

Notes:

• Book subscriptions are two-sided and per-instrument. We subscribe on demand for markets a user is viewing (plus a hot set) to bound the number of MD subscriptions.
• Empty 35=X ~every 30s = heartbeat, not a change — used to confirm subscription health, never re-subscribe on it.
• Auto-cleanup: book + status subs are dropped by the exchange once an instrument settles; ReferenceSync reacts to the settled status rather than polling.
• fcm.book.updated is throttled/coalesced in the translator (e.g. max 4–10 Hz per instrument) so we don't flood Socket.io.

A Swivel user "buys YES at 63". This crosses the wallet, the engine, and the FIX session.

Key engineering points:

• Collateral is reserved before the FIX order goes out, released on reject/cancel, and only finalized at settlement. Because fills are fully collateralized (max loss = qty × price for a buy, qty × (100 − price) for a sell), the reserve amount is deterministic and known upfront — this maps onto our existing bet-wallet-transaction ledger cleanly.
• ClOrdID is ours, unique per session; OrderID is the exchange's. fcm-gateway owns the mapping. Amends chain via OrigClOrdID (41).
• Parties block identifies member/executor/position-owner. Which of the four cases (individual / entity / FCM client / on-behalf) applies depends on our membership model with CDC — an integration decision to confirm (§11).
• The order state machine lives in fcm-gateway, driven by ExecType (150) + OrdStatus (39). Exchange-initiated cancels (day roll, wash-trade prevention, unfilled IOC/FOK, book→settlement) arrive with no OrigClOrdID — the translator must classify these and emit fcm.order.cancelled{reason} so the wallet releases collateral.
• Trade Bust (150=H) is not a reversal in place — CDC opens a BUST_-prefixed offsetting order. The translator treats it as a new order + a compensating ledger entry, never mutating the original fill.

Settlement is asynchronous and exchange-authoritative. We never decide an outcome; we react to Position Reports and settle the wallet from them.

• Settlement payout math per contract type (Binary $100/$0, Future linear, Bracket in-range) is computed from SettlPrice. qty × settlPrice/100 is the gross return; the difference vs reserved collateral is the user's P/L.
• Void / tie / cancelled outcomes (EVENT_TIE, EVENT_CANCELED, SettlPriceDeterminationMethod 2451=9 Manual) surface in Security Status (35=f) text → we refund reserved collateral rather than settle a P/L. The worker's settlement handler must branch on these.
• Account Summary is poll-only (no push) — a ~5 min poll plus a Request For Position cross-check is our drift alarm. The internal ledger is authoritative for the user; the exchange balance is authoritative for the house account — reconciliation guards the gap.

The frontend never sees FIX. It sees a normal Swivel REST + Socket.io API served by api.

These typed events live in libs/common/src/fcm and are the contract between fcm-gateway and everyone else:

Commands (→ gateway):   fcm.order.submit · fcm.order.amend · fcm.order.cancel · fcm.order.massCancel
Events (← gateway):     fcm.instrument.listed · fcm.instrument.settled
                        fcm.book.updated
                        fcm.order.accepted · fcm.order.rejected · fcm.order.filled
                        fcm.order.cancelled · fcm.order.replaced · fcm.order.busted
                        fcm.position.settled

Mirrors the ExecType/OrdStatus cases from the FIX order spec, but this is the authoritative internal state that drives wallet releases and UI.

Each terminal/partial transition emits exactly one RabbitMQ event and (where money moves) one idempotent wallet ledger entry keyed by ExecID to survive FIX resends.

Framed as blockers:

1. 📄 "CDC FCM Appendix – Prediction Markets" — the JSON schema inside InstrAttribType 99. Blocks fcm_event/fcm_instrument modeling and the whole read path. (Highest priority.)
2. API key/secret provisioning, IP whitelist, key scope (trading vs read-only). Blocks any connection.
3. UAT/sandbox endpoint + test instruments. Blocks all integration testing.
4. Membership model → which Parties block case (individual / entity / FCM client / on-behalf) we send on every order. Blocks the write path.
5. Product scope for launch — Events/Politics only, or also FX/commodities. Bounds the Security List filter and the taxonomy load.

Internal decisions to nail down (PM-specific):

• Mapping of 0–100 price ↔ our odds/probability display and payout math per contract shape.
• Fully-collateralized accounting in our wallet/ledger (reserve → settle → release/forfeit lifecycle).
• Void/tie/cancelled refund handling in the settlement pipeline.
• Leader-election + failover story for the single-writer gateway.

Each phase is independently demoable: P1 ships a read-only prediction-market browser (real value, zero money risk), P2 adds trading behind a flag, P3 closes the money loop, P4 makes it production-grade.