PolyLab Docs | Holders and Wallet PnL Source

Current Implementation

This page is intentionally explicit and implementation-first. If the product or upstream APIs change, the current behavior described here can change with them.

Upstream endpoints

PolyLab uses two additional Polymarket services for holder enrichment:

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

Holders endpoint behavior

The holders client calls /holders with:

market=<condition_id>
limit=<request_limit>

The implementation requests more than one outcome-specific sample so it can flatten both sides, but then applies a local cap.

Effective cap: top 20 holders per outcome

The current client reduces the requested holder limit to:

per_outcome_limit = min(limit, 20)

It then:

normalizes each holder row to use proxyWallet as address
normalizes amount into positionSize
sorts rows by position size
keeps only the top 20 rows for each outcome
re-sorts the flattened result

This means the smart-money layer is based on a sampled top-holder view, not on complete holder coverage.

Wallet PnL endpoint behavior

The PnL client calls /user-pnl with:

user_address=<wallet>

If the response is a list, PolyLab reads the last point and uses p as the stored total_pnl.

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

Holders and Wallet PnL Source