Profit and Loss (PNL)

The Profit and Loss (PNL) API endpoints provide tools to retrieve detailed financial performance metrics for trading keys and exchanges. These endpoints allow you to track daily PNL data, calculate the total sum of PNL and investment over time, and navigate large datasets with pagination.

Info

Profit and Loss (PNL) is a financial statement that summarizes the revenues, costs, and expenses incurred during a specified period, usually a fiscal quarter or year. PNL provides insights into a company's ability to generate profit by increasing revenue, reducing costs, or both.

The following sections outline how to use these endpoints, including required parameters, request examples in various programming languages, and sample responses for common use cases.

Get PNL Overview

Method: POST
Endpoint: /api/v1/pnl/overview
Description: Retrieves an overview of Profit and Loss (PNL) data, summarized over different time periods and trading pairs.

Parameters

Name	Type	Required	Description
`timezone`	`string`	Yes	The timezone to use for calculating date ranges (e.g., `Europe/Amsterdam`).
`keys`	`array`	Yes	An array of trading keys (e.g., `['binance/USDT-BTC', 'binance/USDT-XRP']`). Use ['All'] to get all the results.
`dateRange`	`object`	No	Optional custom date range. If provided, it must be in the format `{ startDate: 1733743909461, endDate: 1734348709461 }`.

Examples

cURL

curl -X POST "https://your-gunbot-instance.com:3000/api/v1/pnl/overview" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "Europe/Amsterdam",
    "keys": ["All"],
    "dateRange": { "startDate": 1733743909461, "endDate": 1734348709461 }
  }'

JavaScript (fetch API)

const body = {
  timezone: 'Europe/Amsterdam',
  keys: ['All'],
  dateRange: { startDate: 1733743909461, endDate: 1734348709461 }
};

fetch('https://your-gunbot-instance.com:3000/api/v1/pnl/overview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(data => console.log(data));

Python (requests library)

import requests

data = {
    'timezone': 'Europe/Amsterdam',
    'keys': ['All'],
    'dateRange': { 'startDate': 1733743909461, 'endDate': 1734348709461 }
}

headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Content-Type': 'application/json'
}

response = requests.post('https://your-gunbot-instance.com:3000/api/v1/pnl/overview', json=data, headers=headers)
print(response.json())

Response

{
  "today": {
    "pnl": 0,
    "perPair": {}
  },
  "yesterday": {
    "pnl": 0
  },
  "weekAgo": {
    "pnl": 13.966174729957487
  },
  "monthAgo": {
    "pnl": 172.26520619518234
  },
  "yearAgo": {
    "pnl": 172.26520619518234,
    "perPair": {
      "binance/BTC-ADA": {...},
      "binance/BTC-DOGE": {...}
    }
  },
  "total": {
    "pnl": 172.26520619518234,
    "numberOfTrades": 106,
    "heroTrade": {
      "pnl": 43.28911255406681,
      "time": 1733099150422
    },
    "fuckupTrade": {
      "pnl": -2.1478359571630734,
      "time": 1732896563996
    },
    "averagePnl": 1.6251434546715315,
    "sellCount": 21,
    "buyCount": 85,
    "winning": 6,
    "losing": 0,
    "breakeven": 8,
    "winRate": "100.0",
    "buyPnl": 0,
    "sellPnl": 172.26520619518234,
    "buyBaseValue": 4270.679722132944,
    "sellBaseValue": 3291.7711708390443
  },
  "lastYear": {
    "pnl": 0
  },
  "dailyHistory": [
    {
      "date": "2024-11-22",
      "numberOfTrades": 1,
      "totalVolume": 39.113713719480394,
      "pnl": 0,
      "cumulativePnl": 0,
      "cumulativePnlPercent": 0
    },
    ...
  ],
  "pnlsPerPair": [
    {
      "key": "binance/BTC-ADA",
      "pnl": 120.91196932835516
    },
    {
      "key": "binance/BTC-DOGE",
      "pnl": 51.35323686682719
    }
  ],
  "detailedPerPair": [
    {
      "strategy": "stepgrid",
      "cumulative_pnl": 0.001224695617080708,
      "cumulative_profit": 0.0012591197692164793,
      "cumulative_loss": -0.00003442415213577119,
      "cumulative_fees": 0.000052610508000000016,
      "cumulative_costproceed_wins": 0.022683785508000005,
      "cumulative_costproceed_losses": 0.0010369140480000001,
      "profit_count": 17,
      "loss_count": 2,
      "unique_profit_count": 7,
      "unique_loss_count": 0,
      "buy_count": 55,
      "sell_count": 19,
      "unique_buy_count": 55,
      "unique_sell_count": 7,
      "cumulative_buy_value": 0.028866064000000004,
      "cumulative_sell_value": 0.023744444,
      "daily_pnl_per_thousand": "16.74",
      "unrealized_pnl": -0.0003144618476607431,
      "key": "binance/BTC-ADA"
    },
    ...
  ],
  "unit": "USDT"
}

Get Daily PNL

Method: GET
Endpoint: /api/v1/pnl/daily
Description: Retrieves daily Profit and Loss (PNL) data for a specific trading key within a given time range.

Parameters

Name	Type	Required	Description
`key`	`string`	Yes	The trading key (e.g., `binance/USDT-XRP`). URL-encode if necessary (e.g., `binance%2FUSDT-XRP`).
`startTimestamp`	`number`	Yes	Start timestamp in milliseconds since epoch (e.g., `0`).
`endTimestamp`	`number`	Yes	End timestamp in milliseconds since epoch (e.g., `Date.now()`).

Examples

cURL

curl -X GET "https://your-gunbot-instance.com:3000/api/v1/pnl/daily?key=binance%2FUSDT-XRP&startTimestamp=0&endTimestamp=1733307452623" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

JavaScript (fetch API)

const params = new URLSearchParams({
  key: 'binance/USDT-XRP', // URL-encoded automatically
  startTimestamp: 0,
  endTimestamp: Date.now()
});

fetch(`https://your-gunbot-instance.com:3000/api/v1/pnl/daily?${params.toString()}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Python (requests library)

import requests

params = {
    'key': 'binance/USDT-XRP',
    'startTimestamp': 0,
    'endTimestamp': 1733307452623
}

headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
}

response = requests.get('https://your-gunbot-instance.com:3000/api/v1/pnl/daily', params=params, headers=headers)
print(response.json())

Response

{
  "dateRangeDailyHistory": [],
  "unmatchedBaseValuePerDateRange": 0
}

Get Paginated Daily PNL

Method: GET
Endpoint: /api/v1/pnl/daily/paginated
Description: Retrieves paginated daily PNL data for a specific trading key, allowing for efficient data handling and navigation through large datasets.

Parameters

Name	Type	Required	Description
`key`	`string`	Yes	The trading key (e.g., `binance/USDT-XRP`). URL-encode if necessary.
`pageNum`	`number`	Yes	The page number to retrieve (e.g., `1`).
`pageSize`	`number`	Yes	The number of records per page (e.g., `10`).
`endTime`	`number`	Yes	End timestamp in milliseconds since epoch (e.g., `Date.now()`).

Examples

cURL

curl -X GET "https://your-gunbot-instance.com:3000/api/v1/pnl/daily/paginated?key=binance%2FUSDT-XRP&pageNum=1&pageSize=10&endTime=1733307452649" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

JavaScript (fetch API)

const params = new URLSearchParams({
  key: 'binance/USDT-XRP',
  pageNum: 1,
  pageSize: 10,
  endTime: Date.now()
});

fetch(`https://your-gunbot-instance.com:3000/api/v1/pnl/daily/paginated?${params.toString()}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Python (requests library)

import requests

params = {
    'key': 'binance/USDT-XRP',
    'pageNum': 1,
    'pageSize': 10,
    'endTime': 1733307452649
}

headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
}

response = requests.get('https://your-gunbot-instance.com:3000/api/v1/pnl/daily/paginated', params=params, headers=headers)
print(response.json())

