Changelog
Introduction

Sections

Changelog

Theme switcher

Introduction

The Broker API is a versatile API platform designed for various integrations, enabling streamlined management and interaction with multiple services through a single access point. This API supports REST and gRPC protocols, providing flexibility in integration and ensuring compatibility with diverse client systems. It facilitates secure, efficient administrative operations and service management, making it an essential tool for clients looking to optimise their operational workflows.

In our system, each broker has a unique partnerID assigned. Every operation via this API is performed within that particular partnerID. Since we encode your partnerID in your Authorization token, you don't have to consider this parameter when sending requests, but you will see this parameter across multiple different endpoints. For the Sandbox environment, partnerID = 0 and is shared between every account in the system. It means you will have access to test data added by other integrations.

Server time is GMT (UTC+0).

All time-related fields accept and return values according to the RFC 3339 standard. For example 2024-01-13T09:20:04.651Z.

The request limit is 500 requests/minute.

Base URL

Production:

Sandbox:

Authentication

Our system implements a security mechanism that utilizes token-based authorization to ensure secure resource access. The authentication process involves using an Authorization header, following the token scheme. This section outlines the steps required for obtaining and using the authentication token to access protected resources.

Security Best Practices

To ensure the highest security standards, all communication with our services should be performed over encrypted channels (for example, using SSL/TLS protocols). Unencrypted or insecure connections are not recommended and may be rejected by the server. In particular, please make sure to always connect to the secure port (e.g., 443) assigned for encrypted traffic.

Note: Attempting to establish unencrypted connections or using insecure credentials may cause authentication or connection failures. Always utilize encrypted methods and secure credentials.

Obtaining the Token

The authentication token is obtained from our Customer Relationship Management (CRM) system. You must first authenticate yourself within the CRM to receive a token. This token acts as a digital key, granting access to the system's resources for the duration of the token's validity. Tokens are valid until revoked.

Using the Token for Access

Once the token is obtained, it must be included in the request to access secured resources within our system. The token is added to the HTTP request's header as follows:

Plain text
Authorization: Bearer <Your_Token_Here>

Incorporating Authorization in gRPC Requests

In gRPC, the traditional concept of HTTP headers is abstracted through metadata, allowing for the transmission of key-value pairs alongside RPC calls. To secure gRPC services with token-based authentication, the Authorization metadata (with the Bearer prefix) must be included with each call. This process is similar to using the Authorization header in HTTP requests but is adapted to fit the gRPC framework.

Adding the Authorization Metadata

To include an authentication token in a gRPC request, the token must be added as metadata using the 'Authorization' key, followed by the Bearer token value. This ensures that the server side of the gRPC service can authenticate the request by validating the token.

Code Example (Python)

Below is a generic example of how to add the Authorization metadata in a gRPC client application. The implementation may vary depending on the programming language and gRPC library used.

Plain text
import grpc

# Create a secure gRPC channel (recommended)
channel = grpc.secure_channel('your_grpc_service_endpoint:443', grpc.ssl_channel_credentials())

# Prepare metadata with the Authorization token
metadata = [('Authorization', 'Bearer <Your_Token_Here>')]

# Create a stub (client)
stub = YourServiceStub(channel)

# Make a call with the Authorization metadata
response = stub.YourRpcMethod(request, metadata=metadata)

Replace <Your_Token_Here> with the actual token obtained from your CRM system, and adjust YourServiceStub and YourRpcMethod to match your gRPC service definition.

Was this section helpful?

What made this section unhelpful for you?

On this page
  • Authentication

gRPC

This gRPC model defines several services within a package designed for the Broker API, focusing on positions, ledgers, trading events, and related data. Below is the complete documentation for all services and their methods.

The address to connect to the gRPC stream is: grpc-broker-api-demo.match-trader.com.

A separate gRPC ping stream sends pings every 50 seconds (configurable) to maintain an active connection.

Below is the corresponding Protobuf definition used for the gRPC service.

Protocol Buffers
syntax = 'proto3';
option java_multiple_files = true;
option java_package = 'com.matchtrade.broker_api.grpc';

package com.matchtrade.broker_api.grpc;

service AccountInfoServiceExternal {
  rpc getAccountInfoChangedStream  (PBAccountInfoChangedRequestExternal) returns (stream PBAccountInfoChangedStreamResponseExternal) {}
}

