Home B2Core API REST API The Back Office API Bonuses

Bonuses

Use these methods to manage bonuses allocated to clients.

GET[host]/api/v2/bonuses

Get a list of bonuses

GET[host]/api/v2/bonuses/{bonusId}

Get bonus details

POST[host]/api/v2/bonuses

Create a bonus

PUT[host]/api/v2/bonuses/{bonusId}

PATCH[host]/api/v2/bonuses/{bonusId}

Update a bonus

DELETE[host]/api/v2/bonuses/{bonusId}

Delete a bonus

Use these methods to update bonuses allocated to clients.

POST[host]/api/v2/bonuses/{bonusId}/continue

Extend a bonus

POST[host]/api/v2/bonuses/{bonusId}/hold

Hold a bonus

POST[host]/api/v2/bonuses/{bonusId}/reactivate

Reactivate a bonus

POST[host]/api/v2/bonuses/{bonusId}/revoke

Revoke a bonus

Use these methods to manage bonus templates configured in the Back Office.

GET[host]/api/v2/bonuses/presets

Get a list of bonus presets

GET[host]/api/v2/bonuses/presets{presetId}

Get bonus preset details

POST[host]/api/v2/bonuses/presets

Create a bonus preset

PUT[host]/api/v2/bonuses/presets{presetId}

PATCH[host]/api/v2/bonuses/presets{presetId}

Update a bonus preset

DELETE[host]/api/v2/bonuses/presets{presetId}

Delete a bonus preset

Use these methods to manage temporary bonus programs configured in the Back Office.

GET[host]/api/v2/bonuses/temporary

Get a list of temporary bonuses

GET[host]/api/v2/bonuses/temporary{temporaryId}

Get temporary bonus details

POST[host]/api/v2/bonuses/temporary

Create a temporary bonus

PUT[host]/api/v2/bonuses/temporary{temporaryId}

PATCH[host]/api/v2/bonuses/temporary{temporaryId}

Update a temporary bonus

DELETE[host]/api/v2/bonuses/presets{presetId}

Delete a temporary bonus

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.