Wallet - PnL Details

curl --request POST \
  --url https://public-api.birdeye.so/wallet/v2/pnl/details \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "wallet": "123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D",
  "sort_by": "value",
  "duration": "7d",
  "sort_type": "asc",
  "limit": 2,
  "token_addresses": [
    "2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV"
  ]
}
'

import requests

url = "https://public-api.birdeye.so/wallet/v2/pnl/details"

payload = {
    "wallet": "123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D",
    "sort_by": "value",
    "duration": "7d",
    "sort_type": "asc",
    "limit": 2,
    "token_addresses": ["2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV"]
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    wallet: '123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D',
    sort_by: 'value',
    duration: '7d',
    sort_type: 'asc',
    limit: 2,
    token_addresses: ['2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV']
  })
};

fetch('https://public-api.birdeye.so/wallet/v2/pnl/details', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "meta": {
      "address": "123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D",
      "currency": "usd",
      "holding_check": false,
      "time": "2025-10-31T08:38:25.295882105Z"
    },
    "tokens": [
      {
        "symbol": "G7",
        "decimals": 6,
        "address": "2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV",
        "counts": {
          "total_buy": 1,
          "total_sell": 1,
          "total_trade": 2
        },
        "quantity": {
          "total_bought_amount": 6152601.258849,
          "total_sold_amount": 6152601.258849,
          "holding": 0
        },
        "cashflow_usd": {
          "cost_of_quantity_sold": 9.7233729560565,
          "total_invested": 9.7233729560565,
          "total_sold": 9.85555342050984,
          "current_value": 0
        },
        "pnl": {
          "realized_profit_usd": 0.13218046445334128,
          "realized_profit_percent": 1.3594095901773329,
          "unrealized_usd": 0,
          "unrealized_percent": 0,
          "total_usd": 0.13218046445334128,
          "total_percent": 1.3594095901773329,
          "avg_profit_per_trade_usd": 0.13218046445334128
        },
        "pricing": {
          "current_price": null,
          "avg_buy_cost": 0.0000015803678065552884,
          "avg_sell_cost": 0.0000016018514780776761
        }
      }
    ],
    "summary": {
      "unique_tokens": 7,
      "counts": {
        "total_buy": 19,
        "total_sell": 19,
        "total_trade": 38,
        "total_win": 4,
        "total_loss": 1,
        "win_rate": 0.5714285714285714
      },
      "cashflow_usd": {
        "total_invested": 424.183016567611,
        "total_sold": 555.080692928933,
        "current_value": 392.84271337031083
      },
      "pnl": {
        "realized_profit_usd": 130.8976763613221,
        "realized_profit_percent": 30.858773512554855,
        "unrealized_usd": 0,
        "total_usd": 130.8976763613221,
        "avg_profit_per_trade_usd": 3.444675693719003
      }
    }
  }
}

{
  "success": false,
  "message": "Bad request"
}

{
  "success": false,
  "message": "Unauthorized"
}

{
  "success": false,
  "message": "Access Denied"
}

{
  "success": false,
  "message": "Too many requests"
}

{
  "success": false,
  "message": "Internal Server Error"
}

POST

wallet

pnl

details

Wallet - PnL Details

curl --request POST \
  --url https://public-api.birdeye.so/wallet/v2/pnl/details \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "wallet": "123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D",
  "sort_by": "value",
  "duration": "7d",
  "sort_type": "asc",
  "limit": 2,
  "token_addresses": [
    "2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV"
  ]
}
'

import requests

url = "https://public-api.birdeye.so/wallet/v2/pnl/details"

payload = {
    "wallet": "123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D",
    "sort_by": "value",
    "duration": "7d",
    "sort_type": "asc",
    "limit": 2,
    "token_addresses": ["2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV"]
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    wallet: '123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D',
    sort_by: 'value',
    duration: '7d',
    sort_type: 'asc',
    limit: 2,
    token_addresses: ['2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV']
  })
};

