Completed integration and disclosure boundary
EXCOIN completed an engagement integrating MetaTrader 5 and 4 through a custom API. The client, contracted scope, servers, endpoints, entitlements and operating figures are confidential. This detailed analysis addresses engineering challenges of that class of delivery; the design patterns are generalised and do not reveal the exact client environment. A typical broker wants one layer for portal, CRM, reporting and automation without forcing every new product to understand platform differences.
The goal is not to pretend MT4 and MT5 have identical data models. Their interfaces, trading entities and operational capabilities differ. A custom API should unify common concepts while preserving features present only on one platform. Such differences belong in documentation, contracts and error responses. Silently removing a capability could change the meaning of a trade or account operation.
Discovery: licences, interfaces and capability matrix
MetaQuotes lists MT5 Web API for integration with web services, Manager API for administration, Gateway API for other trading systems and separate report and server-extension interfaces. For MT4 it describes Manager, WebServices, Server, DataFeed and Report APIs; new MT4 licences are no longer offered. These lists do not mean a particular broker installation exposes every interface with every desired permission. Access, versions, entitlements and contractual permission must be verified.
Discovery produces a capability matrix for actual servers: source interface, available method, required role, inputs and outputs, business meaning, limits, failures and target endpoint. Read, write and privileged administrative actions are distinguished. 'Complete implementation' means coverage of every item in the approved matrix with documented exceptions, not a claim that one unrestricted public API exposes everything inside MetaTrader.
Design the custom API around customer processes
The public contract follows customer tasks rather than mechanically mirroring vendor methods. It separates clients and accounts, groups and permissions, symbols and market data, orders and their history, deals, positions, balances and account operations, reports, administration and system events. Each group gets an inventory of reads, writes, pagination, filters, versions and data sensitivity. Endpoint names are finalized only after mapping the interfaces actually available.
The contract defines currency, volume and price precision, time zones, account and trade identifiers, state vocabulary and error translation. An OpenAPI specification is versioned with the code; a breaking change needs a migration plan and a period of coexistence. Platform-specific fields remain explicit schema extensions rather than disappearing. A response must not imply final execution when the backend has only accepted a request.
MT5 and MT4 adapters and the source of truth
Each platform has an adapter behind a domain contract. It handles authentication, licensed vendor interfaces, conversion, call limits, reconnection and error mapping. The common layer should not hide scattered platform branches inside business logic. Adapter tests make a version change or new server a bounded change rather than a rewrite of the portal, CRM and reporting stack.
MetaTrader remains authoritative for trading state unless a particular process explicitly defines another source. The custom database holds correlations, requests, read projections and audit events; it is not an independent truth about final execution. Projections record their last confirmed time and source version. A mismatch creates a reconciliation task rather than a silent overwrite. That prevents a fast interface from displaying an unsupported final outcome.
Orders, deals, positions and unknown outcomes
A request, order, execution and position are separate entities. Acceptance of an order is not execution. Partial fills, rejection and cancellation need states that reflect the actual platform and account type. Before a write, the API validates permission, instrument parameters, trading session, limits and idempotency key. The response distinguishes accepted-for-processing, confirmed trading result and outcome still under investigation.
After a timeout the same order is not submitted blindly again. The layer retains a correlation ID, queries the source and proceeds only when the real state is known. Duplicate callbacks, repeated client requests and worker restarts are routine tests. Reconciliation compares requests, server events and account state within a defined time window, with a controlled manual exception path. Acceptance requires tracing a single order from request to final state.
Global infrastructure without a zero-latency promise
Worldwide access is designed around client regions, data boundaries and the trading servers' locations. A regional edge can provide TLS, traffic protection and routing; customer and read services may operate in more than one region. Write operations still need a clear owner and an authoritative path to the relevant MetaTrader server. It would be unsafe to promise instantaneous consistency across continents or assign the same account to two active writing regions without an explicit consistency design.
The topology defines component availability, capacity limits, queues, degraded mode and traffic redirection. During an outage a read view may show the last confirmed state with its timestamp; writes stop when the source of truth cannot be verified. Regional failover tests include DNS and caching behaviour, message replay and adapter reconnection. Concrete SLOs, p95/p99 latency and RTO/RPO follow measurements in the client's actual licensed environment.
Security, identity and separation of duties
Customer identity, service accounts and privileged operators have different boundaries. The API uses short-lived narrowly scoped tokens and server-side authorization for every action, with separate permissions for account administration, trading, reporting and operational interventions. Secrets stay out of code and logs; access has an owner and review cycle. A privileged change may require a second approval. Rate limits consider actor and operation risk, not just IP address.
The threat model covers another customer's account, swapped MT4/MT5 identifiers, request replay, internal role misuse, leaked exports and adapter compromise. Tests check tenant isolation, permission scope, invalid tokens or signatures, key rotation and disconnection from vendor APIs. Controls can be mapped to OWASP ASVS and relevant NIST SSDF practices, but using those frameworks is neither a certification nor proof of security for a particular deployment.
Audit trail and operational observability
A business audit event links the actor, purpose, account, safely represented request, authorization decision, API and adapter versions, platform response and final outcome. Technical traces and business audit records serve different purposes and retention rules. Passwords, full tokens and unnecessary personal information do not belong in logs. Consistent time, correlation keys and completeness checks allow an incident or complaint to be reconstructed across services.
An operations view separates API health, MT4 and MT5 connectivity, queue depth, freshness of read projections, errors by endpoint, reconciliation age and regional failover state. An alert points to an owner and runbook rather than merely painting a chart red. Synthetic monitoring uses a safe test scenario, not a live trade. During an incident, the team can see which release or configuration change preceded a degradation.
Endpoint tests and acceptance
Every approved endpoint receives contract, authorization, invalid-input, failure-response and size or pagination tests. Critical writes additionally test duplicates, timeout, lost acknowledgement and concurrent state changes. Adapters are first tested against a simulator and then in a controlled client environment; simulation is not presented as proof of actual server behaviour. Test data covers several accounts, groups, instruments and trading modes.
The acceptance matrix includes endpoint inventory ID, source API and permission, expected business result, test evidence and exception owner. It also covers an end-to-end path through account creation, data reading, trading request, history, reporting and service correction as permitted by scope. Load and recovery exercises include degraded operation. Only a signed-off matrix supports the statement that all endpoints agreed for that engagement have been delivered.
Migration, rollout and rollback
MT4 and MT5 may have different history and identifiers. Before cutover the team maps accounts, groups, instruments and time zones, including records with no unambiguous counterpart. Historical data is checked on a sample and then with reconciliation totals. If old information remains only on MT4, the portal labels it as a historical source rather than silently presenting it as a new MT5 record.
Release begins with reads, then selected writes for a restricted account group, and only later broader operation. Feature flags can segment regions, account types and endpoints, but cannot bypass authorization. Each stage has a rollback plan: stop the new path, preserve evidence, confirm platform state and resolve in-flight operations. Rolling back application code does not undo an executed trade; such a change needs an approved business procedure.
Support and extensions after launch
After handover the broker needs clear ownership of incidents, vendor API changes, security updates and capacity. A service model defines contact paths, severity, response procedures, change windows, backups, recovery and regular access review. SLOs and any SLA are agreed against observed operation and platform constraints. Reports must not confuse availability of the custom API with availability of an external MetaTrader server.
A new module follows the same capability matrix: purpose, source of truth, data contract, permissions, security scenarios, monitoring and acceptance. It may be a client portal, CRM workflow, reporting, risk alerts or another integration if approved and licensed. API versions protect existing consumers and retired endpoints have a dated migration plan. Long-term value comes from changing one part without losing control of trading state.
Domain map and ownership boundaries
The domain model comes before the first public endpoint. A person, brokerage account, trading account on a specific MT server, group, symbol, order, deal, position and balance operation are not interchangeable. Each entity needs an identifier, source of truth, retention rule and permitted actions. Mapping a CRM person to an MT account is a privileged, versioned process; silently repairing a mistaken link could expose another customer's funds.
The external API translates a business action into a safe sequence of vendor calls. This boundary also decides whether a CRM outage may stop trading, whether reporting may use a dated projection, and which changes require broker approval. Every operation has an initiator, confirming system, exception owner and final evidence. Those assignments belong in an ownership map rather than in tacit team knowledge.
Account identity across MT4 and MT5
The same numeric identifier may exist on different servers and refer to unrelated clients. A global identity therefore includes platform, server and local ID; external systems use a stable reference that is never silently remapped. Changing an owner, merging clients or moving an account requires a history and approval path so an investigator can establish who had access at a particular time.
An API must not accept only account=12345 and select the first match. Authorisation compares the actor against the canonical account and requested action. Mistakes here can expose history or permit trading on someone else's account. Test data deliberately reuses account numbers across servers and verifies that platform and tenant are mandatory in every decision.
Symbols, instruments and precision
An instrument displayed as EURUSD may differ across servers in suffix, trading hours, volume step, contract size or quote precision. The external catalogue must not equate instruments only by name. It retains vendor identifier, server, asset class, trading constraints and effective dates. When specifications change, pre-trade validation changes too; a week-old form cannot be trusted for a current order.
Price and volume conversion uses precise decimal types and explicit rounding. Floating point arithmetic can produce a value the server rejects or shift a limit. A delayed quote is marked as such; last price is not a promise of execution. Boundary tests include zero and maximum volume, session changes and an instrument suspended while a form remains open.
Pre-trade checks and API responses
Before placing an order, the layer checks identity, role, account, instrument status, order type, volume, price parameters and server constraints. Local checks provide fast feedback, but the trading platform makes the final acceptance decision using current state. The API must distinguish invalid input, vendor refusal, accepted processing and a known final outcome.
Customer channels can share semantics across MT4 and MT5 without pretending every field is identical. Platform-specific rejection reasons map to stable public categories while remaining available in restricted diagnostics. A new vendor error must not silently become unknown. Regression scenarios preserve meanings, not only HTTP status codes.
Retries and the exactly-once illusion
After a lost network response, a caller cannot know whether a trade happened. An exactly-once promise must become a concrete invariant: one economic intent must not create two trading actions. The API stores an idempotency key and hash of relevant parameters. The same key and parameters return the known state; a different amount or account under that key is rejected. This record survives restarts and regional changes.
A write is not automatically retried after timeout until the source server has been checked. The result may be pending, executed, rejected or genuinely unknown. Unknown outcomes trigger reconciliation and expose the time of last verification. An operator should not see an unexplained retry button that could create a second economic action.
Events, history and partial fills
Trading history is more than a list of orders. The API links request, server order, deal, partial fill, final settlement and position so support can explain why one intent produced several events. Partial fill, cancellation of the remainder and position change each have a time and source. MT4 and MT5 history is mapped according to real platform semantics.
Synchronisation must handle gaps in event delivery. An adapter tracks checkpoints, verifies continuity and fills missing intervals after reconnection. Duplicate events cannot change projections twice. If a vendor API lacks a complete stream, periodic snapshot comparison is necessary. Each projection shows its origin and last confirmation time.
Balance, margin and account operations
Balance, equity, free margin and credit are different quantities with distinct definitions, currency, source and timestamp. A customer display may be informative, but trading decisions rely on the authoritative platform state. Deposits, withdrawals and manual corrections are sensitive writes requiring layered approval, a reference to the financial system and an audit link to the approver.
A mismatch between finance and MT cannot be silently fixed with one balancing entry. It may be a timing delay, duplicate message, manual action, conversion or integration error. Every correction needs evidence, approval and reversal procedure. Monitoring tracks aged exceptions and an unusual rate of corrections, either of which may signal a defect or abuse.
Back office, permissions and dual control
Administrative APIs may alter groups, leverage, access and trading modes with financial consequences. They are not ordinary CRUD. Each change records reason, prior value, proposed value, approver and recovery plan. Selected actions separate maker from checker. Permissions are scoped to a server, group and operation; global administrators are exceptional and closely monitored.
Adapter service accounts receive only required vendor privileges. Credential rotation is tested across old and new configurations, restart and rollback. Periodic access recertification catches rights retained after staff changes. An audit event records not only who clicked but the authorisation decision and policy version that permitted the action.
Reports and historical consistency
Client statements, internal risk reports and regulatory exports can answer different questions using the same data. Each defines whether it shows a point-in-time state, live snapshot or closed trading day. Timezone conversion or late server events can alter results. An export therefore carries scope, creation time, transformation version and source identity.
Large histories are paginated and exports generated asynchronously instead of holding an unbounded HTTP request against a trading server. Download access is time-limited and checks tenant and role. Files expire under a retention policy. Tests ensure MT4 and MT5 records are not merged into an unlabelled time series.
Regional availability and write placement
Global access does not mean active trading writes in multiple regions for the same account. Each account has an authoritative route to its platform server and an outage policy. Static content, login and some read projections can be placed near users; writes preserve order and idempotency. Traffic redirection cannot create two independent queues that both submit one order.
Each region is measured against the actual MT server for network latency, adapter availability, projection age and recovery time. In degraded mode a read view may show last known state with a timestamp, but writes stop if the source of truth cannot be confirmed. Failover tests incomplete operations, not only a green healthcheck.
Observability, alerts and runbooks
One API uptime figure does not reveal a trading incident. Dashboards separate read success, write rejection, unknown outcomes, projection lag, queue length, adapter reconnects and open reconciliation cases. Alerts are tied to customer impact and an owner. A planned vendor maintenance window differs from an unexpected outage requiring escalation.
A runbook gives the first check, safe action, limit of automation and broker or platform contact. Restarting a worker must not erase evidence for an unknown write. An incident timeline connects release, configuration, alert and trading event. After recovery, targeted reconciliation and a recorded decision close every exception.
Load, quotas and vendor-server protection
A public API can serve many consumers while the vendor interface is constrained. Adapters maintain limits by operation, server and priority. Critical writes cannot wait behind bulk reports, but opening unlimited connections is unsafe too. During overload, a request is rejected or queued according to contract, with its consequence visible. Capacity planning relies on real endpoint measurements.
Load tests combine history reads, catch-up after outages, market-open peaks and concurrent writes. They measure tail latency, errors and recovery, not just averages. Limits are versioned with the vendor server because upgrades can change behaviour. Tests must never unintentionally place live trades.
Contract versions and platform upgrades
A vendor API change need not become a public API change if the adapter preserves business meaning. A changed field or error meaning does require a versioned contract. Migration notes explain old and new schemas, semantic differences, coexistence and retirement date. A breaking change should not be hidden in an optional field that legacy consumers ignore.
Continuous contract tests run against a known adapter version and licensed test environment where available. After an MT server upgrade, critical writes, history, admin actions and reconnect are checked, not merely HTTP 200 responses. Release gates include audit events and rollback planning. Any change to the source of truth needs an explicit architecture decision.
Security beyond a routine penetration test
High-risk scenarios combine otherwise legitimate components: a signed request for another account, history export after a role change, an admin action in the wrong group or replay after failover. Testing cannot stop at injection and login checks. Authorisation matrices cover every endpoint and adapter, including historic servers and read-only reports.
Security review follows the actual data path: identity origin, decision point, log contents and secret rotation. A compromised service account must be contained, its effects assessed and service restored without overwriting trade history. Audit records need tamper resistance, while retention follows the broker's real duties.
Handover, support and recovery rehearsal
Handover includes OpenAPI, capability matrix, server and role map, runbooks, change process, tests and exception owners. A new team should be able to explain what happens after a lost order acknowledgement and where to find the real state. Otherwise support becomes a series of manual interventions that gradually erode trust in data.
A recovery rehearsal restores projection data, secrets and vendor connections in an isolated environment. It verifies audit correlations and that old write jobs do not restart. The result is a timed record of gaps, not just backup exists. Any new module inherits the same identity, idempotency and observability boundaries.
Result of the study and a practical next step
The owner confirms completion of the anonymised engagement; this page does not publish its metrics. For a similar new delivery a broker would supply licensed servers and API entitlements, roles, permitted operations, regions, retention requirements and representative test scenarios. Joint discovery then fixes endpoints, platform differences, milestones and tests. An early pilot should exercise the riskiest write path and one meaningful failure.
For another client, delivery can be phased into read projections, approved writes, back office, reporting, global resilience and support. Scope depends on licences, security restrictions and operating data. Qualified client specialists assess financial-sector and personal-data obligations. Because of confidentiality, EXCOIN does not name the client, publish measured outcomes or guarantee the same result in another environment.
General technical references
These links explain general principles. They do not document the client's confidential implementation.