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:
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