fetch('https://public-api.birdeye.so/wallet/v2/pnl/details', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "meta": {
      "address": "123hJZ8FGVhesDUrv5dCgorewd7KMqBkFhoGdyZNp62D",
      "currency": "usd",
      "holding_check": false,
      "time": "2025-10-31T08:38:25.295882105Z"
    },
    "tokens": [
      {
        "symbol": "G7",
        "decimals": 6,
        "address": "2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV",
        "counts": {
          "total_buy": 1,
          "total_sell": 1,
          "total_trade": 2
        },
        "quantity": {
          "total_bought_amount": 6152601.258849,
          "total_sold_amount": 6152601.258849,
          "holding": 0
        },
        "cashflow_usd": {
          "cost_of_quantity_sold": 9.7233729560565,
          "total_invested": 9.7233729560565,
          "total_sold": 9.85555342050984,
          "current_value": 0
        },
        "pnl": {
          "realized_profit_usd": 0.13218046445334128,
          "realized_profit_percent": 1.3594095901773329,
          "unrealized_usd": 0,
          "unrealized_percent": 0,
          "total_usd": 0.13218046445334128,
          "total_percent": 1.3594095901773329,
          "avg_profit_per_trade_usd": 0.13218046445334128
        },
        "pricing": {
          "current_price": null,
          "avg_buy_cost": 0.0000015803678065552884,
          "avg_sell_cost": 0.0000016018514780776761
        }
      }
    ],
    "summary": {
      "unique_tokens": 7,
      "counts": {
        "total_buy": 19,
        "total_sell": 19,
        "total_trade": 38,
        "total_win": 4,
        "total_loss": 1,
        "win_rate": 0.5714285714285714
      },
      "cashflow_usd": {
        "total_invested": 424.183016567611,
        "total_sold": 555.080692928933,
        "current_value": 392.84271337031083
      },
      "pnl": {
        "realized_profit_usd": 130.8976763613221,
        "realized_profit_percent": 30.858773512554855,
        "unrealized_usd": 0,
        "total_usd": 130.8976763613221,
        "avg_profit_per_trade_usd": 3.444675693719003
      }
    }
  }
}

{
  "success": false,
  "message": "Bad request"
}

{
  "success": false,
  "message": "Unauthorized"
}

{
  "success": false,
  "message": "Access Denied"
}

{
  "success": false,
  "message": "Too many requests"
}

{
  "success": false,
  "message": "Internal Server Error"
}

Usage Note
Accessibility
Chain Supported

Detailed wallet PnL breakdown.

Maximum number of tokens per request body is 100.
Body parameters include wallet, optional token_addresses, duration, position_scope, pnl_method, sort_by, sort_type, offset, and limit.
limit supports 1 to 100, and offset supports up to 10,000.
Use this endpoint when you need wallet-level summary plus token-level breakdown in one request.

Compute Unit ⚙️

This endpoint consumes 30 CU per request.

Use Cases 💡

Drill from wallet-level PnL into token-level contributors in one call.
Sort and page through the assets that drove gains or losses.
Support research views that need both summary and breakdown without multiple round trips.

How to Use 🛠️

Set the supported PnL chain in x-chain.
Send the wallet address in the POST body.
Optionally restrict the breakdown with token_addresses.
Set pnl_method=netcash or pnl_method=wac when you need to lock the accounting method used in the result.
Use offset, limit, sort_by, and sort_type to control the returned token rows.

Best Practices ✅

Start with the summary endpoint when you need only headline metrics, then switch to details when the wallet warrants investigation.
Restrict token_addresses for focused investigations instead of always requesting a full breakdown.
Keep sort order stable across pagination so result slices are reproducible.

Authorizations

X-API-KEY

string

header

required

API key for authentication

Headers

x-chain

enum<string>

default:solana

The chain support PNL data.

Available options:

solana,

ethereum,

arbitrum,

avalanche,

bsc,

optimism,

polygon,

base,

zksync,

monad,

hyperevm,

mantle,

megaeth,

robinhood

Body

application/json

wallet

string

required

Example:

"5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1"

token_addresses

string[]

Example:

[
  "2VKDTnMF9hmDfCG4i7yPHsfYzYCRhLwQcgUQPxvvYKnV"
]

duration

enum<string>

default:all

Available options:

all,

90d,

30d,

7d,

24h

position_scope

enum<string>

default:duration_only

Calculation mode for PnL. duration_only calculates PnL only for each selected time bucket. cumulative calculates realized_pnl cumulatively from the start time, while unrealized_pnl is based on the all-time open position. Defaults to duration_only.

Available options:

duration_only,

cumulative

pnl_method

string

PNL calculation method. wac (Weighted Average Cost): calculates PNL for each sell against the average cost of the position held at the time of the sell. Buys only re-average the cost of the remaining inventory, and previously realized sell PNL is not affected by later trades. netcash (Net Cash): calculates PNL across the full trade history using the spread between cumulative average sell price and cumulative average buy price. The buy average includes all buys and is not reduced by sells, so later buys can change the reported PNL.

sort_type

enum<string>

default:desc

Available options:

asc,

desc

sort_by

enum<string>

default:last_trade

Available options:

last_trade

limit

integer

default:10

Required range: 1 <= x <= 100

offset

integer

default:0

Required range: 0 <= x <= 10000

Response

JSON object containing a wallet

data

object

required

Show child attributes

success

boolean

Whether the request succeeded.