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

# Wallet PnL by Token Query

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.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per call </Card>

  <Card title="Supported Chains">
    * `BASE_MAINNET`
    * `BSC_MAINNET`
    * `ETH_MAINNET`
    * `GNOSIS_MAINNET`
    * `MEGAETH_MAINNET`
    * `OPTIMISM_MAINNET`
    * `POLYGON_MAINNET`
  </Card>
</CardGroup>

<Tip>
  Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fstreaming-api%2Fqueries%2Fupnl-for-wallet-query).
</Tip>

## Parameters

<ParamField body="chain_name" type="enum" required>
  Blockchain network to filter events
</ParamField>

<ParamField body="wallet_address" type="string" required>
  The wallet address to query
</ParamField>

## Query

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

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

## Response Format

Here's an example of the response data structure:

```json theme={null}
{
  "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

<ResponseField name="cost_basis" type="float">
  Cost basis per token
</ResponseField>

<ResponseField name="contract_metadata" type="object">
  Token contract metadata

  Type: [`TokenContractMetadata`](/api-reference/streaming-api/types/token-contract-metadata)

  <Expandable title="properties">
    <ResponseField name="contract_name" type="string">
      Name of the token contract
    </ResponseField>

    <ResponseField name="contract_address" type="string">
      Address of the token contract
    </ResponseField>

    <ResponseField name="contract_decimals" type="int">
      Number of decimal places for the token
    </ResponseField>

    <ResponseField name="contract_ticker_symbol" type="string">
      Ticker symbol of the token
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="net_balance_change" type="string">
  Net token movement (inflow - outflow) in the last 7 days, not the actual on-chain balance
</ResponseField>

<ResponseField name="token_address" type="string">
  Token contract address (lowercase with 0x prefix)
</ResponseField>

<ResponseField name="current_price" type="float">
  Current price per token
</ResponseField>

<ResponseField name="pnl_realized_usd" type="float">
  Realized profit and loss in USD
</ResponseField>

<ResponseField name="pnl_unrealized_usd" type="float">
  Unrealized profit and loss in USD
</ResponseField>

<ResponseField name="marketcap_usd" type="string">
  Market capitalization in USD
</ResponseField>