Skip to main content

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.

In this recipe we’ll show you how to filter for high-performing wallets, track performance metrics, and build comprehensive wallet analytics across multiple networks.

This data powers the wallet discovery, tracking, and portfolio features on defined.fi:

Wallets

​
Discover High-Performing Wallets

Start by implementing a query to help you identify wallets with strong trading performance using a variety of available filters.

Note: Wallet timeframes, such as PnL intervals, are rolling periods. eg: 1D is the last 24 hours, 7D is the last 7 days, etc. They do not start on a specific date or time of day.

​
Find Token-Specific Traders

The next method to discover profitable wallets is to query for token-specific performance. Keep an eye out for wallets that appear in multiple query results, as this could be an indicator of strong and consistent performance.

filterTokenWallets can only accept one tokenID at a time, however, if you instead filter for a tokenBalance that is greater than 0, you can potentially get more records in one request. Note that our records do not track token transfers and are only updated on swaps, so accuracy may not be 100%.

​
Get Detailed Wallet Analytics

Once you’ve identified a list of high-performing wallets, or simply wallets of interest, use additional queries to obtain comprehensive performance and trading metrics.

If wallet stats are empty or missing data, you can try manually backfilling a wallet by using backfillWalletAggregates mutation found here.

​
Visualize Wallet Activity

An optional step is to query for time-series data that you can use to render performance charts that showcase P&L progression, trading volume, portfolio value over time, and more. Displaying a wallet’s trading activity and performance through a graphic or chart can be a great way to quickly identify patterns and overall trading success (or failure).

Example of a PnL graph & 120-Day Wallet Chart on Defined.fi:
Wallet Chart
When determining “Win Rate”, wallets need to make a profit or loss greater than $1 USD to be counted.

​
Calculate Wallet PnL

PnL (Profit and Loss) is a core metric for wallet analysis. There are several ways to calculate it depending on the level of detail you need.

​
Overall Realized PnL

The detailedWalletStats endpoint provides aggregate realized PnL across configurable timeframes. The statsUsd object within each timeframe contains realizedProfitUsd (total USD profit/loss from closed positions) and realizedProfitPercentage.
# Already shown in the detailedWalletStats example above — key PnL fields:
networkBreakdown {
  statsDay30 {
    statsUsd {
      realizedProfitUsd          # Total realized P&L in USD
      realizedProfitPercentage   # Realized P&L as a percentage
      soldTokenAcquisitionCostUsd # Cost basis of sold tokens
      heldTokenAcquisitionCostUsd # Cost basis of held tokens
    }
    statsNonCurrency {
      wins                       # Number of winning trades
      losses                     # Number of losing trades
    }
  }
}
Available timeframes include statsDay1, statsDay7, statsDay30, and more — each providing the same PnL fields for that rolling window.

​
Per-Token PnL

To see how a wallet performed on a specific token, use filterTokenWallets. This gives you per-token realized PnL across timeframes:

​
Unrealized PnL

To estimate unrealized PnL (profit/loss on tokens still held), compare the current value of held tokens against their acquisition cost:
Unrealized PnL = Current Balance Value - Acquisition Cost
You can calculate this using two fields from filterTokenWallets:
  • tokenAcquisitionCostUsd — what the wallet paid for the tokens it still holds
  • Current value — multiply tokenBalance by the token’s current price (from getTokenPrices)
Alternatively, the heldTokenAcquisitionCostUsd field from detailedWalletStats gives you the total cost basis across all held tokens for a wallet.

​
PnL Over Time

For charting PnL progression, use the walletChart endpoint (shown in Visualize Wallet Activity above). The realizedProfitUsd field in each data point gives you time-series PnL data at your chosen resolution.

​
Check Current Holdings

Your wallet analysis is not complete without a thorough Portfolio breakdown of all held assets. The next query will find what tokens a wallet currently holds across multiple networks, along with their current USD value.

​
Bring Your Results Together

By combining results from multiple wallet endpoints as outlined above, you now have all the pieces necessary to build a comprehensive wallet analysis dashboard and individual wallet portfolios to suit your project’s needs:
  • Discovery: Use filterWallets to find high-performing wallets\
  • Token Analysis: Use filterTokenWallets for token-specific performance\
  • Deep Dive: Use detailedWalletStats and EventsForMaker for a comprehensive wallet analysis\
  • Visualization: Use walletChart for time-series performance data\
  • Token Holdings: Use balances to see current holdings and USD values

​
Assign Wallet Labels (Optional)

Some wallets will be assigned one or more labels depending on their trading activity. You can choose to display these labels to your users. They include:
  • Wealthy (low): Wallet holds $1M+ in assets
  • Wealthy (Medium): Wallet holds $5M+ in assets
  • Wealthy (high): Wallet holds $10M+ in assets
  • Sniper: Profits $3k+ from tokens bought within 1 hour of launch
  • Interesting: Wallet is interesting (based on a number of factors).
  • Early Bird (Smart Trader): Profits $5k+ from tokens 1 hour to 2 days old
  • Second Wave (Smart Trader): Profits $7.5k+from established tokens (2+ days old)
  • Scammer or Bot: Wallets that have suspicious trading behavior. Stats not tracked.
See all possible wallet label inputs here.

Check out the related wallet endpoints in their respective API reference pages: