Methods for PnL monitoring
Use these methods to monitor profit-and-loss by assets and users:
GET[host]/back-api/backoffice/pnl/assets |
|
POST[host]/back-api/backoffice/pnl/users |
|
GET[host]/back-api/backoffice/pnl/total |
|
POST[host]/back-api/backoffice/pnl/actual |
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).
- asset
- rootAsset
string
The root asset set for the exchange.
{
"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
— Active1
— Frozen2
— 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).
- user
- rootAsset
string
The root asset set for the exchange.
{
"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.
- assetId
{
"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
— Active1
— Frozen2
— 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).
- user
- rootAsset
string
The root asset set for the exchange.
{
"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"
}