service PositionsServiceExternal {
  rpc getClientPositionsStream (PBClientPositionRequestExternal) returns (stream PBPositionStreamResponseExternal) {
  }

  rpc getOpenPositionsStreamByGroupsOrLogins (PBOpenPositionRequestExternal) returns (stream PBOpenPositionsStreamResponseExternal) {
  }
}

service LedgerServiceExternal {
  rpc getLedgersStreamByLogin(PBLedgerRequestByLoginExternal) returns (stream PBLedgerStreamResponseExternal) {
  }

  rpc getLedgersStreamByGroupsOrLogins(PBLedgersRequestByGroupsOrLoginsExternal) returns (stream PBLedgersStreamResponseExternal) {
  }
}

service OrderServiceExternal {
  rpc getOrdersUpdateStreamByGroupsOrLogins(PBOrdersUpdateStreamRequestExternal) returns (stream PBOrdersUpdateStreamResponseExternal) {
  }
}

service QuotationsServiceExternal {
  rpc getQuotationsWithMarkupStream (PBQuotationsWithMarkupStreamRequestExternal) returns (stream PBQuotationSimpleExternal) {
  }
}

service GroupServiceExternal {
  rpc getGroupChangesStream(PBGroupChangeStreamRequestExternal) returns (stream PBGroupChangeStreamResponseExternal) {
  }
}

service TradingEventsServiceExternal {
  rpc getTradingEventsStream (PBTradingEventsStreamRequestExternal) returns (stream PBTradingEventsStreamResponseExternal) {
  }
}

service SymbolsServiceExternal{
  rpc getSymbolsChangedStream(PBSymbolChangedRequestExternal) returns (stream PBSymbolChangedStreamResponseExternal) {}
}

service EquityServiceExternal{
  rpc getClientEquityStream (PBEquityRequestExternal) returns (stream PBEquityStreamResponseExternal) {}
}

message PBAccountInfoChangedRequestExternal {
  string systemUuid = 1;
  repeated string groups = 2;
  bool includeBlocked = 3;
  bool includeLocked = 4;
}

message PBAccountInfoChangedStreamResponseExternal {
  oneof msg {
    PBAccountInfoUpdated userUpdated = 1;
    PBAccountInfoDeleted userDeleted = 2;
    bool heartbeat = 3;
  }
}

message PBAccountInfoDeleted  {
  int64 login = 1;
  string group = 2;
  AccountInfoDeletedReason reason = 3;

  enum AccountInfoDeletedReason {
    ACCOUNT_INFO_DELETED_REASON_UNKNOWN = 0;
    ACCOUNT_INFO_DELETED_REASON_ACCOUNT_DELETED = 1;
    ACCOUNT_INFO_DELETED_REASON_RIGHTS_REVOKED = 2;
    ACCOUNT_INFO_DELETED_REASON_ACCOUNT_INTERNAL_ERROR = 3;
  }
}

message PBAccountInfoUpdated {
  int64 login = 1;
  optional PBAccountInfoUpdatedDetails prev = 2;
  PBAccountInfoUpdatedDetails current = 3;
}

message PBAccountInfoUpdatedDetails {
  optional string uuid = 1;
  optional string group = 2;
  optional int32 leverage = 3;
  optional bool isRetail = 4;
  optional bool isProView = 5;
  optional bool isBlocked = 6;
  optional bool isLocked = 7;
  optional string country = 8;
  optional string name = 9;
  optional string address = 10;
  optional string email = 11;
  optional string phone = 12;
  optional string province = 13;
  optional string zipCode = 14;
  optional string city = 15;
  optional string remarks = 16;
  optional string bankAccount = 17;
  optional string accountCurrency = 18;
  optional int32 accountCurrencyPrecision = 19;
  optional int64 registrationDate = 20;
  optional int64 agentId = 21;
  optional PBClientAccessRightsType accessRightsType = 22;
}

enum PBClientAccessRightsType {
  CLIENT_ACCESS_RIGHTS_TYPE_UNSPECIFIED = 0;
  CLIENT_ACCESS_RIGHTS_TYPE_FULL_ACCESS = 1;
  CLIENT_ACCESS_RIGHTS_TYPE_CLOSE_ONLY = 2;
  CLIENT_ACCESS_RIGHTS_TYPE_TRADING_DISABLED = 3;
  CLIENT_ACCESS_RIGHTS_TYPE_LOGIN_DISABLED = 4;
  CLIENT_ACCESS_RIGHTS_TYPE_LOCKED_CLOSE_ONLY = 5;
}

