Introduction

Sections

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.

Was this section helpful?

What made this section unhelpful for you?

Base URL

Sandbox:

https://broker-api-demo.match-trader.com

Was this section helpful?

What made this section unhelpful for you?

Integration Guide for CRM with Match-Trader Platform

This comprehensive integration guide provides external CRM providers with the necessary instructions for connecting their systems with the Match-Trader Platform. The following sections outline the architecture, step-by-step integration process, authentication methods, and best practices to ensure a seamless connection between your CRM solution and our trading ecosystem.

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:

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.

PYTHON
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?

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.

PROTOBUF
syntax = 'proto3'; import "google/protobuf/empty.proto"; option java_multiple_files = true; option java_package = 'com.matchtrade.broker_api.grpc'; package com.matchtrade.broker_api.grpc; service PositionsServiceExternal { rpc getClientPositionsStream (PBClientPositionRequestExternal) returns (stream PBPositionStreamResponseExternal) { } } 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 AccountInfoServiceExternal { rpc getAccountInfoChangedStream (PBAccountInfoChangedRequestExternal) returns (stream PBAccountInfoChangedStreamResponseExternal) { } } service SymbolsServiceExternal{ rpc getSymbolsChangedStream(PBSymbolChangedRequestExternal) returns (stream PBSymbolChangedStreamResponseExternal) {} } 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 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; } 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; } 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; } message PBLedgersRequestByGroupsOrLoginsExternal { string systemUuid = 1; repeated string logins = 2; repeated string groups = 3; repeated PBHistoryOperationTypeExternal historyOperationType = 4; } 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; } 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 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 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 PBAccountInfoUpdated { int64 login = 1; optional PBAccountInfoUpdatedDetails prev = 2; PBAccountInfoUpdatedDetails current = 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 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; } 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; }

Base URL

Sandbox:

https://broker-api-demo.match-trader.com

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.

Via our API you cannot edit Branches, Offers, and Roles configuration (it can be done only by using our CRM), but it's important to know them since you will need them to efficiently manage accounts created in the system. That's why we share GET endpoints, where you can check Branches, Offers, and Roles available in your setup.

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.

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.

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.

Prop Trading