> ## Documentation Index
> Fetch the complete documentation index at: https://data.birdeye.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet - PnL (Per Token)

> Retrieve all-time trading, holdings, cash flow, PnL, and pricing metrics for each specified token in a given wallet.

<Tabs>
  <Tab title="Usage Note">
    <p><strong>Per-token wallet PnL.</strong></p>

    <ul>
      <li>Maximum number of tokens per request is <code>50</code>.</li>
      <li>Notes on data: trade data per protocol aren't backfilled and might affect the calculation of PnL.</li>
      <li><code>pnl\_method</code> supports <code>netcash</code> and <code>wac</code> so you can align the response with your accounting method.</li>
      <li><code>meta</code>:</li>
      <li><code>address</code>: wallet address.</li>
      <li><code>currency</code>: the currency in which PnL is calculated, such as USD.</li>
      <li><code>tokens\[\<token\_address>]</code> includes counts, quantity, cashflow, PnL, and pricing blocks for each token.</li>
      <li>Insights in the response:</li>
      <li><code>counts</code>:</li>
      <li><code>total\_buy</code>: Total number of buy trades.</li>
      <li><code>total\_sell</code>: Total number of sell trades.</li>
      <li><code>total\_trade</code>: Combined total of buys and sells.</li>
      <li><code>total\_win</code>: Total trades have profit. Only account for fully realized tokens.</li>
      <li><code>total\_loss</code>: Total trades in loss. Only account for fully realized tokens.</li>
      <li><code>win\_rate</code>: Winning rate. Only account for fully realized tokens.</li>
      <li><code>cashflow\_usd</code>:</li>
      <li><code>total\_invested</code>: USD spent on all buys.</li>
      <li><code>total\_sold</code>: USD received from sales.</li>
      <li><code>current\_value</code>: Current position value in USD.</li>
      <li><code>pnl</code>:</li>
      <li><code>realized\_profit\_usd</code>: Profit/loss from completed trades.</li>
      <li><code>realized\_profit\_percent</code>: % gain/loss relative to sold cost basis.</li>
      <li><code>unrealized\_usd</code>: Profit/loss of current holdings (mark-to-market).</li>
      <li><code>total\_usd</code>: Sum of realized + unrealized profit in USD.</li>
      <li><code>avg\_profit\_per\_trade\_usd</code>: Average profit/loss per trade.</li>
      <li>Quantity fields are already normalized by token decimals.</li>
    </ul>
  </Tab>

  <Tab title="Accessibility">
    <ul>
      <li>Lite</li>
      <li>Starter</li>
      <li>Premium</li>
      <li>Business</li>
      <li>Enterprise</li>
    </ul>
  </Tab>

  <Tab title="Chain Supported">
    <p><strong>SVM ⛓️ ✨</strong></p>
    <p><strong>EVM ⛓️ ✨</strong></p>
  </Tab>
</Tabs>

<Accordion title="Compute Unit ⚙️" icon="fa-gauge-high">
  <ul>
    <li>Batch CU is calculated as <code>ceil(10 \* wallet\_count^0.8)</code>.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  <ul>
    <li>Break a wallet's PnL down token by token.</li>
    <li>Identify which assets drove gains, losses, and current unrealized exposure.</li>
    <li>Power wallet analytics views that need realized and unrealized PnL per holding.</li>
  </ul>
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  <ul>
    <li>Set the supported PnL chain in <code>x-chain</code>.</li>
    <li>Pass the wallet address in <code>wallet</code>.</li>
    <li>Pass up to <code>50</code> token addresses in <code>token\_addresses</code>.</li>
    <li>Set <code>pnl\_method</code> explicitly when the output needs to match another reporting workflow or PnL view.</li>
    <li>Read <code>pricing</code>, <code>cashflow\_usd</code>, and <code>pnl</code> together to understand both execution and current exposure.</li>
  </ul>
</Accordion>

<Accordion title="Best Practices ✅" icon="fa-check-circle">
  <ul>
    <li>Use this endpoint when you already know which token set you want to evaluate.</li>
    <li>Compare <code>current\_value</code> with <code>total\_invested</code> and <code>total\_sold</code> to separate realized outcomes from open positions.</li>
    <li>Treat this endpoint as deprecated over time and prefer newer summary/detail flows where they better fit the product.</li>
  </ul>
</Accordion>

<br />


## OpenAPI

