MT4 v2 :: Users

Account record for a single login from the pump cache.

Pump-cached read of the wrapper's UserRecord, mapped to the v2 MT4User DTO. Secrets (passwords, OTP secret, API blob) are stripped at the mapper level — they cannot be exposed via this endpoint regardless of caller permissions. Returns NotFound envelope when the pump cache does not contain the requested login.

Timeout: 10 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: Nothing was changed; the request is safe to repeat.

Account record for a single login — live round-trip to MT4 server.

Manager variant — bypasses the pump cache and asks the MT4 server directly via UserRecordsRequest with a single-login array. Slower than UserRecordGet but guarantees fresh data (just changed group, balance fix, etc). Same curated DTO, same security guarantees — passwords/OTP/API blob never cross the boundary.

Timeout: 10 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: Nothing was changed; the request is safe to repeat.

Account records for a list of logins — live round-trip to MT4 server.

Manager batch variant. Pass logins as repeated query parameters: ?logins=1001&logins=1002&logins=1003. Server-side billing counts this as one Manager request regardless of the array length — prefer batch over a loop of single-login calls.

Order in the response is not guaranteed to match the request — the wrapper returns a dictionary. Missing logins are silently omitted; the envelope is not an error envelope in that case.

Timeout: 10 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: Nothing was changed; the request is safe to repeat.

Admin balance integrity check for a single account.

Manager (live) call. Returns the difference between the recorded account balance and what the MT4 server recomputes from closed orders + balance operations. diff = 0 → balance is intact; non-zero → admin tooling can run AdmBalanceFix to recompute (forthcoming Wave 3 endpoint).

Read-only operation despite the wrapper's "Adm" prefix (the prefix signals the elevated authorization requirement, not a write side effect).

Timeout: 10 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: Nothing was changed; the request is safe to repeat.

Admin balance integrity check for a batch of accounts.

Same semantics as the single-login variant but takes a list of logins via repeated query parameters: ?logins=1001&logins=1002. One billed Manager request regardless of the array length. The response list contains entries only for accounts the server flagged with a non-zero diff — clean accounts are silently omitted. Clients should treat "missing from response" as "diff = 0".

Timeout: 10 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: Nothing was changed; the request is safe to repeat.

Admin balance fix — recompute balances for the given logins.

POST mutator. Asks MT4 server to take the diffs reported by AdmBalanceCheck and write them onto the accounts. Empty body — the logins are submitted as repeated query parameters (?logins=1001&logins=1002) to keep the URL shape parallel with the read variant and avoid the awkward "POST with int[] body" pattern.

This DOES modify account balances. Pair every retry with an Idempotency-Key header; otherwise a retried fix can double- apply on an account whose original fix happened to land but whose response was lost on the wire.

Timeout: 5 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: The operation may still be completed by the server (X-Request-Outcome: unknown): check its result before repeating it.

Manager (live) call returning a paged list of every account on the platform. When ?limit= is omitted the response contains all users in one page (back-compat). Set ?limit=N to bound page size; the response's paging.nextCursor drives the next call.

Wrapper-side this still fetches the full users dictionary — paging reduces only the wire payload, not MT4 server load. Items are sorted by login ascending; pages are stable across concurrent inserts as long as the new login is greater than the previous page's last login.

Timeout: 10 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: Nothing was changed; the request is safe to repeat.

Create a new account — Type 1 mutator.

POST mutator. Pass the full MT4UserCreate DTO. Set Login = 0 to let MT4 server assign the next free id, or request a specific id by setting Login > 0 (the server rejects collisions with an MT4 error envelope).

The wrapper accepts the account with empty password bytes; clients MUST follow up with POST UserPasswordSet/{login} before the account is usable.

Idempotency-Key strongly recommended — a retried create without it can land twice when the original response was lost on the wire, burning a second login id from the broker's sequence.

