Pre-provisioning the account pool

A customer's first visit to /forex/dashboard provisions whatever accounts they are missing, and it does that one of two ways: it claims an unowned row from a pool, or it creates an empty one. The first path hands them working MetaTrader credentials immediately. The second hands them an account they can fund and invest with but cannot trade on, and which their dashboard labels Pending.

Keeping the pool stocked is therefore an ongoing operational job, and it cannot be done from the admin screen. This page is how it is actually done.

What claiming actually does

GET /api/forex/account is the dashboard's read, and it writes. For each of DEMO and LIVE that the customer does not already hold, it opens a transaction and:

Three properties of that lookup decide how you build the pool:

• There is no ordering. Which row a given customer gets is arbitrary. You cannot reserve a specific account for a specific customer this way.
• There is no quality filter. A pool row is claimed whether or not it has a broker, a login or a password — and it is switched active either way. A half-filled row is worse than no row, because the customer gets Deposit, Withdraw and Trade buttons and a terminal that will not connect.
• status on the pool row is overwritten on claim, so its seeded value only matters while the row is unclaimed. Seed it 0 so an unclaimed row cannot be mistaken for a live customer account when you filter the accounts table by status.

Two pools, matched on type

DEMO and LIVE are separate pools and are never substituted for each other. Stock both.

Only the LIVE branch is gated: a customer whose verification level does not carry the create_forex_account KYC feature has LIVE provisioning skipped entirely — no claim, no fallback create. The skip is silent and does not fail the request, so that customer still gets their DEMO account and still sees any account they already hold. Tightening your levels can never lock an existing customer out of a balance they already have.

Why the admin form cannot do it

POST /api/admin/forex/account (create.forex.account) does two things that rule it out as a pool builder:

• The create form's first field group, Account Owner, marks userId required, and the handler's duplicate check reads findOne({ userId, type }).
• If that user already holds an account of that type, the request is refused with a 409 naming the existing account — That user already has a LIVE forex account ({accountId}). Edit it instead — a second one would split their balance across two rows.

The edit form has no owner field at all, so you cannot un-assign an existing account into the pool either. Both are deliberate: every lookup in the addon reads this user's LIVE account with no ordering, so a second row makes it arbitrary which one is debited, credited or refunded.

The row to insert

forex_account is paranoid, so it carries a deletedAt. createdAt and updatedAt are NOT NULL with no database default and must be supplied.

INSERT INTO forex_account
  (id, userId, accountId, password, broker, mt, type, status,
   balance, leverage, createdAt, updatedAt)
VALUES
  (UUID(), NULL, '51234567', 'Str0ngPass', 'YourBroker-Live01', 5, 'LIVE', 0,
   0, 1, NOW(), NOW());

Everything else has a usable default: currency and walletType are NULL, dailyWithdrawLimit is 5000, monthlyWithdrawLimit is 50000, both withdrawn counters are 0 and both window anchors are NULL.

The withdrawal caps are the one thing worth reviewing per pool. They are compared against the raw amount in the account's own currency, not dollars, so the defaults mean five thousand BTC on a BTC-denominated account — no cap at all. See Accounts.

Monitoring the pool

There is no pool tile on the forex dashboard and no "unowned" filter on the accounts table, so count the rows directly. Run this before any campaign, launch or marketing push:

SELECT type, COUNT(*) AS available
FROM forex_account
WHERE userId IS NULL
  AND deletedAt IS NULL
GROUP BY type;

deletedAt IS NULL is not optional — a soft-deleted row is invisible to the claim query and would otherwise inflate the count.

The unowned rows do appear in /admin/forex/account, with an empty User column, because the list joins the user table without requiring a match. That is a useful eyeball check; it is not a count.

The dry-pool symptom

When the pool for a type runs out, nothing fails and nothing is logged. The customer silently gets the fallback account, and this is what they see on /forex/dashboard:

• A Pending badge where the account type would be.
• Waiting for admin approval, with a spinner, where the account number and password would be.
• A single Check status button. No balance, no leverage, no Deposit, no Withdraw, no Trade, and no expandable account details.

That state is driven purely by status being false. To rescue a stranded customer, open their row at /admin/forex/account, fill in accountId, broker and mt from your broker's back office, and turn the status on. The backend money routes never check status, so nothing was blocked server-side — the customer simply had no way to reach the buttons.

The password is the one field you cannot supply there. It is on neither the edit form nor the create form, and it is not a table or view column either — the form offers accountId, broker, mt, type, balance, leverage and status, plus userId on create, and nothing else. PUT /api/admin/forex/account/{id} does still accept a password of 6 to 191 characters, so setting one means an API call or the same UPDATE forex_account you would use to build a pool row. Skip it and you have handed the customer an active account whose Trade screen shows an empty password — the credential they have to type into MetaTrader themselves.

Deleting an account does not clean up after it

Deletion on the accounts table is unguarded, and an investment references the customer, not the account. Settlement then looks for this user's LIVE forex account, finds nothing, and:

• rolls back its transaction and skips the payout,
• broadcasts LIVE forex account not found for user {id} to the processForexInvestments live log at /admin/system/cron — and only there, so it does not appear in the backend log,
• leaves the investment ACTIVE, so it is retried on every subsequent hourly tick and never completes.

The cron's own terminal-failure path has the same hole: an investment it gives up on after three retries cannot be cancelled either, because the principal refund has nowhere to land. It is left ACTIVE and the backend log records ALERT: cannot refund investment {id} (no LIVE forex account for user {id}) under FOREX_INVESTMENT_PROCESS. That ALERT string is the one thing worth grepping for after any account deletion.

Next: Accounts for what each field on the row does once a customer owns it, or The admin screens for the rest of the back office.