> ## 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.

# detailedWalletStats

> Returns detailed stats for a wallet. Reference for the detailedWalletStats query in the Codex API: arguments, response fields, and usage.

## GraphQL

```
type Query {
  # Requires a Growth or Enterprise plan.
  detailedWalletStats(
    input: DetailedWalletStatsInput!
  ): DetailedWalletStats
}

type NetworkWalletStats {
  networkId: Int!
  nativeTokenBalance: String!
}

type WindowedDetailedCurrencyWalletStats {
  volumeUsd: String!
  volumeUsdAll: String!
  heldTokenAcquisitionCostUsd: String!
  soldTokenAcquisitionCostUsd: String!
  realizedProfitUsd: String!
  realizedProfitUsdExNative: String
  averageProfitUsdPerTrade: String!
  averageSwapAmountUsd: String!
  realizedProfitPercentage: Float!
  realizedProfitPercentageExNative: Float
}

type WindowedDetailedNonCurrencyWalletStats {
  swaps: Int!
  uniqueTokens: Int!
  wins: Int!
  losses: Int!
  avgHoldPeriodSec: Float
}

type WindowedWalletStats {
  walletAddress: String!
  networkId: Int
  start: Int!
  end: Int!
  lastTransactionAt: Int!
  statsUsd: WindowedDetailedCurrencyWalletStats!
  statsNonCurrency: WindowedDetailedNonCurrencyWalletStats!
}

type WindowedDetailedNonCurrencyWalletStatsYear {
  swaps: Int!
  wins: Int!
  losses: Int!
  avgHoldPeriodSec: Float
}

type WindowedWalletStatsYear {
  walletAddress: String!
  networkId: Int
  start: Int!
  end: Int!
  lastTransactionAt: Int!
  statsUsd: WindowedDetailedCurrencyWalletStats!
  statsNonCurrency: WindowedDetailedNonCurrencyWalletStatsYear!
}

type NetworkBreakdown {
  networkId: Int!
  nativeTokenBalance: String!
  statsDay1: WindowedWalletStats
  statsWeek1: WindowedWalletStats
  statsDay30: WindowedWalletStats
  statsYear: WindowedWalletStatsYear
}

enum WalletCategory {
  NORMIE
  TOKEN_CREATOR
  EXCHANGE
  DEFI_EXCHANGE
  PAIR
  PAIR_TOKEN_HOLDER
  POOL_AUTHORITY
  STAKING_VAULT
  NOTORIOUS
  BURN
  LOCKER
}

type WalletFunding {
  fundedByAddress: String!
  fundedByLabel: String
  fundedAt: Int!
  tokenAddress: String!
  networkId: Int!
  amount: String!
  transactionHash: String!
}

type WalletPolymarketProfile {
  proxyWallet: String!
  xUsername: String
  displayName: String
  pseudonym: String
  profileImageUrl: String
  verifiedBadge: Boolean
  displayUsernamePublic: Boolean
  fetchedAt: Int!
}

type Wallet {
  address: String!
  category: WalletCategory
  firstSeenTimestamp: Int
  firstFunding: WalletFunding
  identityLabels: [String!]
  avatarUrl: String
  displayName: String
  twitterId: String
  twitterUsername: String
  telegramId: String
  telegramUsername: String
  website: String
  discordId: String
  discordUsername: String
  githubId: String
  githubUsername: String
  farcasterId: String
  farcasterUsername: String
  description: String
  ethosScore: Int
  ethosLevel: String
  ethosVerified: Boolean
  tradeSourceIds: [String!]
  identitySource: String
  identityUpdatedAt: Int
  polymarket: WalletPolymarketProfile
  tokensCreatedCount: Int
  tokensMigratedCount: Int
}

type DetailedWalletStats {
  walletAddress: String!
  lastTransactionAt: Int!
  networkBreakdown: [NetworkBreakdown!]
  labels: [String!]!
  scammerScore: Int
  botScore: Int
  statsDay1: WindowedWalletStats
  statsWeek1: WindowedWalletStats
  statsDay30: WindowedWalletStats
  statsYear: WindowedWalletStatsYear
  wallet: Wallet!
}

input DetailedWalletStatsInput {
  walletAddress: String!
  networkId: Int
  timestamp: Int
  includeNetworkBreakdown: Boolean
}
```

### Example

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

```graphql theme={null}
{
  detailedWalletStats(
    input: { walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }
  ) {
    walletAddress
    lastTransactionAt
    labels
    scammerScore
    botScore
    statsDay30 {
      statsUsd {
        volumeUsd
        realizedProfitUsd
        realizedProfitPercentage
        averageProfitUsdPerTrade
      }
      statsNonCurrency {
        swaps
        uniqueTokens
        wins
        losses
      }
    }
    networkBreakdown {
      networkId
      nativeTokenBalance
    }
    wallet {
      address
      firstFunding {
        fundedByAddress
        fundedAt
      }
    }
  }
}
```

### Usage Guidelines

* Query using `input: { walletAddress }` with a wallet address from any supported network
* Stats are available in multiple time windows: `statsDay1`, `statsWeek1`, `statsDay30`, `statsYear1`
* `statsUsd` contains USD-denominated metrics (volume, profit, averages)
* `statsNonCurrency` contains count metrics (swaps, unique tokens, wins/losses)
* Wins and losses only count a closed position when its realized profit or loss is greater than $1 USD. The threshold applies to the profit or loss amount, not the trade size, so a wallet whose positions all have a sub-$1 profit or loss will return `wins: 0` and `losses: 0`
* `networkBreakdown` shows per-network stats and native token balances
* Use `wallet.firstFunding` to see where initial funds came from
* `wallet.tradeSourceIds` lists the apps this wallet trades through (e.g. `axiom`, `phantom`). Means "trades through", never "is owned by" — see [Filter by Trade Source](https://docs.codex.io/recipes/wallets/discover-traders.md#filter-by-trade-source)

### Troubleshooting Tips

> [accordion] What does realizedProfitPercentage represent?
>
> `realizedProfitPercentage` is the profit as a percentage of the cost basis for tokens sold during the time window. A value of 0.5 means 50% profit on tokens sold.

> [accordion] What's the difference between wins and losses?
>
> A "win" is a closed position the wallet sold for more than it paid, and a "loss" is one it sold for less. Only positions whose realized profit or loss is greater than $1 USD are counted. The threshold applies to the profit or loss amount, not the trade size, so a wallet whose positions all have a sub-$1 profit or loss will show 0 wins and 0 losses (and a `winRate` of 0).

> [accordion] What do the labels indicate?
>
> Labels categorize wallets by behavior patterns (e.g., "smart\_money", "bot", "sniper"). Use these to quickly identify wallet types without analyzing all stats.

> [accordion] Why might networkBreakdown be empty?
>
> `networkBreakdown` only includes networks where the wallet has had trading activity on tracked DEXs. A wallet with only transfers or holdings won't appear in the breakdown.

> [accordion] What is firstFunding used for?
>
> `firstFunding` shows the first wallet that funded this address and when. This helps trace wallet origins and identify potential wallet clusters or funding patterns. `firstFunding` is available for wallets Codex has indexed (wallets with trading activity), mostly from mid-October 2025 onward. Older wallets often return null.

### Related Recipes

* [Wallets](https://docs.codex.io/recipes/wallets/discover-traders.md): Analyze wallet performance, discover top traders, and build portfolio views


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