Wallet PnL by Token

This GraphQL query provides detailed financial metrics, including unrealized and realized profit and loss (PnL), current balance, and transaction insights for each token held by a specific wallet address.

Credit Cost

TBD

Supported Chains

• BASE_MAINNET
• BSC_MAINNET
• ETH_MAINNET
• GNOSIS_MAINNET
• POLYGON_MAINNET
• OPTIMISM_MAINNET
• MEGAETH_MAINNET

This query is currently in Beta. It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. No API credits are currently charged.

We welcome your feedback so please reach out to us directly to report issues or request features.

Parameters

Parameter	Type	Required	Description
chain_name	enum	Yes	Chain name to filter events (e.g., BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
wallet_address	string	Yes	The wallet address to query

Query

You can query the upnlForWallet endpoint to retrieve detailed PnL metrics for a wallet.

Basic Query

query {
 upnlForWallet(
    chain_name: ETH_MAINNET
    wallet_address: "0xfe97b0C517a84F98fc6eDe3CD26B43012d31992a"
  ) {
    token_address
    cost_basis
    current_price
    pnl_realized_usd
    pnl_unrealized_usd
    net_balance_change
  }
}

Complete Query

query{ 
upnlForWallet(
    chain_name:ETH_MAINNET,
    wallet_address:"0xfe97b0C517a84F98fc6eDe3CD26B43012d31992a"
  ) {
    token_address
    cost_basis
    current_price
    pnl_realized_usd
    pnl_unrealized_usd
    net_balance_change
    marketcap_usd
    contract_metadata {
      contract_address
      contract_name
      contract_ticker_symbol
      contract_decimals
    }
  }
}

Response Format

Here’s an example of the response data structure:

{
  "data": {
    "upnlForWallet": [
      {
        "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
        "cost_basis": 0.03219392,
        "current_price": 0.032418,
        "pnl_realized_usd": null,
        "pnl_unrealized_usd": 318.22842,
        "net_balance_change": "1420158",
        "marketcap_usd": "32418001.4431",
        "contract_metadata": {
          "contract_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
          "contract_name": "Covalent X Token",
          "contract_ticker_symbol": "CXT",
          "contract_decimals": 18
        }
      }
    ]
  }
}

Field Descriptions

Field	Type	Description
token_address	string	Token contract address (lowercase, 0x-prefixed)
cost_basis	float	Average cost basis per token in USD
current_price	float	Current market price per token in USD
pnl_realized_usd	float	Realized PnL in USD from completed trades
pnl_unrealized_usd	float	Unrealized PnL in USD at the latest price
net_balance_change	string	Net token movement (inflow minus outflow, past 7 days)
marketcap_usd	string	Estimated market capitalization in USD
contract_metadata	object	Token contract metadata