message PBOrdersUpdateStreamRequestExternal {
  string systemUuid = 1;
  repeated int64 logins = 2;
  repeated string groups = 3;
  bool includeBlocked = 4;
  bool includeLocked = 5;
}

message PBOrdersUpdateStreamResponseExternal {
  oneof msg {
    PBOrder order = 1;
    bool heartbeat = 2;
  }
}

message PBOrder {
  string orderId = 1;
  string symbol = 2;
  string alias = 3;
  string volume = 4;
  PBPendingTypeExternal type = 5;
  string creationTime = 6;
  string activationPrice = 7;
  PBOrderSideExternal side = 8;
  string stopLoss = 9;
  string takeProfit = 10;
  string comment = 11;
  PBRequestUpdateTypeExternal requestUpdateType = 12;
  string groupName = 13;
  int64 login = 14;
}

enum PBPendingTypeExternal {
  UNTYPE = 0;
  LIMIT = 1;
  STOP = 2;
}

message PBDailyStatisticsExternal {
  double change = 1;
  double high = 2;
  double low = 3;
}

message PBClientPositionRequestExternal {
  string systemUuid = 1;
  string login = 2;
}

message PBPositionStreamResponseExternal {
  oneof msg {
    PBPositions positionList = 1;
    bool heartbeat = 2;
  }
}

message PBOpenPositionRequestExternal {
  string systemUuid = 1;
  repeated string groups = 2;
  repeated string logins = 3;
}

message PBOpenPositionsStreamResponseExternal {
  oneof msg {
    PositionsPerClient positionsByLogin = 1;
    bool heartbeat = 2;
  }
}

message PBEquityRequestExternal {
  string systemUuid = 1;
  repeated string groups = 2;
  repeated int64 logins = 3;
  bool includeBlocked = 4;
  bool includeLocked = 5;
  bool includeStateHistory = 6;
}


message PBEquityResponseExternal {
  int64 login = 1;
  string equity = 2;
  string balance = 3;
  string credit = 4;
}

message PBEquityStreamResponseExternal {
  oneof msg {
    PBEquityResponseExternal equity = 1;
    bool heartbeat = 2;
  }
}

message PositionsPerClient {
  map<string, PBPositionWithGroup> positionsByLogin = 1;
}

message PBPositions {
  repeated PBPosition positions = 1;
}

message PBPosition {
  string id = 1;
  string symbol = 2;
  double volume = 3;
  PBOrderSideExternal side = 4;
  string open_time = 5;
  double open_price = 6;
  double stop_loss = 7;
  double take_profit = 8;
  double swap = 9;
  double profit = 10;
  double net_profit = 11;
  double current_price = 12;
  double commission = 13;
  repeated PBPartialExternal partials = 14;
  string alias = 15;
  PBRequestUpdateTypeExternal request_update_type = 16;
}

message PBPositionWithGroup {
  string id = 1;
  string symbol = 2;
  double volume = 3;
  PBOrderSideExternal side = 4;
  string open_time = 5;
  double open_price = 6;
  double stop_loss = 7;
  double take_profit = 8;
  double swap = 9;
  double profit = 10;
  double net_profit = 11;
  double current_price = 12;
  double commission = 13;
  repeated PBPartialExternal partials = 14;
  string alias = 15;
  PBRequestUpdateTypeExternal request_update_type = 16;
  string group = 17;
}

enum PBRequestUpdateTypeExternal {
  NEW = 0;
  UPDATE = 1;
  CLOSED = 2;
  PROFIT_CHANGE = 3;
  PARTIALLY_CLOSED = 4;
}

message PBPartialExternal {
  string id = 1;
  double volume = 3;
  double old_partial_volume = 4;
  string open_time = 6;
  double open_price = 7;
  double swap = 8;
  double profit = 9;
  double net_profit = 10;
  double commission = 12;
}

enum PBOrderSideExternal {
  BUY = 0;
  SELL = 1;
}

message PBOpenPositionsRequest {
  repeated string groupNames = 1;
  repeated int64 logins = 2;
}

