Account tiers — margin call, stop out and leverage caps

An account tier is a row in fx_account_group. It decides, for every account assigned to it, when the customer gets a margin call, when the engine starts force-closing their positions, whether a negative balance is written off, and how much leverage they may reach.

Three other pages in this documentation tell you to create one, and the production checklist makes "at least one account group exists, with a defaultForType for LIVE" a gate on going live. This page is how you actually do it, because the answer is not what you expect.

What the admin panel does give you

Two read-only option endpoints, and one place to use them.

Both do a plain findAll of id and name ordered by name, and both prepend a sentinel entry — No group on the account form, Any account group (wildcard) on the routing-rule form. Neither can create a row.

So once a tier exists in the table it is immediately pickable in two places:

• Admin → Forex Trading → Trading → Accounts, edit an account, the Risk controls group, the Account group field.
• Admin → Forex Trading → Execution → Routing Rules, as the accountGroupId match dimension on an A-book rule.

The six columns

Plus id (CHAR(36), the primary key) and the createdAt / updatedAt timestamps, all three of which your INSERT has to supply.

The defaults in that table are model defaults, applied by the ORM. A raw SQL INSERT that omits a column gets the column's DDL default, which for a table created by model sync is the same value — but be explicit anyway and write every column.

Margin level is equity / usedMargin × 100. At 100% the customer's equity exactly covers their requirement.

An account with no tier

groupId on fx_account is nullable, and nothing seeds a tier. An account whose groupId is NULL — or which points at a row you have since deleted — falls back to:

That is a workable ESMA-ish default and it is why an install with no tiers still behaves sanely. It is a fallback, not a decision: nobody chose those numbers for your book, and the missing leverage cap means the account's own leverage value and the symbol group's cap are the only two limits in play.

Creating a tier

negativeBalanceProtection is a TINYINT(1): write 1 for on and 0 for off. NULL also means on — the risk engine only skips the write-off when the column is explicitly false, so leaving it null does not disable protection.

Auto-assignment, and the two-defaults trap

When a customer creates an account, the backend resolves the tier with:

const group = await models.fxAccountGroup.findOne({
  where: { defaultForType: type },
});

There is no ORDER BY, and name is the only unique column in the table — nothing stops two rows both carrying defaultForType = 'LIVE'. When that happens MySQL is free to return either one, and which tier a new customer lands in becomes arbitrary and can differ between two accounts created a minute apart.

The auto-provisioned demo account created on a customer's first visit to the terminal resolves the same way, against defaultForType = 'DEMO'.

Keep at most one row per type, and check it after every edit:

SELECT `defaultForType`, COUNT(*)
FROM `fx_account_group`
WHERE `defaultForType` IS NOT NULL
GROUP BY `defaultForType`;

Assigning a tier to an existing account

This part is available from the admin panel, and it is the only tier operation that is.

Admin → Forex Trading → Trading → Accounts, the row's edit action, Risk controls → Account group. The endpoint accepts groupId and verifies the row exists before writing; an id that matches nothing is refused with "groupId does not reference an account group".

To take an account out of every tier, pick the No group entry. The literal string "none" is the sentinel the endpoint converts to NULL (an empty string does the same). That account then falls back to 100 / 50 with no tier leverage cap.

Balance never changes here — that is the separate reason-coded adjustment action, which writes an ADJUSTMENT deal. See Running the desk.

Bulk moves are not offered in the UI. Reassigning many accounts at once is SQL:

UPDATE `fx_account`
SET `groupId` = 'THE-TIER-V4-UUID', `updatedAt` = NOW()
WHERE `id` = 'THE-ACCOUNT-UUID';

Effective leverage is the minimum of three numbers

effectiveLeverage = min(
  fx_account.leverage,           the per-account knob, 1..3000
  fx_symbol_group.leverage,      the instrument's group cap
  fx_account_group.maxLeverage   the tier cap
)

Values that are absent, non-numeric or below 1 are ignored rather than treated as zero, so an account with no tier is simply capped by the other two. If none of the three is usable the engine falls back to 1.

This is why a tier edit is not a small change: used margin on positions that are already open is recomputed from the current effective leverage on every sweep. The usedMargin column on fx_position is a bookkeeping snapshot taken at open and is explicitly not what the account's margin requirement is calculated from.

Changing a live tier

Every field is read fresh from the database on each sweep; nothing is cached in the engine.

Raising stopOutLevel (say 20 → 50) liquidates earlier and reduces the deficit you can be left with. Lowering it lets customers run closer to zero and puts more of the tail risk on you, which is exactly what negative-balance protection then pays for.

Renaming and deleting

name is unique, so a rename is a plain UPDATE that fails loudly on a collision. Nothing else references a tier by name.

Deleting is SQL too, and there is no guard of any kind — no route refuses it, nothing checks whether accounts or routing rules still point at the row:

SELECT COUNT(*) FROM `fx_account` WHERE `groupId` = 'THE-TIER-UUID';
SELECT COUNT(*) FROM `fx_routing_rule` WHERE `accountGroupId` = 'THE-TIER-UUID';

The association declares ON DELETE SET NULL, so accounts in a deleted tier lose their groupId and drop to the 100 / 50 fallback with no leverage cap — which for an offshore tier is a tightening and for a 30x ESMA tier is a loosening. Reassign the accounts first, then delete the empty row.

An A-book routing rule whose accountGroupId points at a deleted tier stops matching anything, silently. Check the second query above before deleting, and re-point the rule.

Where the levels surface

• The customer is notified at the margin-call level through the FxTradingMarginCall template, and at each forced close through FxTradingStopOut.
• The account's expanded view in Trading → Accounts shows the tier name, its margin-call level and its stop-out level alongside the live margin level.
• Admin → Forex Trading (the risk desk) lists accounts near stop-out, which is measured against each account's own tier.

Next

• Instruments, groups and sessions — symbol groups, the other half of the leverage calculation
• Running the desk — watching the accounts these tiers govern
• Settings and reference — every key and every table