Bonuses
Use these methods to manage bonuses allocated to clients.
GET[host]/api/v2/bonuses |
|
GET[host]/api/v2/bonuses/{bonusId} |
|
POST[host]/api/v2/bonuses |
|
PUT[host]/api/v2/bonuses/{bonusId} PATCH[host]/api/v2/bonuses/{bonusId} |
|
DELETE[host]/api/v2/bonuses/{bonusId} |
Use these methods to update bonuses allocated to clients.
POST[host]/api/v2/bonuses/{bonusId}/continue |
|
POST[host]/api/v2/bonuses/{bonusId}/hold |
|
POST[host]/api/v2/bonuses/{bonusId}/reactivate |
|
POST[host]/api/v2/bonuses/{bonusId}/revoke |
Use these methods to manage bonus templates configured in the Back Office.
GET[host]/api/v2/bonuses/presets |
|
GET[host]/api/v2/bonuses/presets{presetId} |
|
POST[host]/api/v2/bonuses/presets |
|
PUT[host]/api/v2/bonuses/presets{presetId} PATCH[host]/api/v2/bonuses/presets{presetId} |
|
DELETE[host]/api/v2/bonuses/presets{presetId} |
Use these methods to manage temporary bonus programs configured in the Back Office.
GET[host]/api/v2/bonuses/temporary |
|
GET[host]/api/v2/bonuses/temporary{temporaryId} |
|
POST[host]/api/v2/bonuses/temporary |
|
PUT[host]/api/v2/bonuses/temporary{temporaryId} PATCH[host]/api/v2/bonuses/temporary{temporaryId} |
|
DELETE[host]/api/v2/bonuses/presets{presetId} |
Get a list of bonuses
Use this method to obtain a list of bonuses allocated to clients.
Request
Header parameters:
Authorization: Bearer <token>
Query parameters:
The following filter parameters are available for this method:
- state
The bonus status. Possible values:
queued
active
pending
processing
completed
onCompleting
expired
error
hold
- account
The number of a client trading account to which the bonus is credited.
- clientEmail
The email address of a client who receives the bonus.
- clientId
The identifier of a client who receives the bonus.
- clientName
The name of a client who receives the bonus.
The following sorting parameter is available for this method:
- createTime
The date and time when a bonus was allocated.
Refer to the Query parameters section in the API Overview for details on applying filter and sorting parameters.
GET[host]/api/v2/bonuses
curl --location --request GET 'https://host.name/api/v2/bonuses?limit=10&offset=0&sort_order=desc&sort_by=createTime&filter[state]=active&filter[account]=4446546&filter[clientEmail]=email@example.com&filter[clientId]=1&filter[clientName]=name' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
A response contains an array of Bonus objects providing information about the bonuses matching the request parameters.
Get bonus details
Use this method to obtain detailed information about a specific bonus that was allocated to a client.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- bonusId required
The bonus identifier.
GET[host]/api/v2/bonuses/{bonusId}
curl --location --request GET 'https://host.name/api/v2/bonuses/:bonusId' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
A response contains a Bonus object providing information about the specified bonus.
Create a bonus
Use this method to allocate a bonus to a client.
Request
Header parameters:
Authorization: Bearer <token>
Body:
Specify the following parameters when allocating a bonus:
- accountId integer required
The identifier of a client trading account.
- amount string required
The bonus amount that can be awarded to clients under a bonus program.
- lifetime integer required
The number of days after which an activated bonus expires.
- dynamicLots string required
The required amount of traded volume for bonus crediting.
- enableAutoCredit boolean required
If
true
, bonuses from all bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading account immediately.If
false
, bonuses from different bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading accounts one after another. Only after a bonus from the first bonus program is processed and credited, a bonus from the second bonus program is credited to a client.- scalpingThreshold integer required
The minimum time interval (in seconds) during which a position must be opened.
- enableTrade boolean required
If
true
, trading with bonus funds is immediately allowed after depositing funds to a trading account; otherwise,false
.- disabledGroups array required
An array of string values specifying the instruments for which bonuses aren’t awarded.
POST[host]/api/v2/bonuses
curl --location --request POST 'https://host.name/api/v2/bonuses' \
--header 'accept-language: <string>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw'{
"accountId": 1,
"amount": "100.00",
"lifetime": 30,
"dynamicLots": "1.000",
"enableAutoCredit": true",
"scalpingThreshold": 1,
"enableTrade": true,
"disabledGroups": [
"USDCZK",
"EURJPY"
]
}'
Response
A response contains a Bonus object providing information about the allocated bonus.
Update a bonus
Use this method to update a bonus that has expired.
Note
Instead of the method described below, you can use a similar method that uses the HTTP verb PATCH.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- bonusId required
The bonus identifier.
Body:
The following field value can be updated for an expired bonus:
- fictiveVolumeComplete string
The volume that must be traded by a client to receive a bonus. Specifying the updated volume reactivates the expired bonus.
PUT[host]/api/v2/bonuses/{bonusId}
curl --location --request PUT 'https://host.name/api/v2/bonuses/:bonusId' \
--header 'accept-language: <string>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
"fictiveVolumeComplete": "125"
}'
Response
A response contains a Bonus object providing information about the bonus that was updated.
Delete a bonus
Use this method to cancel a bonus that was allocated to a client.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- bonusId required
The bonus identifier.
DELETE[host]/api/v2/bonuses/{bonusId}
curl --location --request DELETE 'https://host.name/api/v2/bonuses/:bonusId' \
--header 'Authorization: Bearer <token>'
Response
In case of success, no response body is returned.
Extend a bonus
Use this method to extend an allocated bonus.
Request
Header parameters:
Authorization: Bearer <token>
- bonusId required
The bonus identifier.
POST[host]/api/v2/bonuses/{bonusId}/continue
curl --location --request POST 'https://host.name/api/v2/bonuses/:bonusId/continue' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
In case of success, no response body is returned.
Hold a bonus
Use this method to put a pending bonus on hold.
Request
Header parameters:
Authorization: Bearer <token>
- bonusId required
The bonus identifier.
POST[host]/api/v2/bonuses/{bonusId}/hold
curl --location --request POST 'https://host.name/api/v2/bonuses/:bonusId/hold' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
In case of success, no response body is returned.
Reactivate a bonus
Use this method to reactivate an expired bonus.
Request
Header parameters:
Authorization: Bearer <token>
- bonusId required
The bonus identifier.
Body:
The following field value can be updated for an expired bonus:
- lifetime integer
The number of days after which an activated bonus expires.
POST[host]/api/v2/bonuses/{bonusId}/reactivate
curl --location --request POST 'https://host.name/api/v2/bonuses/:bonusId/reactivate' \
--header 'accept-language: <string>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
"lifetime": 10
}'
Response
In case of success, no response body is returned.
Revoke a bonus
Use this method to revoke a pending bonus.
Request
Header parameters:
Authorization: Bearer <token>
- bonusId required
The bonus identifier.
POST[host]/api/v2/bonuses/{bonusId}/revoke
curl --location --request POST 'https://host.name/api/v2/bonuses/:bonusId/revoke' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
In case of success, no response body is returned.
Get a list of bonus presets
Use this method to obtain a list of bonus presets configured in the Back Office.
Request
Header parameters:
Authorization: Bearer <token>
Query parameters:
The following filter parameters are available for this method:
- default
If
true
, a bonus preset is used as the default for all clients; oterwise,false
.- platform
The trading platform to which a bonus preset applies.
- name
The name of a preset.
The following sorting parameter is available for this method:
- createTime
The date and time when a bonus was allocated.
Refer to the Query parameters section in the API Overview for details on applying filter and sorting parameters.
GET[host]/api/v2/bonuses/presets
curl --location --request GET 'https://host.name/api/v2/bonuses/presets?limit=10&offset=0&sort_order=desc&sort_by=createTime&filter[default]=true&filter[platform]=MetaTrader4&filter[name]=MT4' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
A response contains an array of Bonus Preset objects providing information about the bonus presets matching the request parameters.
Get bonus preset details
Use this method to obtain detailed information about a specified bonus preset.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- presetId required
The identifier of a preset.
GET[host]/api/v2/bonuses/presets{presetId}
curl --location --request GET 'https://host.name/api/v2/bonuses/presets/:presetId' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
A response contains a Bonus Preset object providing information about the specified bonus preset.
Create a bonus preset
Use this method to create a new bonus preset.
Request
Header parameters:
Authorization: Bearer <token>
Body:
Specify the following parameters for a new bonus preset:
- platformId integer required
The identifier of a trading platform to which a bonus preset applies.
- name string required
The name of a preset.
- default boolean required
If
true
, a bonus preset is used as the default for all clients; oterwise,false
.- lifetime integer required
The number of days after which an activated bonus expires.
- dynamicLots string required
The required amount of traded volume for bonus crediting.
- enableAutoCredit boolean required
If
true
, bonuses from all bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading account immediately.If
false
, bonuses from different bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading accounts one after another. Only after a bonus from the first bonus program is processed and credited, a bonus from the second bonus program is credited to a client.- scalpingThreshold integer required
The minimum time interval (in seconds) during which a position must be opened.
- enableTrade boolean required
If
true
, trading with bonus funds is immediately allowed after depositing funds to a trading account; otherwise,false
.- disabledGroups array required
An array of string values specifying the instruments for which bonuses aren’t awarded.
POST[host]/api/v2/bonuses/presets
curl --location --request POST 'https://host.name/api/v2/bonuses/presets' \
--header 'accept-language: <string>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
"platformId": 1,
"name": "PresetMT5",
"default": true,
"lifetime": 10,
"dynamicLots": "1.000",
"enableAutoCredit": true,
"scalpingThreshold": 1,
"enableTrade": true,
"disabledGroups": [
"EURJPY"
]
}'
Response
A response contains a Bonus Preset object providing information about the created bonus preset.
Update a bonus preset
Use this method to update a specified bonus preset.
Note
Instead of the method described below, you can use a similar method that uses the HTTP verb PATCH.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- presetId required
The identifier of a preset.
Body:
The following field values can be updated for a specified bonus preset:
- name string
The name of a preset.
- default boolean
If
true
, a bonus preset is used as the default for all clients; oterwise,false
.- lifetime integer
The number of days after which an activated bonus expires.
- dynamicLots string
The required amount of traded volume for bonus crediting.
- enableAutoCredit boolean
If
true
, bonuses from all bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading account immediately.If
false
, bonuses from different bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading accounts one after another. Only after a bonus from the first bonus program is processed and credited, a bonus from the second bonus program is credited to a client.- scalpingThreshold integer
The minimum time interval (in seconds) during which a position must be opened.
- enableTrade boolean
If
true
, trading with bonus funds is immediately allowed after depositing funds to a trading account; otherwise,false
.- disabledGroups array
An array of string values specifying the instruments for which bonuses aren’t awarded.
PUT[host]/api/v2/bonuses/presets{presetId}
curl --location --request PUT 'https://host.name/api/v2/bonuses/presets/:presetId' \
--header 'accept-language: <string>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
"name": "PresetMT5",
"default": true,
"lifetime": 10,
"dynamicLots": "1.000",
"enableAutoCredit": true,
"scalpingThreshold": 1,
"enableTrade": true,
"disabledGroups": [
"EURJPY"
]
}'
Response
A response contains a Bonus Preset object providing information about the bonus preset that was updated.
Delete a bonus preset
Use this method to delete a specified bonus preset.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- presetId required
The identifier of a preset.
DELETE[host]/api/v2/bonuses/presets{presetId}
curl --location --request DELETE 'https://host.name/api/v2/bonuses/presets/:presetId' \
--header 'Authorization: Bearer <token>'
Response
In case of success, no response body is returned.
Get a list of temporary bonuses
Use this method to obtain a list of temporary bonus programs configured in the Back Office.
Request
Header parameters:
Authorization: Bearer <token>
Query parameters:
The following filter parameters are available for this method:
- id
The identifier of a temporary bonus program.
- name
The name of a bonus program displayed to clients in the B2Core UI.
The following sorting parameter is available for this method:
- createTime
The date and time when a bonus program was created.
Refer to the Query parameters section in the API Overview for details on applying filter and sorting parameters.
GET[host]/api/v2/bonuses/temporary
curl --location --request GET 'https://host.name/api/v2/bonuses/temporary?limit=10&offset=0&sort_order=desc&sort_by=createTime&filter[id]=1&filter[name]=MT5' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
A response contains an array of Temporary Bonus objects providing information about the temporary bonus programs matching the request parameters.
Get temporary bonus details
Use this method to obtain detailed information about a specified temporary bonus program.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- temporaryId required
The identifier of a temporary bonus program.
GET[host]/api/v2/bonuses/temporary{temporaryId}
curl --location --request GET 'https://host.name/api/v2/bonuses/temporary/:temporaryId' \
--header 'accept-language: <string>' \
--header 'Authorization: Bearer <token>'
Response
A response contains a Temporary Bonus object providing information about the specified temporary bonus program.
Create a temporary bonus
Use this method to create a new temporary bonus program.
Request
Header parameters:
Authorization: Bearer <token>
Body:
Specify the following parameters for a new temporary bonus program:
- platformId integer required
The identifier a trading platform for which a bonus program is available.
- name string required
The name of a bonus program displayed to clients in the B2Core UI.
- amount string required
The bonus amount that can be awarded to clients under a bonus program.
- currencyCode integer required
The bonus program currency. Only the trading accounts denominated in the specified currency can join a bonus program.
- platformGroups array required
An array of string values specifying the platform groups. Only trading accounts included in the specified groups can be awarded bonuses under a bonus program.
- expiredAt string required
The date and time when a bonus expires.
- lifetime integer required
The number of days after which an activated bonus expires.
- dynamicLots string required
The required amount of traded volume for bonus crediting.
- enableAutoCredit boolean required
If
true
, bonuses from all bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading account immediately.If
false
, bonuses from different bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading accounts one after another. Only after a bonus from the first bonus program is processed and credited, a bonus from the second bonus program is credited to a client.- scalpingThreshold integer required
The minimum time interval (in seconds) during which a position must be opened.
- enableTrade boolean required
If
true
, trading with bonus funds is immediately allowed after depositing funds to a trading account; otherwise,false
.- disabledGroups array required
An array of string values specifying the instruments for which bonuses aren’t awarded.
POST[host]/api/v2/bonuses/temporary
curl --location --request POST 'https://host.name/api/v2/bonuses/temporary' \
--header 'accept-language: <string>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
"platformId": 1,
"name": "MT5",
"amount": "100.00",
"currencyCode": 540,
"platformGroups": [
"EURJPY",
],
"expiredAt": "2022-01-01T00:00:00+00:00",
"lifetime": 10,
"dynamicLots": "1.000",
"enableAutoCredit": true,
"scalpingThreshold": 1,
"enableTrade": true,
"disabledGroups": [
"USDCZK"
]
}'
Response
A response contains a Temporary Bonus object providing information about the created temporary bonus program.
Update a temporary bonus
Use this method to update a specified temporary bonus program.
Note
Instead of the method described below, you can use a similar method that uses the HTTP verb PATCH.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- temporaryId required
The identifier of a temporary bonus program.
Body:
The following field values can be updated for a specified temporary bonus program:
- name string
The name of a bonus program displayed to clients in the B2Core UI.
- amount string
The bonus amount that can be awarded to clients under a bonus program.
- platformGroups array
An array of string values specifying the platform groups. Only trading accounts included in the specified groups can be awarded bonuses under a bonus program.
- expiredAt string
The date and time when a bonus expires.
- lifetime integer
The number of days after which an activated bonus expires.
- dynamicLots string
The required amount of traded volume for bonus crediting.
- enableAutoCredit boolean
If
true
, bonuses from all bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading account immediately.If
false
, bonuses from different bonus programs (if more than one is enabled for a client at the same time) are credited to the client’s trading accounts one after another. Only after a bonus from the first bonus program is processed and credited, a bonus from the second bonus program is credited to a client.- scalpingThreshold integer
The minimum time interval (in seconds) during which a position must be opened.
- enableTrade boolean
If
true
, trading with bonus funds is immediately allowed after depositing funds to a trading account; otherwise,false
.- disabledGroups array
An array of string values specifying the instruments for which bonuses aren’t awarded.
PUT[host]/api/v2/bonuses/temporary{temporaryId}
curl --location --request PUT 'https://host.name/api/v2/bonuses/temporary/:temporaryId' \
--header 'accept-language: <string>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
"name": "MT5",
"amount": "100.00",
"platformGroups": [
"USDCZK"
],
"expiredAt": "2022-01-01T00:00:00+00:00",
"lifetime": 10,
"dynamicLots": "1.000",
"enableAutoCredit": true,
"scalpingThreshold": 1,
"enableTrade": true,
"disabledGroups": [
"EURJPY"
]
}'
Response
A response contains a Temporary Bonus object providing information about the temporary bonus program that was updated.
Delete a temporary bonus
Use this method to delete a specified temporary bonus program.
Request
Header parameters:
Authorization: Bearer <token>
Path parameters:
- temporaryId required
The identifier of a temporary bonus program.
DELETE[host]/api/v2/bonuses/presets{presetId}
curl --location --request DELETE 'https://host.name/api/v2/bonuses/temporary/:temporaryId' \
--header 'Authorization: Bearer <token>'
Response
In case of success, no response body is returned.