enum PBHistoryOperationTypeExternal {
  DEPOSIT = 0;
  WITHDRAWAL = 1;
  CREDIT_IN = 2;
  CREDIT_OUT = 3;
  AGENT_COMMISSION = 4;
  COMMISSIONS = 5;
  SWAPS = 6;
  OTHER = 7;
  CLOSED_POSITION = 8;
}

message PBLedgerRequestByLoginExternal {
  string systemUuid = 1;
  string login = 2;
  repeated PBHistoryOperationTypeExternal historyOperationType = 3;
  repeated AdditionalType additionalTypes = 4;
}

message PBLedgersRequestByGroupsOrLoginsExternal {
  string systemUuid = 1;
  repeated string logins = 2;
  repeated string groups = 3;
  repeated PBHistoryOperationTypeExternal historyOperationType = 4;
  repeated AdditionalType additionalTypes = 5;
}

message PBLedgerStreamResponseExternal {
  oneof msg {
    PBLedger ledger = 1;
    bool heartbeat = 2;
  }
}

message PBLedger {
  string id = 1;
  PBHistoryOperationTypeExternal historyOperationType = 2;
  string time = 3;
  double profit = 4;
  string comment = 5;
  string group = 6;
  int64 login = 7;
  AdditionalType additionalType = 8;
}


message PBLedgersStreamResponseExternal {
  oneof msg {
    PBLedgers ledgers = 1;
    bool heartbeat = 2;
  }
}

message PBLedgers {
  repeated PBLedgerStreamResponseExternal ledgers = 1;
}

message PBQuotationsWithMarkupStreamRequestExternal {
  string systemUuid = 1;
  repeated string instruments = 2;
  optional string group = 3;
  optional int32 throttlingMs = 4;
  optional bool smartThrottling = 5;
}

message PBQuotationSimpleExternal {
  oneof msg {
    PBQuotation quotation = 1;
    bool heartbeat = 2;
  }
}

message PBQuotation {
  string symbol = 1;
  double bidPrice = 2;
  double askPrice = 3;
  int64 timestampInMillis = 4;
  optional PBDailyStatisticsExternal dailyStatistics = 5;
}

message PBGroupChangeStreamRequestExternal {
  string systemUuid = 1;
  repeated string groups = 2;
}

message PBGroupChangeStreamResponseExternal {
  oneof msg {
    PBGroupUpdated groupUpdated = 1;
    PBGroupDeleted groupDeleted = 2;
    bool heartbeat = 3;
  }
}

message PBGroupUpdated {
  string group = 1;
  string currency = 2;
  int32 currencyPrecision = 3;
  string groupOwner = 4;
  map<string, PBGroupSymbol> symbols = 5;
  PBMarginCalculationType marginCalculationType = 6;
  bool isManager = 7;
  bool isAdmin = 8;
  bool isBrokerManager = 9;
  int64 marginCall = 10;
  int32 depositCurrencyPrecision = 11;
  int64 swapCalculationTime = 12;
  PBStopoutAndMarginCallType stopoutAndMarginCallType = 13;
  bool commissionUpfront = 14;
  bool islamicSwap = 15;
  bool demoGroup = 16;
  PBHedgeMarginCalculationType hedgeMarginCalculationType = 17;
  int64 eodMode = 18;
  int64 eomMode = 19;
  int64 eodSnapshotTime = 20;
  bool defaultRetailEnabled = 21;
  bool coverageMode = 22;
  int64 orderProcessingDelay = 23;
  double stopoutLevel = 24;
  bool hedgingEnabled = 25;
  int64 pendingMultiplierPer1000 = 26;
  int64 defaultLeverageRatioPercent = 27;
  int64 commissionPerMillion = 28;
  int64 agentCommissionPerMillion = 29;
}

message PBGroupDeleted {
  string group = 1;
  GroupDeletedReason reason = 2;

  enum GroupDeletedReason {
    GROUP_DELETED_REASON_UNKNOWN = 0;
    GROUP_DELETED_REASON_DELETED = 1;
    GROUP_DELETED_REASON_RIGHTS_REVOKED = 2;
  }
}