````yaml openapi/data/openapi_docs.json GET /wallet/v2/pnl
openapi: 3.1.0
info:
  version: 1.1.0
  title: Birdeye Data API
  description: >-
    Birdeye Data API is a full-spectrum blockchain and DEX data platform for
    teams that need production-grade crypto market intelligence across tokens,
    pairs, wallets, traders, protocols, and chains.


    From real-time prices, OHLCV, liquidity, and transaction flow to holder
    analytics, token and pair overviews, wallet portfolio and PnL, smart money,
    discovery, security, and blockchain-level utilities, Birdeye gives you a
    unified data layer for building serious crypto products at scale.


    Use it to power exchange interfaces, trading terminals, bots, market-making
    systems, quant research, alpha screeners, portfolio apps, wallet
    intelligence tools, alerting systems, analytics dashboards, and back-office
    data pipelines. Whether your users are retail traders, pro desks, analysts,
    or infrastructure teams, Birdeye helps you ship faster with broad market
    coverage and API surfaces that support both lightweight integrations and
    data-heavy workflows.


    To start, create an account at [bds.birdeye.so](https://bds.birdeye.so),
    generate an API key from the `Security` tab, and send it in the `X-API-KEY`
    header on every request.
servers:
  - url: https://public-api.birdeye.so
security:
  - apiKeyAuth: []
tags:
  - name: Price & OHLCV
  - name: Stats
  - name: Token/Market List
  - name: Transactions
  - name: Wallet, Networth & PnL
  - name: Balance & Transfer
  - name: Holder
  - name: Alltime & History
  - name: Blockchain
  - name: Account
  - name: Token
  - name: Transaction
  - name: Creation & Trending
  - name: Meme
  - name: Security
  - name: Search & Utils
  - name: Smart Money
  - name: Global Fees Paid
  - name: DEX & Protocol
  - name: Wallet Identity
paths:
  /wallet/v2/pnl:
    get:
      tags:
        - Wallet, Networth & PnL
      summary: Wallet - PnL (Per Token)
      description: >-
        Retrieve all-time trading, holdings, cash flow, PnL, and pricing metrics
        for each specified token in a given wallet.
      operationId: get-wallet-v2-pnl
      parameters:
        - $ref: '#/components/parameters/xPNLChainParam'
        - $ref: '#/components/parameters/walletAddressParam'
        - $ref: '#/components/parameters/tokenAddressesParam'
        - $ref: '#/components/parameters/optionalPnlMethod'
      responses:
        '200':
          $ref: '#/components/responses/WalletPnlResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      deprecated: true
components:
  parameters:
    xPNLChainParam:
      name: x-chain
      description: The chain support PNL data.
      in: header
      required: false
      schema:
        type: string
        enum:
          - solana
          - ethereum
          - arbitrum
          - avalanche
          - bsc
          - optimism
          - polygon
          - base
          - zksync
          - monad
          - hyperevm
          - mantle
          - megaeth
          - robinhood
        default: solana
    walletAddressParam:
      name: wallet
      description: The wallet of the account.
      in: query
      required: true
      schema:
        type: string
      examples:
        solana:
          value: eJpBLoF3bgXpzjxqJRAvMchjEo4EqdAmiQh3ASmEtZT
    tokenAddressesParam:
      name: token_addresses
      description: List of token address.
      in: query
      required: true
      schema:
        type: string
      examples:
        solana:
          value: >-
            pumpsAkNcb1nZs89Uees3DyRzUGxjqThuzF3A8LVVfn,So11111111111111111111111111111111111111112
    optionalPnlMethod:
      name: pnl_method
      description: >-
        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.
      in: query
      required: false
      schema:
        type: string
        enum:
          - wac
          - net_cash
        default: net_cash
      example: net_cash
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Bad request
    '401':
      description: Unauthorized. API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Unauthorized
    '403':
      description: Forbidden. Request is blacklisted or not whitelisted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Access Denied
    '429':
      description: Too Many Requests. Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Too many requests
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Internal Server Error
    WalletPnlResponse:
      description: JSON object containing a wallet’s PnL per token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletPnlResponseSchema'
          examples:
            Solana:
              value:
                success: true
                data:
                  meta:
                    address: 4mwReoK1x668B6KuuSAbGm2tUQULSTHGgTpCa2jUMXtD
                    currency: usd
                    holding_check: false
                    time: '2025-08-27T14:06:48.987054346Z'
                  tokens:
                    So11111111111111111111111111111111111111112:
                      symbol: SOL
                      decimals: 9
                      counts:
                        total_buy: 236570
                        total_sell: 236570
                        total_trade: 473140
                      quantity:
                        total_bought_amount: 12092390.76837637
                        total_sold_amount: 0.00047313999999776897
                        holding: 0
                      cashflow_usd:
                        cost_of_quantity_sold: 0.07608073802599198
                        total_invested: 1944451989.1810136
                        total_sold: 0.07602689546632857
                        current_value: 0
                      pnl:
                        realized_profit_usd: -0.00005384255966340998
                        realized_profit_percent: -0.0707702909572399
                        unrealized_usd: 523529777.302561
                        unrealized_percent: 26.92428407777512
                        total_usd: 523529777.30250716
                        total_percent: 26.92428407671888
                        avg_profit_per_trade_usd: -2.275967352724774e-10
                      pricing:
                        current_price: 204.09378209627866
                        avg_buy_cost: 160.79963229984938
                        avg_sell_cost: 160.6858339322126
                    pumpsAkNcb1nZs89Uees3DyRzUGxjqThuzF3A8LVVfn:
                      symbol: PUMP
                      decimals: 9
                      counts:
                        total_buy: 236570
                        total_sell: 236570
                        total_trade: 473140
                      quantity:
                        total_bought_amount: 1.9012623099995465
                        total_sold_amount: 128820503932.7875
                        holding: 880839335.5814558
                      cashflow_usd:
                        cost_of_quantity_sold: 5151221341.162621
                        total_invested: 0.07602689546632857
                        total_sold: 1944451989.1810136
                        current_value: 7.5417466875590655
                      pnl:
                        realized_profit_usd: -0.04732872112474718
                        realized_profit_percent: -62.25260262759055
                        unrealized_usd: 0
                        unrealized_percent: 0
                        total_usd: -0.04732872112474718
                        total_percent: -62.25260262759055
                        avg_profit_per_trade_usd: -2.0006222735235735e-7
                      pricing:
                        current_price: 8.562000336395786e-9
                        avg_buy_cost: 0.03998758880690519
                        avg_sell_cost: 0.015094274046587626
  schemas:
    WalletPnlResponseSchema:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
        data:
          type: object
          properties:
            meta:
              type: object
              description: Resolved wallet and valuation context for the response.
              properties:
                address:
                  type: string
                  description: Wallet address whose PnL was requested.
                currency:
                  type: string
                  description: Display currency used for valuation.
                holding_check:
                  type: boolean
                  description: >-
                    Whether current holdings were included in the PnL
                    calculation.
                time:
                  type: string
                  description: Timestamp of the PnL snapshot.
            tokens:
              type: object
              description: Map keyed by token address to per-token PnL details.
              additionalProperties:
                $ref: '#/components/schemas/WalletPnlToken'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    WalletPnlToken:
      type: object
      additionalProperties: true
      description: Per-token PnL, position, and trading metrics for one wallet-token pair.
      properties:
        symbol:
          type: string
          description: Token symbol.
        decimals:
          type: integer
          description: Number of token decimals.
        address:
          type: string
          description: Token mint or contract address.
        counts:
          type: object
          additionalProperties: true
          properties:
            total_buy:
              type:
                - number
                - string
              description: Total number of buy trades.
            total_sell:
              type:
                - number
                - string
              description: Total number of sell trades.
            total_trade:
              type:
                - number
                - string
              description: Combined total number of buy and sell trades.
            total_win:
              type:
                - number
                - string
              description: Number of realized winning trades or tokens.
            total_loss:
              type:
                - number
                - string
              description: Number of realized losing trades or tokens.
            win_rate:
              type:
                - number
                - string
              description: Winning rate across realized trades or tokens.
        quantity:
          type: object
          additionalProperties: true
          properties:
            total_bought_amount:
              type:
                - number
                - string
              description: Total token quantity bought.
            total_sold_amount:
              type:
                - number
                - string
              description: Total token quantity sold.
            holding:
              type:
                - number
                - string
              description: Current token quantity still held.
        cashflow_usd:
          type: object
          additionalProperties: true
          properties:
            cost_of_quantity_sold:
              type:
                - number
                - string
              description: Cost basis in USD for the quantity that has been sold.
            total_invested:
              type:
                - number
                - string
              description: Total USD spent on buys.
            total_sold:
              type:
                - number
                - string
              description: Total USD received from sells.
            current_value:
              type:
                - number
                - string
              description: Current USD market value of the remaining position.
        pnl:
          type: object
          additionalProperties: true
          properties:
            realized_profit_usd:
              type:
                - number
                - string
              description: Realized profit and loss in USD.
            realized_profit_percent:
              type:
                - number
                - string
              description: Realized profit and loss percentage relative to sold cost basis.
            unrealized_usd:
              type:
                - number
                - string
              description: Unrealized mark-to-market profit and loss in USD.
            unrealized_percent:
              type:
                - number
                - string
              description: Unrealized mark-to-market profit and loss percentage.
            total_usd:
              type:
                - number
                - string
              description: Combined realized and unrealized profit and loss in USD.
            total_percent:
              type:
                - number
                - string
              description: Combined realized and unrealized profit and loss percentage.
            avg_profit_per_trade_usd:
              type:
                - number
                - string
              description: Average profit and loss per trade in USD.
        pricing:
          type: object
          additionalProperties: true
          properties:
            current_price:
              type:
                - number
                - 'null'
              description: Current indexed token price in USD.
            avg_buy_cost:
              type:
                - number
                - 'null'
              description: Average buy cost per token in USD.
            avg_sell_cost:
              type:
                - number
                - 'null'
              description: Average sell price per token in USD.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````