Skip to main content
In this recipe we’ll show you how to filter for high-performing wallets, rank them by the metrics that matter to you, and narrow results by identity, socials, and labels. This data powers the trader discovery experience on re.defined.fi: A table of trader wallets on re.defined.fi showing PnL, volume, average hold period, win rate, and reputation columns
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.

​
Filter by Performance

Use filterWallets to surface wallets with strong trading performance. Combine numeric filters with a ranking to sort the results. All performance metrics are available across four windows: 1d, 1w, 30d, 1y. Append the window to the metric name (for example realizedProfitUsd30d, winRate1w, volumeUsd1y). Test this query in the Explorer → 
{
  filterWallets(input: {
    filters: { realizedProfitUsd30d: { gte: 10000 } }
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet {
        displayName
        ethosScore
        twitterUsername
      }
    }
  }
}
For a trade to count toward win rate, profit or loss must exceed $1 USD. volumeUsd only counts volume from tokens with a reliable USD price. Use volumeUsdAll to include volume from tokens without one.

​
Filter by Identity and Socials

Narrow discovery to wallets that have linked social accounts or a set display name. This is useful for surfacing public, identifiable traders rather than anonymous addresses. All identity filters accept true (must have) or false (must not have):
FilterWhat it checks
hasTwitterWallet has a linked Twitter/X account
hasDiscordWallet has a linked Discord account
hasTelegramWallet has a linked Telegram account
hasFarcasterWallet has a linked Farcaster account
hasGithubWallet has a linked GitHub account
hasDisplayNameWallet has a display name set
hasSocialsWallet has any linked social account
Test this query in the Explorer → 
{
  filterWallets(input: {
    filters: {
      hasTwitter: true
      hasDisplayName: true
    }
    rankings: [{ attribute: ethosScore, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet {
        displayName
        ethosScore
        twitterUsername
      }
    }
  }
}

​
Sort by Ethos Credibility

ethosScore (0 to 2800) is a credibility score you can use as a ranking attribute to surface reputable traders first. Combine it with identity filters to focus on wallets with both a public identity and a strong reputation. Test this query in the Explorer → 
{
  filterWallets(input: {
    filters: { hasSocials: true }
    rankings: [{ attribute: ethosScore, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet {
        ethosScore
        ethosLevel
        displayName
      }
    }
  }
}

​
Sort and Filter by Average Hold Period

avgHoldPeriodSec estimates how long a trader tends to hold tokens, derived from their buy and sell rate over a window. It is available in four windows (1d, 1w, 30d, 1y) and can be used as either a ranking attribute or a filter input. Long-term conviction holders (longest hold period first): Test this query in the Explorer → 
{
  filterWallets(input: {
    filters: { volumeUsd30d: { gte: 50000 } }
    rankings: [{ attribute: avgHoldPeriodSec30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet { displayName }
    }
  }
}
Quick flippers (shortest hold period first), filtered to active traders: Test this query in the Explorer → 
{
  filterWallets(input: {
    filters: { volumeUsd30d: { gte: 50000 } }
    rankings: [{ attribute: avgHoldPeriodSec1d, direction: ASC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet { displayName }
    }
  }
}
Hold period as a filter (traders that hold positions for more than 24 hours, sorted by profit). 86400 seconds = 24 hours: Test this query in the Explorer → 
{
  filterWallets(input: {
    filters: { avgHoldPeriodSec30d: { gt: 86400 } }
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet { displayName }
    }
  }
}
Hold period is most useful displayed alongside other stats on a single trader’s profile. See the Trader Dashboard recipe for showing it on one wallet.

​
Find Token-Specific Traders

To find profitable traders of a specific token, use filterTokenWallets. Watch for wallets that appear across multiple token queries, which can indicate consistent performance. Test this query in the Explorer → 
{
  filterTokenWallets(input: {
    tokenIds: ["0xTOKEN_ADDRESS:NETWORK_ID"]
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      walletAddress
      tokenBalance
      tokenBalanceLive
      purchasedTokenBalance
    }
  }
}
filterTokenWallets accepts up to 50 token IDs per query. If you pass more than one token ID, you must also include at least one wallet address. Records only update on swaps, so wallets that received tokens via transfer (airdrops, direct sends) will not appear. Use holders if you need an accurate holder list updated on every transfer.tokenBalance reflects the wallet’s balance as of its last swap, while tokenBalanceLive is the most up-to-date balance — prefer tokenBalanceLive when you need a wallet’s current holding.
To narrow results to wallets that still hold the token, filter for a tokenBalance greater than 0. This surfaces current holders rather than everyone who has ever traded it, and can return more relevant records in a single request.

​
Filter by Wallet Labels

Codex surfaces two separate label systems. They come from different sources and may overlap on individual wallets, so treat them as distinct. The Labels & Scores filter panel on re.defined.fi showing both behavioral and identity label buttons, plus risk score and reputation sliders

​
Codex behavioral labels

These are assigned by Codex based on a wallet’s on-chain trading activity. Apply them through includeLabels (only wallets matching) or excludeLabels (wallets to remove) on filterWallets. The WalletLabel enum values:
  • INTERESTING — Wallet is interesting based on a number of factors
  • MEDIUM_WEALTHY — Wallet holds $5M+ in assets
  • MEGA_WEALTHY — Wallet holds $10M+ in assets
  • SMART_TRADER_TOKENS_OVER_TWO_DAYS_OLD — Over $7.5K profit in the last 90 days from tokens older than 2 days
  • SMART_TRADER_TOKENS_UNDER_TWO_DAYS_OLD — Over $5K profit in the last 90 days from tokens between 1 hour and 2 days old
  • SNIPER — Over $3K profit in the last 90 days from tokens launched within their first hour
  • WEALTHY — Wallet holds $1M+ in assets
See the WalletLabel enum reference for the complete list (including bot and scammer values used to filter low-quality wallets out of results). Test this query in the Explorer → 
{
  filterWallets(input: {
    filters: {
      includeLabels: [SMART_TRADER_TOKENS_OVER_TWO_DAYS_OLD]
    }
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      labels
      wallet { displayName }
    }
  }
}

​
Identity labels

Codex also surfaces a separate set of curated identity labels from third-party data. These describe what the wallet is (CEX, KOL, founder, whale) rather than how it trades. They appear on the wallet.identityLabels array, and the full current vocabulary is returned by the walletLabelTypes query. See the reference page for the complete list with display names and descriptions.
Three labels appear conceptually in both systems: SNIPER, BOT, and SCAMMER. They are curated separately (Codex on-chain analysis vs. third-party sources) and may flag overlapping but not identical sets of wallets. A wallet may carry the behavioral SNIPER label without the identity SNIPER label, or vice versa.
Ready to dig into a single wallet? Continue to the Trader Dashboard recipe.