message PBOpenPositionsStreamResponse {
  map<string, PBPositions> loginToPositions = 1;
}
message PBGroupSymbol {
  string symbol = 1;
  string bidMarkup = 2;
  string askMarkup = 3;
  double leverage = 4;
  string swapBuy = 5;
  string swapSell = 6;
  int64 freezeLevel = 7;
  int64 stopsLevel = 8;
  PBSwapType swapType = 9;
  string volumeMin = 10;
  string volumeMax = 11;
  string minCommission = 12;
  bool fixedLeverage = 13;
  int64 rawLeverage = 14;
  PBCommissionType commissionType = 15;
  int64 commissionPerMillion = 16;
}

enum PBMarginCalculationType {
  UNKNOWN_MARGIN_CALCULATION_TYPE = 0;
  UNREALIZED_LOSS_ONLY = 1;
  UNREALIZED_PROFIT_LOSS = 2;
}

enum PBSwapType {
  UNKNOWN_SWAP_TYPE = 0;
  PIPS_SWAP_TYPE = 1;
  PERCENTS = 2;
  NOT_DEFINED = 3;
}

enum PBCommissionType {
  UNDEFINED = 0;
  USD_PER_MILLION = 1;
  USD_PER_CONTRACT = 2;
  USD_PER_LOT = 3;
  PERCENTAGE = 4;
  PIPS_COMMISSION_TYPE = 5;
}

enum PBStopoutAndMarginCallType {
  STOPOUT_TYPE_UNDEFINED = 0;
  STOPOUT_TYPE_MARGIN_LEVEL_PERCENTAGE = 1;
  STOPOUT_TYPE_ABSOLUTE_EQUITY_USD = 2;
  STOPOUT_TYPE_OFF = 3;
}

enum PBHedgeMarginCalculationType {
  HEDGE_MARGIN_CALCULATION_TYPE_UNSPECIFIED = 0;
  HEDGE_MARGIN_CALCULATION_TYPE_NETTING = 1;
  HEDGE_MARGIN_CALCULATION_TYPE_LARGER_LEG = 2;
}

message PBTradingEventsStreamRequestExternal {
  string systemUuid = 1;
  repeated int64 logins = 2;
  repeated string groups = 3;
  bool includeBlocked = 4;
  bool includeLocked = 5;
}

message PBTradingEventsStreamResponseExternal {
  oneof msg {
    TradingEvents tradingEvents = 1;
    bool heartbeat = 2;
  }
}

message TradingEvents {
  repeated PBTradingEvent tradingEvents = 1;
}

message PBTradingEvent {
  oneof msg {
    PBMarginCallEvent marginCallEvent = 1;
    PBStopOutEvent stopOutEvent = 2;
    PBTakeProfitEvent takeProfitEvent = 3;
    PBStopLossEvent stopLossEvent = 4;
    PBOrderActivationEvent orderActivationEvent = 5;
  }
  int64 login = 6;
  string group = 7;
}

message PBMarginCallEvent {
  int64 login = 1;
  double marginLevel = 2;
}

message PBStopOutEvent {
  int64 login = 1;
  string orderId = 2;
  string instrument = 3;
  double volume = 4;
}

message PBTakeProfitEvent {
  int64 login = 1;
  string orderId = 2;
  string instrument = 3;
  PBOrderSideExternal side = 4;
  double volume = 5;
  double netProfit = 7;
  string walletCurrency = 8;
}

message PBStopLossEvent {
  int64 login = 1;
  string orderId = 2;
  string instrument = 3;
  PBOrderSideExternal side = 4;
  double volume = 5;
  double netProfit = 7;
  string walletCurrency = 8;
}

message PBOrderActivationEvent {
  int64 login = 1;
  string orderId = 2;
  string instrument = 3;
  PBOrderSideExternal side = 4;
  double volume = 5;
  double activationPrice = 7;
}

message PBSymbolChangedRequestExternal{
  string systemUuid = 1;

}

message PBSymbolChangedStreamResponseExternal{
  oneof msg {
    PBSymbolUpdatedOrCreated symbolUpdated = 1;
    PBSymbolDeleted symbolDeleted = 2;
    PBSymbolUpdatedOrCreated symbolCreated = 3;
    bool heartbeat = 4;
  }
}