Response

{
  "totalSize": 0,
  "data": []
}

Get PNL Sum for Exchange

Method: GET
Endpoint: /api/v1/pnl/sum
Description: Retrieves the total sum of PNL and investment for a specific exchange over a given time range.

Parameters

Name	Type	Required	Description
`exchange`	`string`	Yes	The exchange key (e.g., `binance/USDT-XRP`). URL-encode if necessary.
`startTimestamp`	`number`	Yes	Start timestamp in milliseconds since epoch (e.g., `0`).
`endTimestamp`	`number`	Yes	End timestamp in milliseconds since epoch (e.g., `Date.now()`).

Examples

cURL

curl -X GET "https://your-gunbot-instance.com:3000/api/v1/pnl/sum?exchange=binance%2FUSDT-XRP&startTimestamp=0&endTimestamp=1733307452649" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

JavaScript (fetch API)

const params = new URLSearchParams({
  exchange: 'binance/USDT-XRP',
  startTimestamp: 0,
  endTimestamp: Date.now()
});

fetch(`https://your-gunbot-instance.com:3000/api/v1/pnl/sum?${params.toString()}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Python (requests library)

import requests

params = {
    'exchange': 'binance/USDT-XRP',
    'startTimestamp': 0,
    'endTimestamp': 1733307452649
}

headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
}

response = requests.get('https://your-gunbot-instance.com:3000/api/v1/pnl/sum', params=params, headers=headers)
print(response.json())

Response

{
  "tournamentData": {
    "sommaPnl": "0.00000000",
    "invested": "0.00000000"
  },
  "data": []
}

Get Total PNL for Trading Key

Method: GET
Endpoint: /api/v1/pnl/total
Description: Retrieves the total PNL for a specific trading key.

Parameters

Name	Type	Required	Description
`key`	`string`	Yes	The trading key (e.g., `binance/USDT-XRP`). URL-encode if necessary.

Examples

cURL

curl -X GET "https://your-gunbot-instance.com:3000/api/v1/pnl/total?key=binance%2FUSDT-XRP" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

JavaScript (fetch API)

const params = new URLSearchParams({
  key: 'binance/USDT-XRP'
});

fetch(`https://your-gunbot-instance.com:3000/api/v1/pnl/total?${params.toString()}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Python (requests library)

import requests

params = {
    'key': 'binance/USDT-XRP'
}

headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
}

response = requests.get('https://your-gunbot-instance.com:3000/api/v1/pnl/total', params=params, headers=headers)
print(response.json())

Response

{}

Note: Replace YOUR_TOKEN_HERE with your actual authorization token in the headers. Ensure that all query parameters are properly URL-encoded, especially if they contain special characters like / or #.

Profit and Loss (PNL)

Get PNL Overview​

Parameters​

Examples​

cURL​

JavaScript (fetch API)​

Python (requests library)​

Response​

Get Daily PNL​

Parameters​

Examples​

cURL​

JavaScript (fetch API)​

Python (requests library)​

Response​

Get Paginated Daily PNL​

Parameters​

Examples​

cURL​

JavaScript (fetch API)​

Python (requests library)​

Response​

Get PNL Sum for Exchange​

Parameters​

Examples​

cURL​

JavaScript (fetch API)​

Python (requests library)​

Response​

Get Total PNL for Trading Key​

Parameters​

Examples​

cURL​

JavaScript (fetch API)​

Python (requests library)​

Response​

Get PNL Overview

Parameters

Examples

cURL

JavaScript (fetch API)

Python (requests library)

Response

Get Daily PNL

Parameters

Examples

cURL

JavaScript (fetch API)

Python (requests library)

Response

Get Paginated Daily PNL

Parameters

Examples

cURL

JavaScript (fetch API)

Python (requests library)

Response

Get PNL Sum for Exchange

Parameters

Examples

cURL

JavaScript (fetch API)

Python (requests library)

Response

Get Total PNL for Trading Key

Parameters

Examples

cURL

JavaScript (fetch API)

Python (requests library)

Response