Profit and Loss (PNL)

Use these endpoints to retrieve PNL metrics for trading keys and exchanges, track daily PNL, calculate totals over time, and page through large datasets.

Info

Profit and Loss (PNL) summarizes revenues, costs, and expenses over a period and indicates profitability.

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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/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:3001/api/v1/pnl/total', params=params, headers=headers)
print(response.json())

Response

{}

---

Note: Replace YOUR_TOKEN_HERE with your authorization token in the headers. URL-encode query parameters that include special characters such as / or #.