message PBSymbolUpdatedOrCreated{
  repeated TradeHoursDto tradingHours = 1;
  int32 volumePrecision = 2;
  string volumeMin = 3;
  string volumeStep = 4;
  double commission = 5;
  string sizeOfOnePoint = 6;
  string symbol = 7;
  string alias = 8;
  string baseCurrency = 9;
  string quoteCurrency = 10;
  int32 pricePrecision = 11;
  PBSymbolType type = 12;
  string swapBuy = 13;
  string swapSell = 14;
  string volumeMax = 15;
  string contractSize = 16;
  int64 multiplier = 17;
  int64 divider = 18;
  double leverage = 19;
  string description = 20;
  PBTerminationType terminationType = 21;
  string terminationDate = 22;
  repeated string tags = 23;
}

message PBSymbolDeleted{
  string symbol = 1;
}

message TradeHoursDto {
  int32 dayNumber = 1; // 0 - Sunday
  int32 openHours = 2;
  int32 openMinutes = 3;
  int32 openSeconds = 4;
  int32 closeHours = 5;
  int32 closeMinutes = 6;
  int32 closeSeconds = 7;
}

enum PBSymbolType {
  UNKNOWN_SYMBOL_TYPE = 0;
  FOREX = 1;
  CFD = 2;
  FOREXCFD = 3;
}

enum PBTerminationType {
  EXPIRATION = 0;
  ROLLOVER = 1;
}

enum AdditionalType {
  NONE = 0;
  NEGATIVE_BALANCE_WITHDRAW = 1;
  CORRECTION = 2;
  REVENUE_SHARE = 3;
  INVOICE_PAYMENT = 4;
  MINIMUM_MONTHLY = 5;
  AGENT_COMMISSION_LEDGER = 6;
  NEGATIVE_BALANCE_CORRECTION = 7;
  SETTLEMENT = 8;
  INACTIVITY_FEE = 9;
  BONUS_IN_OUT = 10;
  STORAGE_FEE = 11;
  M2P = 12;
  BANK = 13;
  CRYPTO = 14;
  DEPOSIT_CORRECTION = 15;
  WITHDRAW_CORRECTION = 16;
  SWAP_CORRECTION = 17;
  COMMISSION_CORRECTION = 18;
  AGENT_FEE_CORRECTION = 19;
  MINIMUM_MONTHLY_FEE_CORRECTION = 20;
  REVENUE_SHARE_CORRECTION = 21;
  CPA = 22;
  DEPOSIT_BONUS = 23;
  CASHBACK = 24;
  IB_COMMISSION = 25;
  INTERNAL_TRANSFER = 26;
  NORIA_PAYMENT = 27;
  UNKNOWN_LEDGER = 28;
}

Base URL

Production:

Sandbox:

Errors

We use standard HTTP response codes to state the success or failure of API requests. It means that codes in the range

  • 2xx indicate success and usually have response bodies,
  • 4xx indicate errors with detailed answers to why a particular request failed,
  • 5xx indicate errors on our servers.

Status Codes

200

The request was performed successfully. You should receive a response with a body. 200 response bodies are listed in each endpoint's response section.

204

The request was performed successfully. You should receive a response without a body.

400

Invalid request, usually due to missing some required parameter.

401

Authorization information is missing or invalid.

403

Your API token does not have permission to perform the requested operation.

405

Wrong HTTP method used, eg. POST instead of GET

422

The server understands the content type of the request entity, and the syntax is correct, but it was unable to process the request.

500

Something went wrong on our end. You can contact our Product Support to check it.

Branches, Offers, Roles

In our system, there is a distinction between multiple layers of account attributes. In general, the account operates within the frames of a given: Branch, Offer(s), and Role. Each section has an explanation of a particular layer.

During the initial setup, offers, branches, and roles are created by Match-Trade by default. The broker can manually add more of them at any time from the CRM. It is not possible to create or edit branches, offers, or roles via the broker API.

On this page
  • Branches, Offers, Roles

Accounts

In the Accounts section, you will find detailed information about user accounts within the system. With this, you can access and update account details and create new accounts. This section serves as a central hub for overseeing and administering user accounts within the system. You can also find a Trading Accounts sub-section within the section with all relevant endpoints to manage Trading Accounts.

An Account represents the user, and a Trading Account is needed to perform trading actions. Under one Account, there might be more than one Trading Account. Some actions are performed only on Accounts, while others are on Trading Accounts.

In our system, there is a distinction between Leads and Clients. They are both types of user accounts. The difference between Lead and Client is conversion (first deposit) - the user is a Lead by default and becomes a Client after the first successful deposit.

