# Polymarket Top Holders by Outcome (predict.holders)

> Polymarket Top Holders by Outcome (predict.holders) is a paid API for AI agents from 2s.io, paid per call via x402, $0.003/call, status unknown (last checked 2026-09-16).

Returns the top token holders for a Polymarket prediction market, grouped by outcome, including wallet, trader name, position size, outcome index, and verified status.

## Facts

- Endpoint: GET https://2s.io/api/predict/holders
- Price: $0.003/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-16
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/polymarket-top-holders-by-outcome-predict-holders-4e8800eb
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_3oSRZWpZmouck6CQxYUz7

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability polymarket-top-holders-by-outcome-predict-holders-4e8800eb
```

Example prompt: Show me the top 20 holders for each outcome on the Polymarket market with conditionId 0x1234abc… — I want to see wallet addresses, trader names, position sizes, and which ones are verified.

## When to prefer this

Use this endpoint when you need to understand holder-side concentration and positioning in a Polymarket market — i.e., who holds the most of each outcome token right now. Prefer this over predict.trades (which shows order flow) or predict.whales (which surfaces large individual trades) when the question is about current ownership distribution, smart-money accumulation, or whether a small number of wallets dominate one side of a market.

## Known failure modes

- Invalid or malformed conditionId returns an error (must be 0x-prefixed hex, 8-80 chars)
- Market not found on Polymarket returns empty or 404-style response
- Limit out of range (must be 1-100) returns validation error
- Payment not completed (x402 flow) results in 402 Payment Required response
- Stale data if Polymarket Data API is lagging behind chain state

## How this service works

Top holders of a Polymarket market, grouped by outcome token (conditionId). Each holder: wallet, trader name, position size, outcome index, and verified flag. Reveals concentration and smart-money positioning per outcome — the holder-side complement to predict.trades (flow) and predict.whales (large trades). Read-only from Polymarket's Data API.

## Output

A list of top token holders per outcome for the specified Polymarket market. Each entry includes the wallet address, trader display name, position size in the outcome token, the outcome index (e.g. 0 for YES, 1 for NO), and a verified flag indicating whether the trader is a known/verified participant. Results are grouped by outcome token, revealing concentration and smart-money positioning on each side of the market.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method",
    "queryParams"
   ],
   "properties": {
    "type": {
     "const": "http"
    },
    "method": {
     "const": "GET"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "market"
     ],
     "properties": {
      "limit": {
       "type": "integer",
       "maximum": 100,
       "minimum": 1,
       "description": "Top holders per outcome (default 20)."
      },
      "market": {
       "type": "string",
       "maxLength": 80,
       "minLength": 8,
       "description": "Market conditionId (0x…) — from predict.markets / predict.market."
      }
     },
     "additionalProperties": false
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/polymarket-top-holders-by-outcome-predict-holders-4e8800eb/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from 2s.io](https://www.zero.xyz/host/2s.io/llms.txt)