Timeout: 15 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: The operation may still be completed by the server (X-Request-Outcome: unknown): check its result before repeating it.

Update an account record — Type 1 mutator with secret-preservation read.

Surface-level Type 1 semantics: client submits the full MT4UserUpdate DTO and the server writes it back. Implementation requires an extra read step because the wrapper UserRecord struct contains secret/computed/read-only fields the v2 input DTO deliberately omits (Password, OTPSecret, LastDate, etc.). Without the read step those would be zeroed out by the write.

Flow:

• Fetch the existing record via UserRecordsRequest (live, not pump cache).

• Apply the DTO over the in-memory record using ApplyTo. Secrets and read-only fields are [MapperIgnoreTarget]'d so they survive.

• Write the modified record back via UserRecordUpdate.

This is NOT Type 2. Type 2 mutators (single-field) are deferred to a later release and will accept just the field name + value, doing the read-modify-write entirely server-side. Both flows happen to use the same read-modify-write structure on the implementation side — the difference is what the client submits.

Idempotency-Key is strongly recommended; without it a retried update risks silently overwriting concurrent edits that happened between the original send and the retry.

Timeout: 15 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: The operation may still be completed by the server (X-Request-Outcome: unknown): check its result before repeating it.

Type 2 mutator — partial update of a user record. Client sends a JSON object containing only the fields to change; the server reads the current record live from MT4 (Manager, not pump), overlays the patch, and writes back. Echoes the merged record.

Unknown keys in the patch body are silently ignored (forwards-compat). Field-level validation is delegated to MT4 server — invalid values surface as MT4Error envelopes. Secret-preservation and computed-field protection are handled by the existing Type 1 ApplyTo mapper's ignore list.

Timeout: 15 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: The operation may still be completed by the server (X-Request-Outcome: unknown): check its result before repeating it.

All user accounts in a given group (admin scope) — the safe variant that honors permission checks server-side.

Manager (live) call. Returns the curated MT4User projection for every account in the specified group. The wrapper's "Safe" suffix indicates it runs through RunSafe with the Admin rights guard — a manager lacking that permission receives a sensible error rather than a connection drop.

Comma-separated group lists are accepted by the wrapper (it strips commas and trims whitespace internally); the simplest call pattern is a single group name. Large groups may return substantial payloads — pair with Idempotency-Key on retry.

Timeout: 30 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: Nothing was changed; the request is safe to repeat.

Opens a server-side incremental sync session for user records modified at or after timestamp.

Manager-live POST (modifies server-side session state). The wrapper supports a follow-up UsersSyncRead call that drains the snapshot, but the read-side endpoint is currently deferred under wine x64 (see deferral note above this method). Pass timestamp=0 to request all user records.

timestamp is Unix epoch seconds (int32) in MT4 server-local time, not UTC. Returns a bare success envelope.

Timeout: 60 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: The operation may still be completed by the server (X-Request-Outcome: unknown): check its result before repeating it.

Bulk operation on a list of account logins — change group, leverage, enable/disable, or delete in a single Manager round-trip.

Manager (live) call. Wraps UsersGroupOp(GroupCommandInfo, ICollection<int>). The body specifies the command and its parameter (NewGroup for SetGroup, Leverage for Leverage; both ignored for Delete/Enable/ Disable) plus the list of target logins. The wrapper auto-fills the internal Len field from the logins array — clients do not set it.

Wine x64 safe: the wrapper uses AllocArraySafe on the int login array (single contiguous pack, no UnpackObject loop) and AllocSafe on the GroupCommandInfo struct.

Requires Manager or Administrator access rights on the manager account; the wrapper enforces this server-side. Idempotency-Key strongly recommended — bulk Delete / SetGroup operations are destructive on customer-visible state.

Timeout: 60 s by default, adjustable per request with the X-Request-Timeout header. When the trade server does not answer in time: The operation may still be completed by the server (X-Request-Outcome: unknown): check its result before repeating it.