Home Admin guide Platform API Methods for PnL monitoring

Methods for PnL monitoring

Use these methods to monitor profit-and-loss by assets and users:

GET[host]/back-api/backoffice/pnl/assets

Get PnL by assets

POST[host]/back-api/backoffice/pnl/users

Get PnL by users

GET[host]/back-api/backoffice/pnl/total

Get the total PnL for a time period

POST[host]/back-api/backoffice/pnl/actual

Get the current user PnL

Get PnL by assets

Use this method to view the current PnL values calculated for each asset traded by a specific exchange user.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Query parameters:

from

The earliest date and time for which the data must be obtained: YYYY-MM-DDThh:mm:ss.

When unspecified (null), all data is returned that was obtained before the latest specified date.

to

The latest date and time for which the data must be obtained: YYYY-MM-DDThh:mm:ss.

When unspecified (null), all data is returned that was obtained after the earliest specified date.

user

The username or email (to return entries matching this string).

GET[host]/back-api/backoffice/pnl/assets

GET /back-api/backoffice/pnl/assets
    ?from=2020-09-01
    &to=2020-10-01
    &user=user@mailexample.com HTTP/1.1
Host: host.name
Authorization: Bearer akvmn34egjidg0jifgjdg0djg34g

Response

assetPnl array

The following information is provided about each user asset:

asset string

The asset name.

balance string

The user balance in this asset.

balanceInRootAsset string

The user balance in this asset, in conversion to the platform root asset (based on the latest conversion rate).

tradedVolume string

The total asset volume traded.

tradedVolumeInRootAsset string

The total asset volume traded, in conversion to the platform root asset (based on the latest conversion rate).

commission string

The total commission charged in this asset.

commissionInRootAsset string

The total commission charged in this asset, in conversion to the platform root asset (based on the latest conversion rate).

pnl string

Obsolete: see the realizedPnl value instead.

pnlInRootAsset string

Obsolete: see the realizedPnl value instead.

realizedPnl string

The user realized PnL, in conversion to the platform root asset (based on the rates effective as of the moment of each historical transaction).

unrealizedPnl string

The user unrealized PnL, in conversion to the platform root asset (based on the average rate obtained for the time period specified in the request).

rootAsset string

The root asset set for the exchange.

RESPONSE EXAMPLE 
{
  "assetsPnl": [
    {
      "asset": "btc",
      "balance": "2002247250025.19922623",
      "balanceInRootAsset": "98264122737056631.94463428",
      "tradedVolume": "747821.84629745",
      "tradedVolumeInRootAsset": "36700790918.35441147",
      "commission": "392787.83797129",
      "commissionInRootAsset": "19276816247.11842812",
      "pnl": "24562.80353902",
      "realizedPnl": "1205466678.35036720",
      "unrealizedPnl": "20000959450732697.26175941",
      "pnlInRootAsset": "1205466678.35036720"
      }
    ],
  "rootAsset": "usd"
}

Get PnL by users

Use this method to view the current PnL of specified exchange users.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Body:

from string

The earliest date and time for which the data must be obtained: YYYY-MM-DDThh:mm:ss.

When unspecified (null), all data is returned that was obtained before the latest specified date.

to string

The latest date and time for which the data must be obtained: YYYY-MM-DDThh:mm:ss.

When unspecified (null), all data is returned that was obtained after the earliest specified date.

page number

A zero-based integer value, specifying the page number for a paging response.

perPage number

The maximum number of entries to include in each paging response.

roles array

An array of string values, identifying the user roles:

Omit this parameter (leave it null) to obtain the complete list of users, regardless of their roles.

user string

The username or email (to return entries matching this string).

Omit this parameter (leave it null) to obtain the complete list of users.

POST[host]/back-api/backoffice/pnl/users

POST /back-api/backoffice/pnl/users
Host: host.name
Authorization: Bearer akvmn34egjidg0jifgjdg0djg34g

{
  "from":"2020-09-21T17:13:52.5444915Z",
  "to":null,
  "page":1,
  "perPage":10,
  "roles":["Trader"],
  "user":"usernameExample"
}

Response

usersPnl array

The following information is provided about each user:

user string

The user email.

userId string

The user identifier, in the GUID string format.

userRoles array

An array of string values, identifying the user roles.

activityStatus number

The user profile status:

  • 0 — Active

  • 1 — Frozen

  • 2 — Terminated

balanceInRootAsset string

