Retrieving Trading Account Financial Data

This section describes all available API methods that external CRM providers (including PROP firms) can use to retrieve and monitor the status of trading accounts.

Real-time balance and equity stream

CRM providers operating in the Forex space typically poll accounts in bulk to get up-to-date status information such as profit, loss, and account balance. These systems often use both single-account and group-based data fetching methods.

gRPC Stream: getClientEquityStream

This stream allows real-time monitoring of equity and balance values for selected trading accounts or entire account groups.

Authorization: Bearer {{APIKey}}

 
{
  "systemUuid": "system_uuid",
  "logins": ["login1", "login2"],
  "groups": ["group_name"]
}

• logins: array of specific trading account numbers to monitor.
• groups: array of group names - recommended: only one group per connection.

💡 Best Practice: Listen to one group per stream connection. This prevents future performance degradation, as a single group can contain up to 10,000 trading accounts.

The systemUuid is a unique and immutable identifier for each server. It can be retrieved via the following endpoint:

 
curl --location '{{baseURL}}/v1/offers' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{APIkey}}'

Stream Response Example:

 
{
  "equity": {
    "login": "413586",
    "equity": "5560.95",
    "balance": "5560.95",
    "credit": "0.00"
  }
}

Periodic Account Status Fetching via REST API

If real-time streaming is not required, and it's sufficient to check account status periodically (e.g., every few minutes), the following REST API endpoint can be used to retrieve current trading account information, including balance and equity.

Endpoint:

 
curl --location --globoff '{{baseURL}}/v1/trading-account?systemUuid={{systemUuid}}&login={{login}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{APIKey}}'

Query Parameters:

• systemUuid – unique identifier of the trading server (retrievable via /v1/offers)
• login – trading account number to be fetched

Response example:

 
{
  "uuid": "3f168829-80a5-48ce-aa11-41cad249dcee",
  "login": "7198",
  "created": "2024-05-24T10:42:08.412Z",
  "accountInfo": {
    "uuid": "aafff59c-ad8d-41c6-b577-b22d1359f475",
    "email": "test@match-trade.com"
  },
  "offerUuid": "f6cbaca3-cc96-4275-a784-12659032b544",
  "systemUuid": "8e9ed851-1e5e-479b-aa19-bade6a67d1d5",
  "commissionUuid": null,
  "group": "testUSD",
  "leverage": 100,
  "access": "FULL",
  "accountType": "REAL",
  "financeInfo": {
    "balance": 618509.43,
    "equity": 618720.93,
    "profit": 0,
    "netProfit": 0,
    "margin": 0.00,
    "freeMargin": 618720.93,
    "marginLevel": 0,
    "credit": 211.50,
    "currency": "USD",
    "currencyPrecision": 2
  }
}

This method is suitable for integrations where polling is acceptable and instant reaction to changes is not critical. It allows external systems to fetch the full financial snapshot of an individual trading account in a lightweight and reliable way.