Skip to main content
Once you have a wallet of interest, this recipe shows how to pull together everything you would display on a trader profile or dashboard: identity, performance stats, PnL, charts, trading history, and current holdings. A complete trader profile on re.defined.fi showing the identity header, network breakdown, realized PnL chart, volume calendar heatmap, per-token stats, and recent activity feed
Wallet timeframes (such as PnL and volume windows) are rolling periods. 1D is the last 24 hours, 1W is the last 7 days, and so on. They do not start at a fixed date or time of day.

​
Identity and Stats Overview

detailedWalletStats is the core endpoint for a dashboard. A single call returns both the wallet’s identity (display name, Ethos credibility, linked socials, identity labels) and its performance stats across rolling time windows, broken down by network. This is what you render as the header and primary metrics of a trader profile. Test this query in the Explorer → 
{
  detailedWalletStats(input: {
    walletAddress: "0xADDRESS"
    includeNetworkBreakdown: true
  }) {
    walletAddress
    lastTransactionAt
    labels
    scammerScore
    botScore

    statsDay30 {
      statsUsd {
        volumeUsd
        realizedProfitUsd
        realizedProfitPercentage
        soldTokenAcquisitionCostUsd
        heldTokenAcquisitionCostUsd
        averageProfitUsdPerTrade
      }
      statsNonCurrency {
        swaps
        uniqueTokens
        wins
        losses
        avgHoldPeriodSec
      }
    }

    wallet {
      address
      displayName
      avatarUrl
      description
      ethosScore
      ethosLevel
      ethosVerified
      twitterUsername
      discordUsername
      telegramUsername
      farcasterUsername
      githubUsername
      identityLabels
    }
  }
}
Available time windows: statsDay1, statsWeek1, statsDay30, statsYear1. Each provides the same field set for that rolling window. Request only the windows you need to display. Setting includeNetworkBreakdown: true returns per-network volume and hold period alongside the aggregate stats, which is useful when a wallet is active on multiple chains: A per-network breakdown on re.defined.fi showing volume share and average hold period for Ethereum, HyperEVM, BNB Chain, and others
Hold period vs. hold time. avgHoldPeriodSec estimates how long tokens are held based on a trader’s buy and sell rate over the window. It is not a measure of actual elapsed holding time. Returns null when there are no sells in the window. Display it as an indicator of conviction, not a precise duration.

​
Calculate Wallet PnL

PnL (profit and loss) is central to a trader dashboard. For the concepts behind how Codex calculates it, see the Wallet PnL page. This section covers the practical queries.

​
Overall realized PnL

The detailedWalletStats example above already returns realized PnL through statsUsd.realizedProfitUsd and statsUsd.realizedProfitPercentage for each window.

​
Per-token PnL

To see how a wallet performed on a specific token, use filterTokenWallets filtered to that wallet: Test this query in the Explorer → 
{
  filterTokenWallets(input: {
    tokenIds: ["0xTOKEN_ADDRESS:NETWORK_ID"]
    filtersV2: { walletAddress: { eq: "0xADDRESS" } }
  }) {
    results {
      walletAddress
      realizedProfitUsd30d
      tokenBalance
      tokenBalanceLive
      purchasedTokenBalance
    }
  }
}

​
Unrealized PnL

To estimate PnL on tokens still held, compare current value against acquisition cost: 
Unrealized PnL = Current Balance Value - Acquisition Cost
Two fields from filterTokenWallets give you the inputs:
  • tokenAcquisitionCostUsd — what the wallet paid for tokens it still holds
  • Current value — multiply tokenBalanceLive by the token’s current price (from getTokenPrices)
For an aggregate cost basis across all held tokens, heldTokenAcquisitionCostUsd from detailedWalletStats.statsUsd is the single-field equivalent.

​
PnL over time

For charting PnL progression, use walletChart. The realizedProfitUsd field in each data point gives time-series PnL at your chosen resolution. See the Visualize Wallet Activity section below.

​
Visualize Wallet Activity

walletChart returns time-series data for rendering performance charts and heatmaps: PnL progression, trading volume, and swap counts over time. Test this query in the Explorer → 
{
  walletChart(input: {
    walletAddress: "0xADDRESS"
    networkId: 1
    range: {
      start: 1739404800
      end: 1742083200
      resolution: "1D"
    }
  }) {
    walletAddress
    backfillState
    range {
      start
      end
      resolution
    }
    data {
      timestamp
      volumeUsd
      realizedProfitUsd
      swaps
    }
  }
}
A realized PnL line chart on the left and a daily volume calendar heatmap on the right, both for a single wallet on re.defined.fi Available resolutions: 60 (1-hour candles), 240 (4-hour candles), 1D (daily), 7D (weekly). Choose a resolution appropriate for your time range. Omit networkId for cross-chain aggregated data.

​
If Stats Look Empty

If detailedWalletStats or walletChart return empty or partial data, the wallet’s historical stats may still be processing. walletChart exposes the state directly in its response through backfillState. To check it ahead of time on any wallet, use walletAggregateBackfillState: Test this query in the Explorer → 
{
  walletAggregateBackfillState(input: { walletAddress: "0xADDRESS" }) {
    walletAddress
    status
  }
}
The status enum has six values:
StatusWhat it means
BackfillCompleteHistorical stats are ready
BackfillInProgressCurrently processing, retry shortly
BackfillRequestReceivedQueued, will start soon
BackfillNotFoundHas not been started — trigger one with backfillWalletAggregates
BackfillCanceledStarted, then canceled. Wallet may be flagged as a bot
BackfillBlockedBlocked. Wallet may be flagged as a bot

​
Trading History

For a per-transaction view of everything a wallet has done, use getTokenEventsForMaker. It returns the wallet’s individual swap events with full detail, including the global fees paid data on each event. Test this query in the Explorer → 
{
  getTokenEventsForMaker(query: {
    maker: "0xADDRESS"
    networkId: 1
  }) {
    items {
      transactionHash
      timestamp
      eventType
      eventDisplayType
      token0SwapValueUsd
      token1SwapValueUsd
      maker
    }
  }
}
A scrolling trading history feed on re.defined.fi showing individual swap events with token name, USD amount, and token amount per transaction
A single transaction may return multiple events for multi-hop swaps (Token A → B → C). Disambiguate client-side using the transaction hash if you only want the end-to-end swap.

​
Current Holdings

Complete the dashboard with a portfolio breakdown. balances returns the tokens a wallet currently holds with current balance and metadata. Test this query in the Explorer → 
{
  balances(input: {
    walletAddress: "0xADDRESS"
    networks: [1, 8453]
    removeScams: true
  }) {
    items {
      tokenAddress
      balance
      shiftedBalance
      token {
        name
        symbol
      }
    }
  }
}
A holdings table on re.defined.fi listing each token a wallet holds with amount, price, and USD value columns
ENS names are not supported on balances. For EVM wallets, native token balances require a network with traces enabled. On networks without traces, a native balance may still update when the wallet makes a swap, but without trace data those values can be updated inconsistently — treat them as approximate. Set removeScams: true to filter out tokens flagged as scams.

​
Bring It Together

A complete trader dashboard pulls from several endpoints:
  • Identity and performance: detailedWalletStats for display name, Ethos score, socials, identity labels, PnL, win rate, and hold period in one call
  • Per-token detail: filterTokenWallets for token-specific performance
  • Visualization: walletChart for time-series PnL, volume, and swap counts
  • History: getTokenEventsForMaker for the per-transaction feed
  • Holdings: balances for the current portfolio