The total user balance, in conversion to the platform root asset (based on the latest conversion rate).

tradedVolumeInRootAsset string

The total volume traded by the user, in conversion to the platform root asset (based on the latest conversion rate).

commissionInRootAsset string

The total commission paid by the user, in conversion to the platform root asset (based on the latest conversion rate).

pnlInRootAsset string

Obsolete: see the realizedPnl value instead.

realizedPnl string

The user realized PnL, in conversion to the platform root asset (based on the rates effective as of the moment of each historical transaction).

unrealizedPnl string

The user unrealized PnL, in conversion to the platform root asset (based on the average rate obtained for the time period specified in the request).

rootAsset string

The root asset set for the exchange.

RESPONSE EXAMPLE 
{
  "usersPnl": [
    {
      "user": "user1@mailexample.com",
      "userId": "e596e2c4-e376-3599-0d44-8dd5678a25bc",
      "userRoles": ["Trader"],
      "activityStatus": 0,
      "balanceInRootAsset": "0.00000001",
      "tradedVolumeInRootAsset": "0.0000044",
      "commissionInRootAsset": "0.00000001",
      "realizedPnl": "0.00000001",
      "unrealizedPnl": "0.00000001",
      "pnlInRootAsset": "0.00000001"
    },
    {
      "user": "user2@mailexample.com",
      "userId": "c9a2a84a-e392-1612-8cba-fbba12346029",
      "userRoles": ["Trader"],
      "activityStatus": 0,
      "balanceInRootAsset": "0.00000001",
      "tradedVolumeInRootAsset": "0.0000084",
      "commissionInRootAsset": "0.0000001",
      "realizedPnl": "0.00000001",
      "unrealizedPnl": "0.00000001",
      "pnlInRootAsset": "0.0000001"
    }
  ],
  "rootAsset": "usd"
}

Get the total PnL for a time period

Use this method to view the PnL values calculated for each asset traded by every exchange user during a specified time period.

Note

A user asset is not included in the response if the RateToRootAsset field is not specified for the asset, meaning that it cannot be converted to the platform root asset and its PnL value cannot be obtained.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Query parameters:

from

The earliest date and time for which the data must be obtained: YYYY-MM-DDThh:mm:ss.

When unspecified (null), all data is returned that was obtained before the latest specified date.

to

The latest date and time for which the data must be obtained: YYYY-MM-DDThh:mm:ss.

When unspecified (null), all data is returned that was obtained after the earliest specified date.

GET[host]/back-api/backoffice/pnl/total

GET /back-api/backoffice/pnl/total
    ?from=2020-09-01
    &to=2020-10-01 HTTP/1.1
Host: host.name
Authorization: Bearer akvmn34egjidg0jifgjdg0djg34g

Response

rootAsset string

The root asset set for the exchange.

pnl string

Obsolete: see the totalRealizedPnl value instead.

pnlInRootAsset string

Obsolete: see the totalRealizedPnl value instead.

totalRealizedPnl string

The realized PnL for all assets traded so far by a specific user, in conversion to the platform root asset (based on the rates effective as of the moment of each historical transaction).

totalUnrealizedPnl string

The unrealized PnL for all assets currently traded by a specific user, in conversion to the platform root asset (based on the average rate obtained for the time period specified in the request).

tradedVolume string

Obsolete: see the tradedVolumeInRootAsset value instead.

tradedVolumeInRootAsset string

The total volume traded by the user, in conversion to the platform root asset (based on the latest conversion rate).

commission string

Obsolete: see the commissionInRootAsset value instead.

commissionInRootAsset string

The total commission paid by the user in this asset, in conversion to the platform root asset (based on the latest conversion rate).

assets array

An array of objects, identifying the user assets.

Note

A user asset is not included in the response if the RateToRootAsset field is not specified for the asset, meaning that it cannot be converted to the platform root asset and its PnL value cannot be obtained.

The following information is provided about each user asset:

assetId string

The asset identifier.

rateToRootAsset string

The rate of converting the user asset to the platform root asset.

totalPnl string

Obsolete: see the totalRealizedPnl value instead.

totalPnlInRootAsset string

Obsolete: see the totalRealizedPnl value instead.

totalRealizedPnl string

The realized PnL based on the user asset amount traded so far, in conversion to the platform root asset (based on the rates effective as of the moment of each historical transaction).

totalUnrealizedPnl string

The unrealized PnL based for the user asset, in conversion to the platform root asset (based on the average rate obtained for the time period specified in the request).

