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, provided to you together with your API key (referred to as
{baseURL}throughout this documentation)
The API key should be kept secure and not shared publicly.
API Overview
The Match-Trade CRM-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:
curl --location '{{baseURL}}/v1/offers' \
--header 'Content-Type: application/json' \
--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
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
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
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:
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:
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:
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:
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.
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.
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.
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
}'
On this page
- Step-by-Step Integration Process