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.

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.

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