On this page
  • Accounts

Payments

In the Payments section you can find endpoints for:

  • Retrieving Payment Gateways list with details about each Payment Gateway,
  • Retrieving Deposits and Withdrawals,
  • Making Manual payments,
  • Credit in and out.
On this page
  • Payments

Trading

The Trading section allows accessing and managing various trading functionalities within the system. With this section, you can place orders and monitor trading activity seamlessly. This section provides the necessary tools for users to efficiently execute trades and stay informed about market conditions.

On this page
  • Trading

Prop Trading

On this page
  • Prop Trading

Social Trading

On this page
  • Social Trading

CRM Events

CRM Events, such as payment and timeline events are implemented in Broker API via two delivery methods, Webhooks and gRPC, to suit different integration requirements.

You will find details for each of the methods in corresponding sections.

On this page
  • CRM Events

FAQ

This section contains frequently asked questions about integrating with the Match-Trader platform. Here you'll find concise answers to common technical questions that arise during implementation. The FAQ will be regularly updated as new questions emerge from our integration partners.

icon

How do I transfer a trading account from one group to another?

To change a trading account's group, you need to update its associated offer. Use the following endpoint:

Bash
curl --location --request PATCH '{{baseURL}}/v1/trading-account?systemUuid={{systemUuid}}&login={{login}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{APIkey}}' \
--data '{
  "offerUuid": "{{offer_uuid}}"
}'

This will move the trading account to the new offer (and consequently to the new group).

icon

How do I change a trader's password?

Passwords are associated with the user account (not with individual trading accounts). To change a password, use:

Bash
POST /v1/change-password

The system will automatically encrypt the new password. Neither you nor the Match-Trade system will have access to the plain text password after this change.

icon

How do I retrieve a list of a user's trading accounts?

To get all trading accounts associated with a specific user account:

Bash
GET /v1/trading-accounts?query={{email}}

This will return all trading accounts linked to the specified account email.

icon

How do I check a trading account's balance?

To check the current balance and equity of a trading account:

Bash
GET /v1/trading-account?systemUuid={{systemUuid}}&login={{tradingAccountLogin}}

This will return the current balance, equity, and other financial information for the specified trading account.

icon

What are branch, system and operation?

  • Branch is used in our CRM, e.g., for organizing clients by country. For external integrations, the "Default" branch should be used, which is always set up by Match-Trade.
  • The system is an internal service that connects the platform to the backend. There is only one, and it is unchangeable per server. The Match-Trade team configures it.
  • Operation is an internal service responsible for the proper creation of accounts. There is only one and it is unchangeable, set up during the client’s setup by Match-Trade.

Some endpoints require the UUIDs of these services (systemUuid, branchUuid, operationUuid), which can be obtained, for example, from the endpoint:

Bash
GET /v1/offers
icon

What is credit? Balance, Credit and Equity

Equity = Balance + Credit

  • Balance includes deposits and closed trade results. 
  • Credit is extra funds (e.g., bonuses) that cannot be withdrawn.

Credit allows an account to have a negative balance if it has been granted. For example, if an account has a balance of $100 and a credit of $50, and will lose $130, the balance will be -$30, while the credit will remain $50.

icon

How to change leverage on a trading account?

To change the leverage on a trading account, you need to retrieve the systemUuid and the trading account login. Then, send the following request:

Bash
curl --location --request PUT '{{baseURL}}/v1/trading-account/leverage?systemUuid={{systemUuid}}&login={{login}}' \
--header 'Authorization: {{APIkey}}' \
--header 'Content-Type: application/json' \
--data '{
  "leverage": "100"
}'

A 204 status indicates that the leverage has been successfully changed.

icon

How to create a trading account with specific parameters (currency, leverage, etc.)?

The trading account parameters such as currency, leverage, account type (Demo or Real) and more, are determined by the settings of the group and the corresponding offer in the Match-Trader system. If you want to create, for example, a Demo trading account with 1:30 leverage and currency set to EUR, you first need to:

  1. Create a group in the admin panel (backend) with the desired parameters.
  2. Create an offer assigned to that group, with EUR as the currency, leverage set to 30, and the Demo type enabled.

Once the group and offer are configured, you can send a request to create the account: For a usser account:

Bash
POST {{baseURL}}/v1/accounts

For a trading account under an exsiting user account:

Bash
POST {{baseURL}}/v1/accounts/{{accountUuid}}/trading-accounts

Make sure to include the offerUuid in the request body. The system will then create the trading account using the parameters defined in the selected offer.

icon

What is an offer and how do I configure it?

An Offer is a trading account configuration created and managed manually in the CRM. It cannot be created or modified via API - the API allows read-only access (GET) to Offer data.

An Offer maps to a specific trading group configured in the trading system backend (admin). That group defines all detailed trading conditions for the trader, such as commissions, markups, symbols, execution rules, and other broker-specific settings.

For the end user (trader):

  • the Offer name is displayed in the top-left corner of the trading platform,
  • the Offer type (e.g. Demo or Real) is clearly indicated.

From a functional perspective, an Offer defines:

  • what type of trading account will be created for the client,
  • with which basic parameters, such as: real or demo account, trading system (e.g. MTT / MT5), account currency, initial leverage and more.

An Offer must exist in order to create a trading account correctly. It is mandatory when creating a trading account via API - the request must include a valid offerUUID.

Based on the provided offerUUID, the system automatically creates the trading account using the configuration defined in the Offer and its mapped trading group.

icon

What is the "Fixed Amount Book" Mechanism for Prop Trading?

The "Fixed Amount Book" mechanism for Prop Trading was introduced to handle cryptocurrency payments where the user must pay a precise, fixed amount (e.g., for a challenge fee). The statuses FULLY_PAID and PARTIALLY_PAID were created to handle scenarios where the amount sent to the blockchain wallet does not exactly match the declared amount.

Purpose: Designed for Prop Trading challenges where users must pay a specific, fixed fee (e.g., $100 for a challenge) using cryptocurrency.

Functionality:

  • It "freezes" the exchange rate for a set time (default 5 minutes) to ensure the user pays the exact required amount in crypto.
  • It allows only one open "Fixed Amount" transaction per trading account at a time.
  • It introduces a "Declared Amount" field to track what the user should pay versus what was actually received.

Why new statuses were created?

PARTIALLY_PAID: Created to handle cases where the user sends less crypto than required (e.g., due to network fees or user error). The system marks it as partially paid, and the funds are not fully booked until the remainder is sent. It is considered a final status (like DONE) but indicates incomplete payment. FULLY_PAID: Created to confirm that the user sent the exact or greater amount than declared. It is equivalent to DONE but specifically signals that the fixed amount condition has been met, triggering actions like account activation or challenge start.

icon

What is the difference between deposit status FAILED and FAILED_PAYMENT?

The difference between FAILED and FAILED_PAYMENT lies in the stage of the process where the error occurred. FAILED is a general status indicating that the transaction failed within the internal system (e.g., due to a timeout, validation error, or rejection by the broker), while FAILED_PAYMENT specifically indicates a failure on the payment provider's side (e.g., declined card, payment gateway error).

FAILED:

  • Indicates a general failure of the transaction within the broker's system.
  • Can be caused by internal validation errors, timeouts (e.g., trading API timeout), manual rejection by an admin, or system errors.
  • Often used when the transaction logic itself fails or is cancelled internally.

FAILED_PAYMENT:

  • Specifically indicates that the payment process failed at the Payment Service Provider (PSP) level.
  • Used when the payment gateway returns an error, declines the transaction, or fails to process the funds.
  • In the CRM/MTR interface, this status informs the user that the issue lies with the payment method rather than the broker's internal logic.
icon

API Key, Token & HMAC

The API key is the key that authorizes the user and must be sent in the request headers of each Broker API request. It is assigned to a specific CRM user account and inherits the same permissions as that account. For example, if an API key is generated for an Admin CRM user, it will have Admin-level rights.

Additional permission layers and request limits can be configured in CRM Back Office → API Access. This is also where API keys are generated and managed.

Tokens and HMACs for the MTR Broker Management application are generated in the Admin panel under the Special Accounts section. There, Admin and Manager accounts are created and granted access to the Admin and Manager applications. The token and HMAC generated in Special Accounts should not be used in Broker API queries

These tokens act as login credentials (similar to a username and password) and are used to authenticate.

Was this section helpful?

What made this section unhelpful for you?

On this page
  • FAQ