# Polymarket Market-Flow Screener

> Polymarket Market-Flow Screener is a paid API for AI agents from api.polym.uk, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-14).

Returns a ranked list of Polymarket prediction markets screened by taker-flow structure, factual concentration, trader breadth, and liquidity compatibility for a recent observation window.

## Facts

- Endpoint: GET https://api.polym.uk/screener
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/polymarket-market-flow-screener-4d6a7812
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_UXVbzxPxCTZ9vH03boRUt

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-market-flow-screener-4d6a7812
```

Example prompt: Show me the top 30 Polymarket markets screened by taker-flow structure — I want to see which ones are broad vs concentrated, their apparent volume, effective trader counts, and any resolution subjectivity flags.

## When to prefer this

Use this endpoint when you need a quick ranked snapshot of Polymarket market health, flow concentration, and trader breadth across multiple markets simultaneously. Prefer it over manual Polymarket browsing when you want structured, machine-readable flow-quality signals (bucket classification, effective trader count, top-trader share) for downstream filtering or alerting. It is especially useful for agents that need to identify which prediction markets are safe to trade or analyze based on liquidity and participation structure.

## Known failure modes

- top parameter out of range (1–40) returns validation error
- payment not provided or insufficient results in 402 Payment Required
- upstream Polymarket data unavailable causes partial or stale results indicated in caveats
- network timeout if Polymarket API is slow
- market data artifact may be cached; asOf timestamp indicates freshness

## How this service works

Ranked Polymarket market-flow screener with factual concentration and liquidity-compatibility fields for the observed window. BEFORE YOU PAY: free substitute https://dash.polym.uk/markets.json. THIS ADDS: Little today, and we would rather you knew: the free snapshot has every field this route returns, for the whole decomposed set instead of the 40 rows this caps at, and it also carries the dominant-flow wallet that this route omits. Buy only if a small fixed-shape response beats completeness.

## Output

Returns a JSON object with: timestamp and observation window hours, a ranked array of up to N markets each containing conditionId, title, flow bucket (broad/moderate/concentrated/structurally-thin/unranked), apparent volume in USD, top trader share, effective trader count, apparent-vs-book flag, market closed status, and a resolution object with heuristic category, dispute rate, flip rate, and subjectivity flag. Also includes a decomposed summary and a caveats array explaining data limitations.

## 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"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "top": {
       "type": "integer",
       "default": 20,
       "maximum": 40,
       "minimum": 1
      }
     },
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "asOf",
      "windowHours",
      "observedMarkets",
      "decomposed",
      "markets",
      "caveats"
     ],
     "properties": {
      "asOf": {
       "type": "string",
       "format": "date-time"
      },
      "caveats": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "markets": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "conditionId",
         "title",
         "bucket",
         "apparentVolumeUsd",
         "topTraderShare",
         "effectiveTraders",
         "apparentVsBookFlag",
         "marketClosed",
         "resolution"
        ],
        "properties": {
         "title": {
          "type": "string",
          "description": "Observed Polymarket market title."
         },
         "bucket": {
          "enum": [
           "unranked",
           "structurally-thin",
           "concentrated",
           "moderate",
           "broad"
          ],
          "type": "string",
          "description": "Descriptive taker-flow structure bucket, not a fraud verdict."
         },
         "resolution": {
          "type": [
           "object",
           "null"
          ],
          "required": [
           "category",
           "categoryDisputeRatePct",
           "categoryFlipRatePct",
           "titleLooksUncheckable"
          ],
          "properties": {
           "category": {
            "type": "string",
            "description": "Heuristic category inferred from the market title."
           },
           "categoryFlipRatePct": {
            "type": [
             "number",
             "null"
     
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/polymarket-market-flow-screener-4d6a7812/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.polym.uk](https://www.zero.xyz/host/api.polym.uk/llms.txt)