totalVolume string

The total asset volume traded.

totalVolumeInRootAsset string

The total asset volume traded, in conversion to the platform root asset.

totalCommission string

The total commission charged in this asset.

totalCommissionInRootAsset string

The total commission charged in this asset, in conversion to the platform root asset.

RESPONSE EXAMPLE 
{
  "rootAsset": "usd",
  "pnl": "0.00000001",
  "pnlInRootAsset": "0.00000001",
  "totalRealizedPnl": "0.00000001",
  "totalUnrealizedPnl": "0.00000001",
  "tradedVolume": "0.00000001",
  "tradedVolumeInRootAsset": "0.00000001",
  "commission": "0.00000001",
  "commissionInRootAsset": "0.00000001",
  "assets": [
    {
      "assetId": "btc",
      "rateToRootAsset": "3.00000001",
      "totalPnl": "0.00000001",
      "totalPnlInRootAsset": "0.00000001",
      "totalRealizedPnl": "0.00000001",
      "totalUnrealizedPnl": "0.00000001",
      "totalVolume": "0.00000001",
      "totalVolumeInRootAsset": "0.00000001",
      "totalCommission": "0.00000001",
      "totalCommissionInRootAsset": "0.00000001"
    },
    {
      "assetId": "usd",
      "rateToRootAsset": "1.00000001",
      "totalPnl": "0.00000001",
      "totalPnlInRootAsset": "0.00000001",
      "totalRealizedPnl": "0.00000001",
      "totalUnrealizedPnl": "0.00000001",
      "totalVolume": "0.00000001",
      "totalVolumeInRootAsset": "0.00000001",
      "totalCommission": "0.00000001",
      "totalCommissionInRootAsset": "0.00000001"
    }
  ]
}

Get the current user PnL

Use this method to view the current PnL values calculated for individual exchange users for a certain time period.

You can specify which assets should be taken into account when evaluating PnL for each user. You can also obtain up-to-date PnL values for all assets that have ever been traded by users.

Request

Header parameters:

  • Authorization: Bearer <access_token>

Query parameters:

from

The earliest date and time for which the data must be obtained: YYYY-MM-DDThh:mm:ss.

When unspecified (null), all available data is returned.

user

The username or email (to return entries matching this string).

Omit this parameter (leave it null) to obtain the complete list of users.

asset

The asset identifier.

Omit this parameter (leave it null) to obtain the complete list of user assets.

POST[host]/back-api/backoffice/pnl/actual

POST /back-api/backoffice/pnl/actual
    ?from=2020-09-01
    &user=user@mailexample.com
    &asset=btc HTTP/1.1
Host: host.name
Authorization: Bearer akvmn34egjidg0jifgjdg0djg34g

Response

usersPnl object

The following information is provided about each user included in the response:

user string

The user email.

userId string

The user identifier, in the GUID string format.

userRoles array

An array of string values, identifying the user roles.

activityStatus number

The user profile status:

  • 0 — Active

  • 1 — Frozen

  • 2 — Terminated

balanceInRootAsset string

The total user balance, in conversion to the platform root asset (based on the latest conversion rate).

tradedVolumeInRootAsset string

The total volume traded by the user, in conversion to the platform root asset (based on the latest conversion rate).

commissionInRootAsset string

The total commission paid by the user, in conversion to the platform root asset (based on the latest conversion rate).

pnlInRootAsset string

Obsolete: see the realizedPnl value instead.

realizedPnl string

The realized PnL for the user assets specified in the request, in conversion to the platform root asset (based on the rates effective as of the moment of each historical transaction).

unrealizedPnl string

The unrealized PnL for the user assets specified in the request, in conversion to the platform root asset (based on the average rate obtained for the time period specified in the request).

rootAsset string

The root asset set for the exchange.

RESPONSE EXAMPLE 
{
  "usersPnl": [
    {
      "user": "user1@mailexample.com",
      "userId": "e596e2c4-e376-3599-0d44-8dd3792a25bc",
      "userRoles": ["Trader"],
      "activityStatus": 0,
      "balanceInRootAsset": "1.00000001",
      "tradedVolumeInRootAsset": "0.0000044",
      "commissionInRootAsset": "1.00000000",
      "realizedPnl": "0.00000001",
      "unrealizedPnl": "0.00000001",
      "pnlInRootAsset": "0.00000001"
    }
  ],
  "rootAsset": "usd"
}