MT4 v2 :: Backup

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

GET /api/v2/MT4/{tradePlatform}/BackupInfoUsers/{mode} — List user backup files
GET /api/v2/MT4/{tradePlatform}/BackupInfoOrders/{mode} — List order backup files
GET /api/v2/MT4/{tradePlatform}/BackupRequestUsers/{file} — Read users from backup
GET /api/v2/MT4/{tradePlatform}/BackupRequestOrders/{file} — Read orders from backup

List user backup files

GET /api/v2/MT4/{tradePlatform}/BackupInfoUsers/{mode}

List backup user files available on the MT4 server for a given mode.

Manager (live) call to the wrapper's BackupInfoUsers(int mode). Returns the catalog of backup files (filename, size, mtime) — does NOT touch the files themselves. Read-only operation: safe to call repeatedly.

mode is the server-defined backup mode selector (typical values: 0 = daily, 1 = weekly — confirm against your server's ConBackup configuration).

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.

Parameters

Name	In	Type	Required	Description
tradePlatform	path	string (uuid)	yes	Trade platform id (GUID)
mode	path	integer (int32)	yes	Backup mode selector (0 = daily, 1 = weekly — server-defined)
X-Request-Timeout	header	number (double)	no	How long to wait for the trade server, in seconds (1–300). Default for this operation: 30 s (history or report). 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

200 Success — MT4BackupInfoListApiResponse

Example

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

List order backup files

GET /api/v2/MT4/{tradePlatform}/BackupInfoOrders/{mode}

List backup order files available on the MT4 server for a given mode.

Manager (live) call to the wrapper's BackupInfoOrders(int mode). Order-side counterpart of BackupInfoUsers — same shape, different catalog. Read-only operation.

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.

Parameters

Name	In	Type	Required	Description
tradePlatform	path	string (uuid)	yes	Trade platform id (GUID)
mode	path	integer (int32)	yes	Backup mode selector (0 = daily, 1 = weekly — server-defined)
X-Request-Timeout	header	number (double)	no	How long to wait for the trade server, in seconds (1–300). Default for this operation: 30 s (history or report). 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

200 Success — MT4BackupInfoListApiResponse

Example

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

Read users from backup

GET /api/v2/MT4/{tradePlatform}/BackupRequestUsers/{file}

Read user records out of a backup file (does NOT restore — read-only).

Manager (live) call to the wrapper's BackupRequestUsers(string file, string request). The wrapper extracts records from the named backup file but does NOT write them back to the live DB — that requires a separate (destructive) BackupRestoreUsers call which is part of Wave 4b.

Use BackupInfoUsers first to discover valid file names. The optional request query is a server-defined filter string; empty string returns all users.

Heavy operation: backup files can contain millions of records — the wrapper returns the full set in one shot. The optional limit query truncates the response server-side (default 10000, max 100000). The wrapper still loads the full file regardless of limit — limit only caps the JSON response size.

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.

Parameters

Name	In	Type	Required	Description
tradePlatform	path	string (uuid)	yes	Trade platform id (GUID)
file	path	string	yes	Backup file name (from BackupInfoUsers)
request	query	string	no	Filter request string (empty = all users)
limit	query	integer (int32)	no	Server-side response cap (1..100000, default 10000)
X-Request-Timeout	header	number (double)	no	How long to wait for the trade server, in seconds (1–300). Default for this operation: 30 s (history or report). 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

200 Success — MT4UserListApiResponse

Example

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

Read orders from backup

GET /api/v2/MT4/{tradePlatform}/BackupRequestOrders/{file}

Read trade records out of a backup file (does NOT restore — read-only).

Manager (live) call to the wrapper's BackupRequestOrders(string file, string request). Order-side counterpart of BackupRequestUsers. Same caveats: read-only, full file loaded server-side regardless of limit, destructive restore is a separate (Wave 4b) operation.

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.

Parameters

Name	In	Type	Required	Description
tradePlatform	path	string (uuid)	yes	Trade platform id (GUID)
file	path	string	yes	Backup file name (from BackupInfoOrders)
request	query	string	no	Filter request string (empty = all orders)
limit	query	integer (int32)	no	Server-side response cap (1..100000, default 10000)
X-Request-Timeout	header	number (double)	no	How long to wait for the trade server, in seconds (1–300). Default for this operation: 30 s (history or report). 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

200 Success — MT4TradeListApiResponse

Example

curl "https://cloud.mywebapi.com/api/v2/MT4/$TRADE_PLATFORM_ID/BackupRequestOrders/$FILE" \
  -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.

MT4BackupInfoListApiResponse

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.

Property	Type	Description
data	MT4BackupInfo[]
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.

MT4UserListApiResponse

Property	Type	Description
data	MT4User[]
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.

MT4TradeListApiResponse

Property	Type	Description
data	MT4Trade[]
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.

MT4BackupInfo

v2 DTO for a single MT4 backup file descriptor. Curated subset of the wrapper's BackupInfo — drops the 6-int reserved blob and keeps only the three consumer-facing fields.

Property	Type	Description
file	string, nullable	Backup file name (basename, server-relative)
size	integer (int64)	File size in bytes. Source field is a 32-bit signed int — widened to long here to give the client JSON-safe numeric range without re-shaping after a future wrapper fix.
time	string (date-time)	File modification time (UTC, from MetaQuotes __time32_t)

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.

MT4User

v2 DTO describing a trading account. Curated subset of the wrapper's UserRecord — exposes identity, contact, financial and flag fields that callers actually need. Deliberately omitted from v2 (vs v1's full UserRecord shape): * Password / PasswordInvestor / PasswordPhone / OtpSecret / ApiData / SecureReserved — credentials and secrets must never cross the v2 boundary regardless of access level. * Unused / Reserved2 / EnableReserved / TimeStamp — wrapper bookkeeping with no caller-visible semantics. Account flags are exposed as a single CPlugin.SaaSWebApps.WebAPI.DTOs.MT4.v2.MT4User.EnableFlags bitfield (the wrapper's native representation). Bit semantics are documented under that property — splitting it into separate booleans would hide the fact that MetaQuotes occasionally reuses bit positions across builds.

Property	Type	Description
login	integer (int32)	Trading account number (login)
group	string, nullable	Group name the account belongs to
name	string, nullable	Display name of the account holder
registrationDate	string (date-time)	UTC timestamp when the account was created
lastDate	string (date-time)	UTC timestamp of the last MT4 server interaction
externalId	string, nullable	External customer identifier (e.g. CRM/KYC link). Wrapper's Id field.
status	string, nullable	MT4-internal status string (e.g. live/demo state)
country	string, nullable	Country (free text per broker's enrolment workflow)
city	string, nullable	City
state	string, nullable	State / region
zipCode	string, nullable	Postal / ZIP code
address	string, nullable	Street address
leadSource	string, nullable	Lead source / referral channel tag
phone	string, nullable	Contact phone
email	string, nullable	Contact email
comment	string, nullable	Free-form back-office comment
leverage	integer (int32)	Account leverage (e.g. 100 means 1:100)
agentAccount	integer (int32)	IB / agent account number that referred this client
lastIP	integer (int32)	Last connection IP as raw int (use platform helpers to format)
balance	number (double)	Current balance
credit	number (double)	Credit on the account
prevMonthBalance	number (double)	Balance at the start of the previous calendar month
prevBalance	number (double)	Balance at the previous reporting close
prevMonthEquity	number (double)	Equity at the start of the previous calendar month
prevEquity	number (double)	Equity at the previous reporting close
interestRate	number (double)	Interest rate (broker-defined, often used for swaps)
taxes	number (double)	Tax rate applied to the account
enableFlags	integer (int32)	Account flag bitfield (wrapper's EnableFlags). Documented bits: * 0x01 = account enabled (login allowed) * 0x02 = client may change password * 0x04 = account is read-only (no trading) * 0x08 = OTP enrolment required at login Bit positions reflect MT4 build 1455. Verify against the current MT4 Manager docs if pinning behaviour to a specific bit.
sendReports	integer (int32)	0 = no reports, non-zero = nightly email reports enabled
mqid	integer (int64)	MetaQuotes ID for mobile push notifications (0 if not linked). Typed as long in v2 even though current builds store it in 32 bits — the wrapper exposes a wider underlying type and a checked narrowing cast would crash for accounts whose mqid sits above Int32.MaxValue. Future-proofs the contract against MQ widening.
userColor	integer (int32)	UI tint color in terminal client lists

MT4Trade

v2 DTO mirroring the wrapper's TradeRecord. The set of fields is curated for typical client use-cases — order monitoring, P&L reporting, trade history reconciliation. Internal padding/reserved/gateway-internal/raw underscore-prefixed fields are intentionally excluded. Span<>-typed helpers (ConvRates, ConvReserv, APIData) are excluded because System.Text.Json cannot serialize ref-struct-backed properties — those would force callers onto a custom converter for marginal value. Enum members (TradeCommand, TradeRecordState, TradeRecordReason, ActivationType) serialize as string names via V2JsonContext UseStringEnumConverter — e.g. "Buy" rather than 0.

Property	Type	Description
order	integer (int32)	Order ticket number
login	integer (int32)	Owner account login
symbol	string, nullable	Symbol traded (e.g. EURUSD)
digits	integer (int32)	Symbol precision (number of digits after the decimal point)
tradeCommand	TradeCommand	Trade direction / pending order type (Buy/Sell/BuyLimit/etc)
volume	integer (int32)	Volume stored ×100 (e.g. 15 means 0.15 lots — see VolumeLots)
volumeLots	number (double)	Volume expressed in lots, for human consumption (Volume / 100)
tradeRecordState	TradeRecordState	Lifecycle state of the trade record
openPrice	number (double)	Price at which the order was opened
sl	number (double)	Stop-loss price (0 if unset)
tp	number (double)	Take-profit price (0 if unset)
openTime	string (date-time)	Order open timestamp
closeTime	string (date-time)	Order close timestamp (default for still-open orders)
closePrice	number (double)	Price at which the order was closed
commission	number (double)	Broker commission
commissionAgent	number (double)	Agent (IB) commission
storage	number (double)	Accumulated swap / rollover charges
profit	number (double)	Realised / floating profit
taxes	number (double)	Taxes withheld
magic	integer (int32)	Expert advisor magic number — client-supplied tag
comment	string, nullable	Free-form order comment
expiration	string (date-time)	Expiration timestamp for pending orders
tradeRecordReason	TradeRecordReason	Reason the trade record was created/modified (Client/Expert/Dealer/Stopout/etc)
activationType	ActivationType	How a pending order was activated
timeStamp	string (date-time)	Last modification timestamp of the trade record
marginRate	number (double)	Margin conversion rate (margin currency → deposit currency)