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
  • Ethereum Mainnet
  • Gnosis Mainnet
  • Polygon Mainnet
  • Optimism 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

ParameterTypeRequiredDescription
chain_nameenumYesChain name to filter events (e.g., BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
wallet_addressstringYesThe wallet address to query

​
Query

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

​
Basic Query

query {
 upnlForToken(
    chain_name: ETH_MAINNET
    wallet_address: "0xfe97b0C517a84F98fc6eDe3CD26B43012d31992a"
  ) {
    token
    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
    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": "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

FieldTypeDescription
tokenstringToken contract address, represented in uppercase with a 0x prefix
cost_basisfloatSimple Average cost basis per token in USD
current_pricefloatCurrent market price per token in USD
pnl_realized_usdfloatRealized profit or loss in USD from completed trades
pnl_unrealized_usdfloatCurrent unrealized profit or loss in USD based on the latest price
net_balance_changeBigIntegerNet token movement (inflow minus outflow) over the past 7 days
marketcap_usdstringToken’s estimated market capitalization in USD
contract_metadataobjectContains metadata details for the token contract

​
GraphQL Playground