> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polytape.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading the numbers

> Three P/L voices live on this API. Which one to quote, how to label it, and the caveats that keep a verdict honest.

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

<Card title="polymarket.pnl is THE P/L" icon="star">
  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.
</Card>

```json theme={null}
"polymarket": {
  "pnl": 61240.0,
  "pnl_realized": 55010.0,
  "pnl_unrealized": 6230.0,
  "portfolio_value": 12400.0,
  "peak": 71000.0,
  "low": -3400.0,
  "max_drawdown": 42000.0,
  "as_of": 1783200000
}
```

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

<AccordionGroup>
  <Accordion title="pnl_usd — realized cash flow (the audit voice)" icon="receipt">
    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.
  </Accordion>

  <Accordion title="pnl_marked_usd — the chain-audited approximation" icon="ruler">
    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**.
  </Accordion>
</AccordionGroup>

## Labeling a result

<Columns cols={2}>
  <Card title="Resolved market" icon="flag-checkered">
    `pnl_usd` is a **result**. "Won $X" / "lost $X" is fair.
  </Card>

  <Card title="Open market" icon="hourglass">
    `pnl_usd` is **cash flow**, not a result. Quote `pnl_marked_usd`, say
    "marked at $X" — never "won $X".
  </Card>
</Columns>

## The caveats that keep you honest

<AccordionGroup>
  <Accordion title="Split and merge legs are invisible to fills" icon="scissors">
    A market's `pnl_usd` includes mint, split, and redemption legs that never
    appear as buy or sell fills. A −$42.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.
  </Accordion>

  <Accordion title="The V2 window" icon="calendar">
    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.
  </Accordion>

  <Accordion title="Conversion-arb bots read oddly" icon="robot">
    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.
  </Accordion>

  <Accordion title="None of this is an account balance" icon="wallet">
    Not one of these three figures is a live account balance. Do not present any
    of them as one.
  </Accordion>
</AccordionGroup>

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

<Tabs>
  <Tab title="On the trader card">
    `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."**
  </Tab>

  <Tab title="On a market summary">
    `summary.avg_entry_price` is the **UP-space VWAP** of that trader's buys
    **within one market**. A different frame and a different question.

    The per-token `sides[].avg_entry` inside the same response is in each token's
    *own* frame — what they actually paid for that token.
  </Tab>
</Tabs>

<Note>
  `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.
</Note>

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

```text theme={null}
ACROSS 5,154 MARKETS: $10.2M volume, +$1.1M (Polymarket) — a grinder in the black.
ENTRY:  buys around even odds (VWAP ~0.54), not chasing extremes.
SIZE:   steady ~$19 clips with occasional conviction lumps up to ~$48k.
TIMING: near-zero early, ~57% of capital in the last tenth — a late piler.
EDGE:   size + timing pays on the winners (this one +$234k at 65% ROI).
LEAK:   winrate 41% — the late-pile conviction loses more markets than it wins.
VERDICT: fade the aggregate, but the late conviction lumps are worth watching.
```

Chart labeling follows the same doctrine — see [Plotting](/guides/plotting).