Skip to main content
An agent sees three profit-and-loss figures on this API. They answer different questions. Quoting the wrong one is the most common way to be confidently wrong about a trader.

​
The one to quote

polymarket.pnl is THE P/L

On the trader card, the polymarket block carries Polymarket’s own model: realized plus unrealized, over the trader’s full account history including the pre-V2 era. This is the number the user sees on polymarket.com. Quote it as the trader’s profit.
If Polymarket’s upstream is unreachable the block degrades to {"status": "pm_offline"} and the rest of the card still serves. Only then does the card carry the archive’s own career_pnl_usd / pnl_marked_usd as a labeled fallback. On a healthy response those fields are absent by design — there is one headline P/L, not two competing ones.

​
The other two voices

Per-market pnl_usd (and the card’s career_pnl_usd twin, served only when Polymarket is offline) is realized cash flow only — reconstructed and chain-audited over the V2-contract era (roughly April 2026 onward).Use it for per-market analysis and anything that must trace to the chain.An active trader with a large open book reads more negative here than the headline, because money deployed counts as spent until the market resolves. That is not a discrepancy; it is a different question.
Realized plus open holdings valued at the last on-chain trade. PolyTape’s own estimate of where a standing position sits. Useful, honest, not the headline.

​
Labeling a result

Resolved market

pnl_usd is a result. “Won X"/"lostX" / "lost X” is fair.

Open market

pnl_usd is cash flow, not a result. Quote pnl_marked_usd, say “marked at X"—never"wonX" — never "won X”.

​
The caveats that keep you honest

A market’s pnl_usd includes mint, split, and redemption legs that never appear as buy or sell fills. A −42.3kmarketcanshowbuy42.3k market can show buy 2k / sell $41.7k and simply not reconcile from the fills alone.Quote pnl_usd; do not reconstruct P/L from visible fills. And roi is meaningless for split-sellers — pnl ÷ buy-notional explodes when the “entry” was a mint rather than a buy. Do not quote it on sell-dominated flow.
The card’s counts, winrate, and volume cover the V2 era until the v1 backfill lands. The headline P/L covers the full account.State that once, then quote the headline with confidence.
A small class — dozens of accounts — run NegRisk-conversion arbitrage, where a conversion moves balances without a trade. Their per-token accounting is distorted.If a card shows large volume with near-zero or nonsensical realized P/L, suspect a conversion-arb bot rather than an edge.
Not one of these three figures is a live account balance. Do not present any of them as one.

​
avg_entry_price — two different stats, one name

This trips up more agents than anything else on the surface. The field appears in two places and means two different things.
card.avg_entry_price is the average cost per token across all buys — dollars spent ÷ tokens bought, both outcome sides, in the token’s own frame.That makes it the trader’s break-even winrate. Compare it against winrate to price the edge:
  • 63% winrate at a 0.47 average entry → real selection skill.
  • 95% winrate at a 0.95 average entry → none.
It is token-weighted, so cheap-token volume drags it well below the price the trader typically clicks. A trader who enters at 90¢ or better nearly every time can still read 0.627 here, and that is correct arithmetic, not a bug.Do not describe it as “the price they usually pay.”
avg_entry_price, avg_win_usd, and avg_loss_usd are absent or null until the career-stats rollup has populated a trader. Treat missing as “unavailable” — never as zero.avg_win_usd / avg_loss_usd are per-resolved-market averages, not medians, and one blowup skews them. Read them beside get_top_markets, not alone.

​
A verdict that traces

Every claim should trace to a number a tool returned. If the record looks incomplete, say so rather than guessing. What that reads like:
Chart labeling follows the same doctrine — see Plotting.