SoW: Desk management / Cross-account self-trade prevention

Master: SoW: Desk management, step 8.

Tracking: A-5032. Customer need: Blockhouse asked for a second trading account on 2026-09-17. TTG and Axtior need accounts that do trade against each other.

Delivers: ticket W5.5 and the self-trade part of decision D3 in Accounts and transfers. Uses: customers and trading_accounts.customer_id from Customer account access. Does not change: the parent pointer in Account families.

Objective. AX can state, per set of accounts, whether those accounts may trade against each other. The venue enforces the answer. The default does not change: an account is prevented only against itself.

The problem

A customer can hold several trading accounts. Two kinds of customer ask for this, and they need opposite behavior:

Today AX can only give the first behavior. No setting gives the second.

Current behavior

• One AX trading account is one EP3 participant and one EP3 account. trading_accounts.ep3_username and ep3_account are unique and generated per account (rs/ep3/src/ep3_user_manager.rs). Orders route as the account's participant, not the session user (rs/order-gateway/src/rest_service.rs, Ep3Identity::resolve).

• EP3 has exchange-level self-match scopes. The production settings, as read on 2026-03-31:

  selfMatchPreventionClearingMemberFirm: false
  selfMatchPreventionParticipantFirm:    false
  selfMatchPreventionAccount:            true
  selfMatchPreventionParticipant:        true
  selfMatchPreventionBeneficialOwner:    false

  Thus the scope of prevention today is the single account. Two users on one account are prevented. One user on two accounts is not. Two accounts of one customer or one UBO are not.

• The per-order self_trade_prevention field only selects the outcome of a prevented match: cancel the aggressor (default), cancel the resting order, or cancel both. It does not set the scope. The gateway sends self_match_prevention_instruction and never sends self_match_prevention_id.

• ep3-mock matches on the participant only (rs/ep3-mock/src/order_entry_service.rs, find_self_trade_orders). The STP battery (rs/sdk-internal/test-batteries/src/stp_scenarios/) tests one account and two unrelated accounts. It has no related-account case.

• On the Bitnomial edition the venue owns prevention. This SoW does not apply there.

The model

Prevention scope is an explicit key, not a customer, user, or UBO:

customer -> self_trade_prevention_group -> trading_account

An account with no group keeps today's behavior. Accounts in the same group are prevented against each other in addition to themselves. Accounts in different groups, or with no group, can trade against each other even when the customer is the same.

This is the same shape as margin groups and for the same reason. Common ownership does not decide risk pooling, and it does not decide prevention scope. TTG and Blockhouse are both "one customer with several accounts".

Decisions

1. The key is explicit. customer_id does not imply a group. AX assigns groups.
2. No group is the default. The schema adds no group rows. Behavior for every existing account is unchanged.
3. One account has at most one group. The venue compares one key per order. A column carries it; there is no membership table.
4. A group belongs to one customer. Every member account has the group's customer_id. A group across two customers (one UBO, two onboarded entities) is refused in this release. See open question 1.
5. A customer can own several groups. A customer with pods of two accounts each gets one group per pod.
6. AX sets groups. Customers do not. Removing prevention between the accounts of one firm is a market-abuse control. A customer manager can see the group of each account and cannot change it.
7. A second account requires an explicit choice. When AX creates an account for a customer that already owns one, the operator must name a group or state that the account is independent. There is no silent default for the second account.
8. A membership change requires no open orders on the account. The route refuses otherwise, or cancels them when the operator asks. This removes the question of what key a resting order carries.
9. The per-order instruction keeps its meaning inside a group. An aggressor on account A with CancelResting cancels the resting order on account B. A trader on A can therefore cancel B's order without a grant on B. This is accepted: the customer asked for A and B to act as one book for prevention. Record it in the customer notice.
10. Independent accounts stay under surveillance. A customer with ungrouped accounts can self-cross. Surveillance treats those crosses by customer_id, not by group. This SoW does not build that; it must not hide it.

Venue mechanism

EP3 gives two candidate mechanisms. Stage 0 tests both on ep3-dev and picks one. Everything after stage 0 depends only on this contract:

