Skip to main content
Codex provides wallet-level profit and loss data across several endpoints, including filterWallets, filterTokenWallets, getDetailedWalletStats, and walletChart. This page covers how those PnL numbers are calculated so you can interpret them correctly and layer on additional adjustments where needed.

​
Cost basis methodology

Codex calculates realized PnL using weighted average cost basis. Each buy adds to a cumulative acquisition cost, and each sell reduces that cost proportionally based on the share of holdings sold. The formula for realizedPnl: 
sellAmountUsd - (acquisitionCostUsd × tokensSold / tokensHeld)
Which simplifies to: 
sellAmountUsd - (averageCostPerToken × tokensSold)

​
Worked example

A wallet trades a token called PENGU:
ActionRunning acquisition costTokens heldRealized PnL
Buy 10 PENGU for $10$1010$0
Sell 4 PENGU for $8$66+$4
Buy 10 PENGU for $20$2616+$4 (unchanged)
Sell 16 PENGU for $32$00+$10
After the second buy, the 16 tokens held carry a blended cost basis of about $1.63 per token ($26 acquisition cost spread across 16 tokens). Selling all 16 for $32 produces $6 of additional realized PnL, bringing the running total to $10.

​
Transferred and received tokens

Codex only calculates PnL for tokens it can attribute a cost basis to. If a wallet acquires tokens through a swap, that swap establishes the acquisition cost used in the weighted average cost basis calculation. If a wallet receives tokens through a transfer (with no corresponding buy), Codex has no cost basis for those tokens and excludes them from PnL. Concretely, when a wallet later sells tokens it received via transfer:
  • The sale is not counted in realizedPnl or other PnL figures, because the profit or loss can’t be known without a cost basis.
  • The sale is still tracked in all-suffixed stats such as volumeUsdAll1w, swapsAll1w, and amountSoldUsdAll1w. Any field with all in its name reflects total activity, including sells of transferred tokens.
We deliberately avoid assuming a zero cost basis for transferred tokens. Doing so would treat every such sale as pure profit, which skews PnL for transfer-recipient wallets and makes the data less accurate overall.

​
Fee handling

Wallet PnL and volume figures handle fees in two different ways depending on the fee type.

​
Pool and swap fees

Pool fees are already reflected in realizedProfitUsd and volumeUsd. Codex reads swap values post-execution, so the amounts and prices recorded are net of what the pool took. No additional adjustment is needed on your end.

​
Gas fees

Gas fees (base fees, priority fees, L1 data fees, and builder tips) are tracked separately from wallet PnL. Gas is paid outside the swap itself, so wallet aggregation does not fold it into realizedProfitUsd or volumeUsd. If you want PnL net of gas, subtract gas fees yourself using the Global Fees Paid (GFP) fields. GFP exposes per-event and per-window fee components across most endpoints that return swap or bar data.

​
Data freshness

Wallet stats are indexed and updated on a rolling basis. To keep frequently viewed wallets fresh, querying filterWallets or filterTokenWallets with one or more specific wallet addresses triggers a background refresh of the 500 most recently traded tokens for each wallet. Refreshes are capped at once every 6 hours per wallet. The triggering request returns the current indexed data immediately. Refreshed values become available shortly after, so a follow-up query will reflect the updated stats.