Discover Traders

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:

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):

Filter	What it checks
`hasTwitter`	Wallet has a linked Twitter/X account
`hasDiscord`	Wallet has a linked Discord account
`hasTelegram`	Wallet has a linked Telegram account
`hasFarcaster`	Wallet has a linked Farcaster account
`hasGithub`	Wallet has a linked GitHub account
`hasDisplayName`	Wallet has a display name set
`hasSocials`	Wallet 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, using average-cost accounting: sells realize the age of the sold cost basis, so unsold holdings do not affect the result. It is a lower bound, capped at the window length, and returns null when under $1 of cost basis was sold in the 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.

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.

Wallet category

Distinct from both label systems, wallet.category returns a single structural classification of what kind of address a wallet is — for example NORMIE, TOKEN_CREATOR, EXCHANGE, PAIR, or POOL_AUTHORITY. Where labels describe how a wallet trades or who it is, category answers “what kind of address is this.” See the WalletCategory enum reference for the full set of values.

Filter by Trade Source

Separate from labels and category, Codex tracks which apps a wallet trades through — trading terminals, wallets, and interfaces such as Axiom, Phantom, or Fomo — as distinct from the exchanges its trades settle on. Use this to build “traders on Axiom” style leaderboards, or to exclude a competitor’s user base from results. Filter with includeTradeSourceIds (only wallets that traded through any of these apps) or excludeTradeSourceIds on filterWallets, and read the matching apps back from the tradeSourceIds array. Test this query in the Explorer →

{
  filterWallets(input: {
    includeTradeSourceIds: ["axiom"]
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      tradeSourceIds
    }
  }
}

The same two filters work on filterTokenWallets, where the wallet’s apps are returned as walletTradeSourceIds:

{
  filterTokenWallets(input: {
    tokenIds: ["0xTOKEN_ADDRESS:NETWORK_ID"]
    includeTradeSourceIds: ["axiom"]
    limit: 10
  }) {
    count
    results {
      address
      walletTradeSourceIds
    }
  }
}

On filterTokenWallets, trade source is a property of the wallet overall, not of its activity on the token you queried. A wallet that trades most tokens through one app and this one through another lists both, and includeTradeSourceIds matches the wallet’s apps globally. This filter answers “wallets that use Axiom, and that traded this token” — not “wallets that traded this token through Axiom.”

Trade source means “trades through”, never “is owned by” — a single routed trade is enough for an app to appear on a wallet. Treat it as a signal about where a wallet’s flow goes, not as an ownership or affiliation claim.These fields are arrays of registry entity ids (e.g. axiom, fomo, phantom, defined) with no display names attached. If you need a human-readable name, read tradeSource { id displayName } off an event — see the Events recipe. Wallets with no attributed trades return null.Trade source reads back from filterWallets, filterTokenWallets, and detailedWalletStats.

Ready to dig into a single wallet? Continue to the Trader Dashboard recipe.

First steps

Codex for Agents

Concepts

Recipes

Migration Guides

Resources

Discover Traders

Filter by Performance

Filter by Identity and Socials

Sort by Ethos Credibility

Sort and Filter by Average Hold Period

Find Token-Specific Traders

Filter by Wallet Labels

Codex behavioral labels

Identity labels

Wallet category

Filter by Trade Source

​Filter by Performance

​Filter by Identity and Socials

​Sort by Ethos Credibility

​Sort and Filter by Average Hold Period

​Find Token-Specific Traders

​Filter by Wallet Labels

​Codex behavioral labels

​Identity labels

​Wallet category

​Filter by Trade Source

​Related Endpoints

Filter by Performance

Filter by Identity and Socials

Sort by Ethos Credibility

Sort and Filter by Average Hold Period

Find Token-Specific Traders

Filter by Wallet Labels

Codex behavioral labels

Identity labels

Wallet category

Filter by Trade Source

Related Endpoints