The venue key of an account is its self_trade_prevention_group_id, or nothing. Two orders with the same non-empty venue key do not match.

Candidate 1: per-order self-match prevention ID (preferred if it works)

The gateway sets InsertOrderRequest.self_match_prevention_id to the account's self_trade_prevention_group_id, and leaves it empty for an account with no group. FIX tag 7928 has the same meaning. The exchange-level account and participant scopes stay on and still cover the single account.

• No venue configuration change and no venue restart.
• One source of truth. trading_accounts is already on the order-gateway replica, so the key is a field read on the order path.
• A change takes effect on the next order. Decision 8 covers resting orders.
• CancelReplaceOrderRequest has no ID field. Stage 0 must show that a replacement keeps the original order's ID.
• Unknown: whether EP3 compares IDs across two participants. On 2026-04-02 an ID made prevention work on ep3-dev while the exchange-level scopes were off, but the test used one participant.

Candidate 2: beneficial-owner scope

This is the idea in the original accounts proposal ("use the EP3 Legal Entity Identifier as a self-trade identifier"). An EP3 account carries beneficial_ownership, a list of UserAttributes. Each entry has legal_entity_identifier and ownership_key. The proto comment on ownership_key says that equal keys on two accounts mark the accounts as related. AX writes the self_trade_prevention_group_id to one entry per grouped account with UpdateAccount, and turns on selfMatchPreventionBeneficialOwner.

• The venue enforces it on every order path, including resting orders.
• The flag change needed a restart of ep3-dev (5 to 10 minutes). Production needs a maintenance window.
• State lives in two places. A reconciler must compare Postgres and EP3.
• UpdateAccount takes a whole Account. The writer must read, change one field, and write, or it can clear fields that provisioning set.
• Unknown: which field the scope compares (ownership_key, the identifier, or the whole entry), and whether two accounts with no entry count as equal. If empty equals empty, turning the flag on would prevent every account against every other account. The safe form then writes a key on every account: the group id, or the account's own id.
• Use ownership_key, not the identifier, if both work. The identifier is a real regulatory field.
• SetAssociatedAccounts with SHARED_BENEFICIAL_OWNERSHIP is a third place the scope could read. Stage 0 checks it.

Do not set client_account_id on orders under either candidate. Connamara confirmed on 2026-06-02 that a different client_account_id on the same base account disables account-level prevention (omnibus behavior).

Schema

