CPlugin
Log in

MT4 v2 :: Margins

API v2 (beta) · MT4 · 3 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.

Operations

List account margins (cached)

GET /api/v2/MT4/{tradePlatform}/MarginsGet

Margin levels for all accounts from the pump cache.

Pump-cached snapshot of margin/equity/free margin per login. Use this for bulk monitoring of account health (margin calls / stop-out proximity). For a single account, prefer the existing MarginLevelGet/MarginLevelRequest endpoints.

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

NameInTypeRequiredDescription
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.

Responses

Example

curl "https://cloud.mywebapi.com/api/v2/MT4/$TRADE_PLATFORM_ID/MarginsGet" \
  -H "Authorization: Bearer $TOKEN"

Get account margin (cached)

GET /api/v2/MT4/{tradePlatform}/MarginLevelGet/{login}

Margin level for a single account from the pump cache.

Pump variant — two-step lookup: UserRecordGet to resolve the account's group, then MarginLevelGet(login, group). Returns NotFound envelope if the account is unknown or has no open trades. For a live round-trip use MarginLevelRequest.

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

NameInTypeRequiredDescription
tradePlatform path string (uuid) yes Trade platform id (GUID)
login path integer (int32) yes Account login (positive integer)
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.

Responses

Example

curl "https://cloud.mywebapi.com/api/v2/MT4/$TRADE_PLATFORM_ID/MarginLevelGet/$LOGIN" \
  -H "Authorization: Bearer $TOKEN"

Get account margin (live)

GET /api/v2/MT4/{tradePlatform}/MarginLevelRequest/{login}

Margin level for a single account — live round-trip to MT4 server.

Manager variant — bypasses the pump cache and asks the MT4 server directly. Slower than MarginLevelGet but always fresh. Cost- equivalent to other live Manager calls (billed per request, unlike pump reads).

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

NameInTypeRequiredDescription
tradePlatform path string (uuid) yes Trade platform id (GUID)
login path integer (int32) yes Account login (positive integer)
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.

Responses

Example

curl "https://cloud.mywebapi.com/api/v2/MT4/$TRADE_PLATFORM_ID/MarginLevelRequest/$LOGIN" \
  -H "Authorization: Bearer $TOKEN"

Schemas

Types the operations above take and return, with their first-level properties; * marks a required one. The full graph is in the OpenAPI specification.

MT4MarginLevelListApiResponse

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.

PropertyTypeDescription
data MT4MarginLevel[]
error 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.
meta 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.

MT4MarginLevelApiResponse

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.

PropertyTypeDescription
data MT4MarginLevel v2 DTO mirroring the wrapper's MarginLevel record. All fields are kept because clients monitoring margin call / stop-out conditions need the complete state. ControllingType and LevelType remain as MT4 enums and serialize as string names via the V2JsonContext UseStringEnumConverter option (e.g. "Percent" rather than 0).
error 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.
meta 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.

MT4MarginLevel

v2 DTO mirroring the wrapper's MarginLevel record. All fields are kept because clients monitoring margin call / stop-out conditions need the complete state. ControllingType and LevelType remain as MT4 enums and serialize as string names via the V2JsonContext UseStringEnumConverter option (e.g. "Percent" rather than 0).

PropertyTypeDescription
login integer (int32) Trading account number
group string, nullable Group the account belongs to
leverage integer (int32) Account leverage (e.g. 100 means 1:100)
updated integer (int32) Last update timestamp (MT4 unix-time int)
balance number (double) Account balance (deposit minus losses)
equity number (double) Equity (balance + floating P&L)
volume integer (int32) Open volume across all positions
margin number (double) Used margin
free number (double) Free margin (equity − margin)
level number (double) Margin level in % (equity / margin × 100)
controllingType MarginControllingType Whether margin is controlled by percentage or currency
levelType MarginLevelType Indicates margin call / stop-out state

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.

PropertyTypeDescription
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.

PropertyTypeDescription
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.