Changelog
Introduction

Sections

Changelog

Theme switcher

Step-by-Step Integration Process

Authentication and API Access

To begin integration with the Match-Trade CRM, you need:

  • Bearer Token (APIKey) - obtained from the client (broker)
  • Base URL - specific to the client's environment. Example URL for the UAT environment: https://broker-api-demo.match-trader.com/

The API key should be kept secure and not shared publicly

API Overview

The Match-Trade Broker API provides two interfaces:

  • REST API - The primary interface for most integration needs
  • gRPC - For streaming live data in advanced scenarios (e.g., monitoring stop-loss events or position openings)

Initial Connection Test

To verify your connection is working correctly:

Bash
curl --location '{baseURL}/service-info' \
--header 'Authorization: {APIkey}'

A successful response (HTTP 200) indicates that your authentication is working properly.

Key Configuration Elements

Offers

  • Offers cannot be created via API
  • They must be pre-configured by the client during setup
  • Offers are linked to groups in the backend system
  • You'll need to retrieve available offers UUID to create trading accounts

Roles

  • Each trader (account) should have the 'User' role
  • Other roles like 'IB' or 'Sub_IB' exist but are for our internal CRM use
  • For external integration: Always assign the 'User' role when creating accounts

Integration Steps

1

Retrieve Available Offers

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

The response contains a lot of important information including:

  • offerUuid
  • partnerId
  • groupName
  • branchUuid
  • systemUuid
  • operationUuid

Store these values as they will be required for subsequent API calls.

2

Create User Account and Trading Account

Bash
curl --location '{baseURL}/v1/accounts' \
--header 'Content-Type: application/json' \
--header 'Authorization: {APIkey}' \
--data-raw '{
  "email": "blatata@match-trade.com",
  "password": "abcd1234",
  "offerUuid": "offer_uuid_from_step_1",
  "personalDetails": {
    "firstname": "Testfirstname",
    "lastname": "TestLastname"
  }
}'
  • When you specify the offerUuid, a user account will be created along with a trading account under the selected offer. Without this parameter, only the user account will be created.
  • Passwords are encrypted immediately by the system. Neither you nor the Match-Trade system will have access to the user's plain text password after account creation.
3

Optional: Create Only Trading Account

Bash
curl --location '{baseURL}/v1/accounts/{accountUuid}/trading-accounts' \
--header 'Content-Type: application/json' \
--header 'Authorization: {APIkey}' \
--data '{
  "offerUuid": "offer_uuid_from_step_1"
}'

This will create a trading account linked to the user account and the specified offer (group).

4

Optional: Check if Account Already Exists

Before creating a new account, you may want to check if it already exists:

Bash
curl --location '{baseURL}/v1/accounts/by-email/blatata@match-trade.com' \
--header 'Authorization: {APIkey}'

If the account exists, you'll receive its details. If not, you'll get an error response.

5

Managing Account Deposits and Withdrawals

Important notes about payment gateways:

  • Payment gateways are pre-configured by Match-Trade or the client 
  • For external integration, use gateways with "method": "MANUAL"
  • The gateway currency must match the trading account currency (e.g., USD gateway for USD accounts)
  • If a gateway for a specific currency is missing, it must be manually configured by the client

For demo accounts:

  • Demo trading accounts can be created on offers with "demo": true
  • Demo offers typically have a pre-configured "initialDeposit" value (e.g., 1000.00)
  • It is possible to add a deposit to a demo account via the payment gateway
  • It is possible to withdraw funds from the demo account via a payment gateway

For handling deposits and withdrawals, you need to use payment gateways, get them by:

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

To add balance to the trading account, you need to send this request:

Bash
curl --location '{baseURL}/v1/deposits/manual' \
--header 'Content-Type: application/json' \
--header 'Authorization: {APIkey}' \
--data '{
  "systemUuid": "system_uuid_from_step_1",
  "login": "trading_account_login_from_step_2_or_step_3",
  "paymentGatewayUuid": "payment_gateway_uuid_from_step_5",
  "amount": 150,
  "comment": "testDeposit"
}'

Withdraw funds (deduct balance) should be used:

Bash
curl --location '{baseURL}/v1/withdrawals/manual' \
--header 'Content-Type: application/json' \
--header 'Authorization: {APIkey}' \
--data '{
  "systemUuid": "system_uuid_from_step_1",
  "login": "trading_account_login_from_step_2_or_step_3",
  "paymentGatewayUuid": "payment_gateway_uuid_from_step_5",
  "amount": 100,
  "comment": "testWithdrawal"
}'
6

Optional: Get Open Positions

Retrieves the list of currently open trading positions. You can filter by individual logins, groups, and set a maximum number of results.

Bash
curl --location '{{baseURL}}/v1/trading-accounts/trading-data/open-positions' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{APIkey}}' \
--data '{
  "systemUuid": "{{systemUuid}}",
  "logins": ["login1","login2"],
  "groups": ["group_name"],
  "limit": 15
}'

7

Optional: Get Closed Positions History

Fetches historical data on positions that have been closed. Supports filtering by time range, account logins, groups, and optional locking/blocking flags.

Bash
curl --location '{{baseURL}}/v1/trading-accounts/trading-data/closed-positions' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{APIkey}}' \
--data ‘{
  "systemUuid": "{{systemUuid}}",
  "logins": ["login1", "login2"],
  "groups": ["group_name"],
  "from": "2025-06-18T00:00:00.000Z",
  "to": "2027-05-14T00:00:00.000Z",
  "includeLocked": "",
  "includeBlocked": "",
  "limit": null
}'

8

Optional: Get Ledgers

Returns a chronological ledger of financial operations (e.g. deposits, withdrawals) on trading accounts. You can filter by operation type, account logins, groups and time window.

Bash
curl --location '{{baseURL}}/v1/trading-accounts/trading-data/ledgers' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{APIkey}}' \
--data '{
  "systemUuid": "{{systemUuid}}",
  "types": ["DEPOSIT","WITHDRAWAL"],
  "logins": ["login1","login2"],
  "groups": ["group_name"],
  "from": "",
  "to": "",
  "limit": null
}'

Was this section helpful?

What made this section unhelpful for you?

On this page
  • Step-by-Step Integration Process