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

# Discover Traders

> Find high-performing wallets with the Codex API: filter and rank traders by performance, then narrow results by identity, socials, and labels.

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 [Defined.fi](https://www.defined.fi/tokens):

![A table of trader wallets on re.defined.fi showing PnL, volume, average hold period, win rate, and reputation columns](https://mintcdn.com/codex-dfdf2708/R4WMMuibQUOmJVip/images/wallets/discover_traders_redefined.png?fit=max\&auto=format\&n=R4WMMuibQUOmJVip\&q=85\&s=597c90ff57563b592fed69a08a7b0e0e)

> [!NOTE]
>
> 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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  filterWallets(input: {
    filters: { realizedProfitUsd30d: { gte: 10000 } }
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet {
        displayName
        ethosScore
        twitterUsername
      }
    }
  }
}
```

> [!NOTE]
>
> 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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  filterWallets(input: {
    filters: { avgHoldPeriodSec30d: { gt: 86400 } }
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      wallet { displayName }
    }
  }
}
```

> [!TIP]
>
> Hold period is most useful displayed alongside other stats on a single trader's
> profile. See the [Trader Dashboard](https://docs.codex.io/recipes/wallets/trader-dashboard.md) 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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  filterTokenWallets(input: {
    tokenIds: ["0xTOKEN_ADDRESS:NETWORK_ID"]
    rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
    limit: 10
  }) {
    count
    results {
      address
      tokenBalance
      tokenBalanceLive
      purchasedTokenBalance
    }
  }
}
```

> [!NOTE]
>
> `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`](https://docs.codex.io/api-reference/queries/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.

> [!TIP]
>
> 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](https://mintcdn.com/codex-dfdf2708/R4WMMuibQUOmJVip/images/wallets/wallet_label_score_filters.png?fit=max\&auto=format\&n=R4WMMuibQUOmJVip\&q=85\&s=7497fd9ea34855ea16587e82c160611f)

### 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](https://docs.codex.io/api-reference/enums/walletlabel.md) for the complete
list (including bot and scammer values used to filter low-quality wallets out of
results).

[Test this query in the Explorer →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  filterWallets(input: {
    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`](https://docs.codex.io/api-reference/queries/walletlabeltypes)
query. See the reference page for the complete list with display names and
descriptions.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> Identity labels are set only where a wallet has been attributed, so many exchange
> wallets return null. Use `wallet.category` (`EXCHANGE`) and `displayName` to identify
> exchanges.

### 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](https://docs.codex.io/api-reference/enums/walletcategory.md) 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 →](https://docs.codex.io/explore.md)

```graphql theme={null} theme={null}
{
  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`:

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

> [!WARNING]
>
> 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."

> [!NOTE]
>
> 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](https://docs.codex.io/recipes/events.md#trade-source) recipe. Wallets with no attributed trades return
> `null`.
>
> Trade source reads back from [`filterWallets`](https://docs.codex.io/api-reference/queries/filterwallets),
> [`filterTokenWallets`](https://docs.codex.io/api-reference/queries/filtertokenwallets), and
> [`detailedWalletStats`](https://docs.codex.io/api-reference/queries/detailedwalletstats).

## Related Endpoints

* [filterWallets](https://docs.codex.io/api-reference/queries/filterwallets.md)
* [filterTokenWallets](https://docs.codex.io/api-reference/queries/filtertokenwallets.md)
* [walletLabelTypes](https://docs.codex.io/api-reference/queries/walletlabeltypes.md)
* [holders](https://docs.codex.io/api-reference/queries/holders.md)
* [WalletLabel enum reference](https://docs.codex.io/api-reference/enums/walletlabel.md)
* [WalletCategory enum reference](https://docs.codex.io/api-reference/enums/walletcategory.md)

Ready to dig into a single wallet? Continue to the
[Trader Dashboard](https://docs.codex.io/recipes/wallets/trader-dashboard.md) recipe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.