Holders and Wallet PnL Source

Upstream endpoints

PolyLab uses two additional Polymarket services for holder enrichment:

https://data-api.polymarket.com/v2/holders
https://data-api.polymarket.com/v2/user-pnl

Holders endpoint behavior

PolyLab requests one condition at a time from /v2/holders. The condition parameter identifies the market and limit sets the number of holders per outcome token. With include_pnl=true, the source reports each wallet’s gross position on each side, including wallets that own both outcomes. PolyLab uses the separate lifetime wallet P/L series to classify holders.

Effective cap: top 20 holders per outcome

The scanner takes the first page of token groups in data and keeps the largest 20 holders on each side, ranked by amount. The watch monitor can request a deeper sample. Each row identifies its side with outcome_index and its wallet with proxy_wallet. A successful empty page records an empty observation. A failed request leaves the previous sample in place.

Collection coverage and missing data

The hourly holder job covers active, open markets with at least $10,000 volume and $10,000 liquidity. A past end_date does not mean a market has closed: for sports it can be kickoff. After each successful market scrape, a bounded catch-up pass collects up to 200 newly eligible markets that have no stored holder rows.

For users with holder-analysis access, opening an unsampled market also makes one bounded upstream attempt, including markets below the routine volume/liquidity thresholds. Attempts have a five-minute per-market cooldown and concurrency/rate limits. This reuses cached wallet P/L; unknown P/L stays unknown. The holder list response format and access requirements are unchanged. Upstream failure or recovery capacity limits return HTTP 503 with Retry-After: 60; a confirmed empty source response returns an empty list.

Fetch attempts record time, success/empty/failure status and stored count for operational diagnosis. Missing local rows do not prove that the market has no actual holders.

Wallet PnL endpoint behavior

The PnL client calls /v2/user-pnl with:

user=<wallet>
interval=1d, fidelity=1h

The v2 response wraps a series in data.points. Every point is cumulative through its timestamp; the one-day request bounds the series window, not the P/L horizon. PolyLab selects the newest timestamp and stores trade_pnl, the compatibility series documented as the old chart's p. It does not substitute realized-only or all-income economic P/L. See Polymarket's served API reference.

The wallet identity must match. Empty series, missing/null/non-finite values, future points and observations older than 48 hours remain unknown; they never become zero. The stored freshness timestamp is the upstream point's timestamp, not the HTTP download time. Failed reads retain the previous value and its previous age. Permanent 4xx responses, including the retired endpoint's 410, are not retried; transient failures and rate limits have bounded retries.

Alias capture

Aliases come from the holders payload field name when present. When aliases are missing, PolyLab keeps alias = null.

Retry behavior

The holders and wallet-PnL clients both retry on network errors and rate limits. The goal is operational resilience, not a guarantee of completeness.

What this means for interpretation

a missing wallet from the sample is not evidence of absence
a profitable sampled wallet may not be profitable because of this market
smart-money counts are only as complete as the sampled holder set and wallet-PnL coverage