API v2 (beta) · MT4 · 8 operations ·
base URL https://cloud.mywebapi.com ·
OpenAPI v2 (JSON) ·
Redoc
Every call needs Authorization: Bearer $TOKEN — an OAuth 2.0 client-credentials token from
https://auth.cplugin.net/connect/token (scope webapi).
$TRADE_PLATFORM_ID is the id of a trade platform registered in Toolbox.
All trading groups configured on the MT4 server from the pump cache.
Pump-cached read. Curated DTO drops SMTP credentials, template paths,
and nested SecGroups/SecMargins arrays (those get dedicated v2
endpoints in a later wave). Typical group counts are small (dozens),
so no pagination is needed.
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
Trade platform id (GUID)
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 10 s (read). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
GET /api/v2/MT4/{tradePlatform}/GroupRecordGet/{group}
Single trading group configuration by name (pump-cached).
Pump-cached lookup. Returns NotFound envelope if no group with the
given name exists. Group names are case-sensitive — the wrapper does
an exact dictionary lookup.
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
Trade platform id (GUID)
group
path
string
yes
Group name (max 16 chars)
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 10 s (read). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
Manager (live) call returning a paged list of all configured groups on the platform. Sort key is the group name (string, ordinal compare) ascending. Cursor is the last returned group name encoded as opaque base64.
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
limit
query
integer (int32)
no
Maximum number of items to return in one page. Omit to return all items in a single page. Maximum allowed value is 5000.
cursor
query
string
no
Opaque continuation token. Pass the value from the previous response's meta.paging.nextCursor to fetch the next page; omit for the first page.
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 10 s (read). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
GET /api/v2/MT4/{tradePlatform}/GroupSecGroupsGet/{group}
Security-group entries (SecGroups[32]) for one trading group.
Pump-cached read. Returns the full 32-element array; entries whose
Trade and Show are both 0 are placeholders (the wrapper
reserves the slot for the symbol-group regardless of whether the
group is configured to trade it). Filter on the client side.
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
Trade platform id (GUID)
group
path
string
yes
Group name (max 16 chars)
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 10 s (read). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
GET /api/v2/MT4/{tradePlatform}/GroupSecMarginsGet/{group}
Special-securities margin overrides (SecMargins) for one group.
Pump-cached read. Returns the first SecMarginsTotal entries of
the wrapper's 128-element SecMargins array — the trailing
slots are always uninitialised padding. SecMarginsTotal itself
is part of the parent MT4Group DTO.
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
Trade platform id (GUID)
group
path
string
yes
Group name (max 16 chars)
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 10 s (read). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
POST /api/v2/MT4/{tradePlatform}/GroupRecordUpdate/{group}
Update a group configuration — Type 1 mutator with secret-preservation read.
Same flow as UserRecordUpdate: read the existing
ConGroup from the MT4 server, overlay the
MT4GroupUpdate DTO over the in-memory record, write the
merged structure back. Preserves SMTP credentials, template paths,
SecuritiesHash, reserved arrays, the nested SecGroups/SecMargins
arrays, and NewsLanguages — none of those are on the input DTO so
they survive untouched.
Wraps the wrapper's CfgUpdateGroup — v2 renames to
GroupRecordUpdate for consistency with
UserRecordUpdate; the underlying wrapper call is the same as
v1's POST CfgUpdateGroup endpoint.
Idempotency-Key strongly recommended for safe retries.
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
Trade platform id (GUID)
group
path
string
yes
Group name (path parameter, max 16 chars, immutable identity)
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 15 s (change). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
Request body
MT4GroupUpdate (application/json) — Replacement fields. Omitted-from-DTO fields are preserved server-side.
Type 2 mutator — partial update of a trading group. Same semantics as UserRecordPatch; see that endpoint for the read-merge- write flow and forwards-compat behavior.
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
Trade platform id (GUID)
group
path
string
yes
Group name (immutable identity)
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 15 s (change). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
Request body
object (application/json, required) — JSON Merge Patch: an object with only the fields to change.
GET /api/v2/MT4/{tradePlatform}/EnsureGroupNameExist/{group}
Checks whether a trading group exists on the connected MT4 server. Useful as a validation pre-flight before creating users, moving users between groups, or wiring up automated provisioning.
Manager-live read. The wrapper's EnsureGroupNameExist helper
is internal/private, so this v2 endpoint re-implements the check
directly: enumerate the full group catalog via
GroupsRequest and look up the key. The same Manager request
is incurred either way; there is no cheaper "exists" call in the
MT4 ManagerAPI surface.
Returns true if the group is configured on the server,
false otherwise. Group lookup is case-sensitive (MT4 group
names are case-sensitive in the underlying API).
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.
Parameters
Name
In
Type
Required
Description
tradePlatform
path
string (uuid)
yes
Trade platform id (GUID)
group
path
string
yes
Group name to look up (max 16 chars)
X-Request-Timeout
header
number (double)
no
How long to wait for the trade server, in seconds (1–300). Default for this operation: 10 s (read). The query parameter requestTimeout does the same for clients that cannot set headers. The applied value is returned in the X-Request-Timeout-Applied response header.
Types the operations above take and return, with their first-level properties; * marks a required one. The full graph is in the OpenAPI specification.
MT4GroupListApiResponse
Unified v2 response envelope: data is the payload (null on error); error is the error object (null on success, always serialised); meta contains response metadata (activityId and optional paging). HTTP status is always 200.
v2 error body. Code is the stable transport error code; ManagerCode is the raw MT4 ResultCode (serialized as a string for a known enum member, or as a number for an unrecognised value returned by MT4); Message is a human-readable description.
Response metadata. ActivityId is the W3C trace-id for correlation in Seq/SigNoz. Paging is present only on paginated list responses; otherwise it is omitted — the global JSON context policy serialises null fields, so we override that here with System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull.
MT4GroupApiResponse
Unified v2 response envelope: data is the payload (null on error); error is the error object (null on success, always serialised); meta contains response metadata (activityId and optional paging). HTTP status is always 200.
v2 DTO describing a trading group configuration. Curated subset of the wrapper's ConGroup — exposes the configuration fields that callers need to inspect margin/leverage/rights settings. Deliberately omitted from v2 (vs v1's full ConGroup shape): * SmtpServer, SmtpLogin, SmtpPassword — SMTP credentials must never cross the v2 boundary regardless of access level. SmtpServer alone is dropped too because a server name is rarely useful without its credentials and exposes infra topology. * Templates — server-side filesystem path, irrelevant to API consumers and a minor information-disclosure risk. * SecuritiesHash — opaque byte[], wrapper bookkeeping. * Reserved, UnusedRights, SecGroups[32], SecMargins[128] — reserved/internal arrays. The two nested arrays (SecGroups, SecMargins) deserve their own dedicated v2 endpoints (GroupSecGroupsGet/{group}, GroupSecMarginsGet/{group}) planned for Wave 3 — including them here would balloon the DTO. * NewsLanguages (uint[]) and NewsLanguagesTotal — rarely consumed; can be added later once the use case is clear. Enums (OTPMode, MarginMode, NewsMode, MarginControllingType) serialize as strings because CPlugin.SaaSWebApps.WebAPI.Code.Json.V2JsonContext enables UseStringEnumConverter; GroupRights is a flags string, the names of the set bits.
v2 error body. Code is the stable transport error code; ManagerCode is the raw MT4 ResultCode (serialized as a string for a known enum member, or as a number for an unrecognised value returned by MT4); Message is a human-readable description.
Response metadata. ActivityId is the W3C trace-id for correlation in Seq/SigNoz. Paging is present only on paginated list responses; otherwise it is omitted — the global JSON context policy serialises null fields, so we override that here with System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull.
MT4GroupSecListApiResponse
Unified v2 response envelope: data is the payload (null on error); error is the error object (null on success, always serialised); meta contains response metadata (activityId and optional paging). HTTP status is always 200.
v2 error body. Code is the stable transport error code; ManagerCode is the raw MT4 ResultCode (serialized as a string for a known enum member, or as a number for an unrecognised value returned by MT4); Message is a human-readable description.
Response metadata. ActivityId is the W3C trace-id for correlation in Seq/SigNoz. Paging is present only on paginated list responses; otherwise it is omitted — the global JSON context policy serialises null fields, so we override that here with System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull.
MT4GroupMarginListApiResponse
Unified v2 response envelope: data is the payload (null on error); error is the error object (null on success, always serialised); meta contains response metadata (activityId and optional paging). HTTP status is always 200.
v2 error body. Code is the stable transport error code; ManagerCode is the raw MT4 ResultCode (serialized as a string for a known enum member, or as a number for an unrecognised value returned by MT4); Message is a human-readable description.
Response metadata. ActivityId is the W3C trace-id for correlation in Seq/SigNoz. Paging is present only on paginated list responses; otherwise it is omitted — the global JSON context policy serialises null fields, so we override that here with System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull.
MT4GroupUpdate
Type 1 mutator input — full-replace shape for GroupRecordUpdate. Same field set as the read DTO CPlugin.SaaSWebApps.WebAPI.DTOs.MT4.v2.MT4Group minus the immutable group name (path parameter) and the derived SecMarginsTotal (computed from SecMargins length). Fields preserved by the server-side read step (NOT on this DTO): * Group — path param, immutable identity. * SmtpServer, SmtpLogin, SmtpPassword — SMTP creds, never client-controlled. * Templates — server-side filesystem path. * SecuritiesHash — opaque wrapper bookkeeping. * Reserved, UnusedRights — reserved arrays. * SecGroups[32], SecMargins[128] — nested arrays, planned as dedicated v2 endpoints. * NewsLanguages, NewsLanguagesTotal — separate management. * SecMarginsTotal — derived from SecMargins length.
Margin controlling unit (percent vs deposit currency)
archivePeriod
integer (int32)
Inactivity period (days) before account archival
archiveMaxBalance
integer (int32)
Max balance under which an account becomes archivable
stopoutSkipHedged
integer (int32)
0 = include hedged in stop-out checks, non-zero = skip them
archivePendingPeriod
integer (int32)
Pending orders clean-up period (days)
BooleanApiResponse
Unified v2 response envelope: data is the payload (null on error); error is the error object (null on success, always serialised); meta contains response metadata (activityId and optional paging). HTTP status is always 200.
v2 error body. Code is the stable transport error code; ManagerCode is the raw MT4 ResultCode (serialized as a string for a known enum member, or as a number for an unrecognised value returned by MT4); Message is a human-readable description.
Response metadata. ActivityId is the W3C trace-id for correlation in Seq/SigNoz. Paging is present only on paginated list responses; otherwise it is omitted — the global JSON context policy serialises null fields, so we override that here with System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull.
MT4Group
v2 DTO describing a trading group configuration. Curated subset of the wrapper's ConGroup — exposes the configuration fields that callers need to inspect margin/leverage/rights settings. Deliberately omitted from v2 (vs v1's full ConGroup shape): * SmtpServer, SmtpLogin, SmtpPassword — SMTP credentials must never cross the v2 boundary regardless of access level. SmtpServer alone is dropped too because a server name is rarely useful without its credentials and exposes infra topology. * Templates — server-side filesystem path, irrelevant to API consumers and a minor information-disclosure risk. * SecuritiesHash — opaque byte[], wrapper bookkeeping. * Reserved, UnusedRights, SecGroups[32], SecMargins[128] — reserved/internal arrays. The two nested arrays (SecGroups, SecMargins) deserve their own dedicated v2 endpoints (GroupSecGroupsGet/{group}, GroupSecMarginsGet/{group}) planned for Wave 3 — including them here would balloon the DTO. * NewsLanguages (uint[]) and NewsLanguagesTotal — rarely consumed; can be added later once the use case is clear. Enums (OTPMode, MarginMode, NewsMode, MarginControllingType) serialize as strings because CPlugin.SaaSWebApps.WebAPI.Code.Json.V2JsonContext enables UseStringEnumConverter; GroupRights is a flags string, the names of the set bits.
Property
Type
Description
group
string, nullable
Group name (unique per platform, max 16 chars)
enable
integer (int32)
0 = group disabled, non-zero = enabled (accounts in this group can log in)
Margin controlling unit (percent vs deposit currency)
archivePeriod
integer (int32)
Inactivity period (days) before account moves to archive
archiveMaxBalance
integer (int32)
Maximum balance under which an account is eligible for archiving
stopoutSkipHedged
integer (int32)
0 = include hedged accounts in stop-out checks, non-zero = skip them
archivePendingPeriod
integer (int32)
Pending orders clean-up period (days)
ApiError
v2 error body. Code is the stable transport error code; ManagerCode is the raw MT4 ResultCode (serialized as a string for a known enum member, or as a number for an unrecognised value returned by MT4); Message is a human-readable description.
Property
Type
Description
code
WebApiErrorCode
Stable transport-level error code.
managerCode
ResultCode
Raw MT4/MT5 manager result code, when the error came from the trading platform; otherwise null.
message
string, nullable
Human-readable error description.
ApiMeta
Response metadata. ActivityId is the W3C trace-id for correlation in Seq/SigNoz. Paging is present only on paginated list responses; otherwise it is omitted — the global JSON context policy serialises null fields, so we override that here with System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull.
Property
Type
Description
activityId
string, nullable
W3C trace id for correlating this response in logs and tracing (Seq/SigNoz).
paging
PagingMeta
Pagination info; present only on list responses, omitted otherwise.
MT4GroupSec
v2 DTO for one entry in a group's SecGroups array (32 elements indexed by symbol-group). Curated from ConGroupSec; drops the Reserved int[3] padding. Enum fields are typed as string for the leaf-nested-generic STJ source-gen reason — see feedback-stj-enum-leaf-nested.
Property
Type
Description
show
integer (int32)
0 = security group hidden from clients, non-zero = visible
trade
integer (int32)
0 = trading disabled, non-zero = trading enabled
dealingMode
string, nullable
Dealing mode (Manual / Auto / Activity)
standardCommission
number (double)
Standard commission
commissionType
string, nullable
Commission type (Money / Pips / Percent)
commissionLotsMode
string, nullable
Commission lots mode (PerLot / PerDeal)
agentCommission
number (double)
Agent commission
agentCommissionMode
string, nullable
Agent commission type (Money / Pips)
spreadDiff
integer (int32)
Spread difference compared to default symbol spread
lotMin
integer (int32)
Minimum allowed lot size (in 1/100 lot units, e.g. 100 = 1 lot)
lotMax
integer (int32)
Maximum allowed lot size
lotStep
integer (int32)
Lot step (10 lot = 1000, 1 lot = 100, 0.1 lot = 10)
ieDeviation
integer (int32)
Max price deviation in Instant Execution mode
confirmation
integer (int32)
0 = no confirmation, non-zero = request mode confirmation
tradeRights
string, nullable
Clients trade rights bit mask (string-encoded)
ieQuickMode
integer (int32)
0 = normal, non-zero = don't resend on deviation in IE
v2 DTO for one of a group's "special securities" margin overrides. Curated from ConGroupMargin — the wrapper's per-symbol swap/margin overrides stored as a 128-element array on ConGroup.SecMargins. The Reserved int[7] padding is dropped.
Property
Type
Description
symbol
string, nullable
Symbol the override applies to (max 12 chars)
swapLong
number (double)
Swap charge for long positions
swapShort
number (double)
Swap charge for short positions
marginDivider
number (double)
Margin divider override (1.0 = use default)
OTPMode
Values: Disabled, TOTP_SHA256
MarginMode
Values: DontUse, UseAll, UseProfit, UseLoss
NewsMode
Values: No, Topics, Full
GroupRights
Flags: names of the set bits joined by ", " ("Signals, Trailing"), "None" when none is set; a set bit without a name is "Bit<n>" (bit number). Bits: Signals = 0x1, Trailing = 0x2, Advisor = 0x4, Expiration = 0x8, SignalAll = 0x10, SignalsOwn = 0x20, RiskWarning = 0x40, ForcedOTPUsage = 0x80.