CREATE TABLE self_trade_prevention_groups (
    id CHAR(16) PRIMARY KEY,
    customer_id CHAR(16) NOT NULL REFERENCES customers(id),
    name TEXT NOT NULL,
    created_by_user_id CHAR(16) REFERENCES users(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX self_trade_prevention_groups_customer_id_idx ON self_trade_prevention_groups (customer_id);

ALTER TABLE trading_accounts
    ADD COLUMN self_trade_prevention_group_id CHAR(16) REFERENCES self_trade_prevention_groups(id);
CREATE INDEX trading_accounts_self_trade_prevention_group_id_idx ON trading_accounts (self_trade_prevention_group_id);

Invariants that a CHECK cannot reach. The write paths enforce them and a recon check reports violations:

• A grouped account and its group have the same customer_id.
• A system account has no group.
• An account with no EP3 identity has no group.
• Under candidate 2 only: the EP3 account's key equals the venue key.

No backfill. trading_accounts is already on every logical replication publication, so the column reaches order-gateway with no publication change. self_trade_prevention_groups is read from Postgres directly; it is not on the order path.

Routes and CLI

POST   /admin/customers/{id}/self-trade-prevention-groups   { name } -> group
GET    /admin/customers/{id}/self-trade-prevention-groups   -> [group + accounts]
DELETE /admin/self-trade-prevention-groups/{id}             -> 204 (empty group only)
PUT    /admin/accounts/{id}/self-trade-prevention-group
       { self_trade_prevention_group_id | null, cancel_open_orders }

Rules on PUT /admin/accounts/{id}/self-trade-prevention-group:

• The group's customer must equal the account's customer. Else 409.
• The account must have no open orders, unless cancel_open_orders is true. Then the route cancels them and waits for the venue to confirm before it writes.
• The write records the acting user.
• Under candidate 2 the route writes EP3 first and Postgres second, and is safe to retry.

POST /admin/accounts (create account): when the customer already owns an account, the request must carry self_trade_prevention_group_id or self_trade_prevention_independent: true. Else 400 with a message that names the choice.

The admin CLI gains self-trade-prevention-groups create, self-trade-prevention-groups list, accounts set-self-trade-prevention-group, and self-trade-prevention-groups report. The report lists every customer with two or more accounts, the group of each account, and the accounts with no group. Compliance reviews it.

GET /whoami account entries and GET /customer/accounts carry self_trade_prevention_group (the group id and name, or null). The public SDK describes it as "accounts in the same group do not trade against each other". It names no venue field.

Order gateway

Candidate 1: prepare_ep3_insert_order_request takes the account's venue key and sets self_match_prevention_id. The replica struct for trading_accounts gains self_trade_prevention_group_id. No other order path inserts customer orders.

Candidate 2: no order-path change.

Both: the reject and cancel texts for a prevented match say "your own resting order" (rs/order-gateway/src/exchange_reject.rs). Change them to name a related account when the resting order is on a different account, without naming that account to a user who has no grant on it.

Mock and tests

ep3-mock models the chosen mechanism, so CI tests the same contract as the venue. find_self_trade_orders matches on the same participant or the same non-empty venue key.

The STP battery gains a cross_account section. It runs against ep3-mock in CI and against a live venue from the admin CLI, as the battery does today. This is the W5.5 acceptance:

• Two accounts in one group: the aggressor is rejected under the default instruction. CancelResting and CancelBoth act on the other account's order. Repeat through cancel-replace.
• Two accounts of one customer with no group: the orders fill.
• Two accounts of one customer in different groups: the orders fill.
• One user with grants on two ungrouped accounts: the orders fill. One user with grants on two grouped accounts: prevented.
• Two users on one account: prevented, with and without a group.
• An unrelated counterparty fills against a grouped account.
• Add an account to a group: prevention starts on the next order. Remove it: prevention stops. Both with the open-order rule.
• After client disconnect, server disconnect, order-gateway restart, and reconnect, the same results hold. A gateway whose replica has not yet seen a membership change uses the old key; measure and record the delay.

Delivery

0 ── A ── B ── C ── D

Stage 0 needs no schema and can start now. Rollout: sandbox, then demo with the live battery, then production. Candidate 2 adds a production maintenance window before C is usable.

Record the stage 0 result and the first production group as the D3 self-trade evidence in the master SoW decision record.

Until this ships

AX can create a second account for a customer. The accounts can trade against each other. Before it does so, AX asks the customer which shape they are and tells them in writing that AX does not prevent crosses between the accounts yet. A one-firm customer must prevent crosses on their side until stage C.

Do not give two AX accounts the same EP3 participant or EP3 account to get prevention early. One AX account to one EP3 identity is an invariant of order routing, event routing, positions, and reconciliation.

Out of scope

• Prevention on the Bitnomial edition.
• Customer-editable groups.
• Groups that follow an account family automatically. A family is a likely group, and AX can set it so, but the parent pointer does not imply it.
• Margin groups. A self-trade prevention group and a margin group are independent keys. A cross-account margin group will likely require a self-trade prevention group; that rule belongs to Margin groups.
• Fee tiers and promotions across a customer's accounts.
• Surveillance of crosses between ungrouped related accounts, and the entity-relationship model for it.

Open questions

1. One UBO can own two onboarded customers. Should a group span them? The venue key allows it. Decision 4 refuses it until Compliance asks for it.
2. Which shape is Blockhouse?
3. Does Compliance need a stated reason on file for each independent multi-account customer, and where does it live?
4. Should liquidation orders carry the venue key? Under candidate 1 the gateway can omit it, so that a liquidation can cross a sibling account. Under candidate 2 it cannot.