{"openapi":"3.1.0","info":{"title":"Polymarket Intelligence API","version":"1.0.0","description":"Factual Polymarket market-flow intelligence and UMA resolution base-rate compatibility for machine consumers. Descriptive observed-window evidence, never a fraud allegation or market-specific prediction. Paid delivery uses the x402 protocol with exact USDC payments on Base or Base Sepolia. A static screener sample and aggregate coverage metadata are free for contract evaluation."},"servers":[{"url":"https://api.polym.uk"}],"paths":{"/market-authenticity/{conditionId}":{"get":{"operationId":"getMarketAuthenticity","summary":"Factual per-market Polymarket taker-flow concentration, price-band structure, book compatibility and resolution base-rate context; never a fraud verdict or prediction.","description":"Factual per-market Polymarket taker-flow concentration, price-band structure, book compatibility and resolution base-rate context; never a fraud verdict or prediction.","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"description":"Polymarket condition ID (exactly 32 bytes encoded as hex)."}],"x-payment-info":{"protocols":["x402"],"scheme":"x402","asset":"USDC","network":"base","payTo":"0x7b13107779CfDA1bEba3289d0Fbe27310436f3E3","price":{"mode":"fixed","currency":"USD","amount":"0.05"}},"responses":{"200":{"description":"Polymarket intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketAuthenticity"},"example":{"asOf":"2026-07-19T00:00:00.000Z","conditionId":"0x0000000000000000000000000000000000000000000000000000000000000000","found":false,"note":"The requested market is not among the decomposed top-volume markets for this window.","caveats":["Example only: a not-found response does not imply that the market is inactive or invalid."]}}}},"400":{"description":"Invalid path or query input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"Market or route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required Polymarket data unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/screener":{"get":{"operationId":"getPolymarketScreener","summary":"Ranked Polymarket market-flow screener with factual concentration and liquidity-compatibility fields for the observed window.","description":"Ranked Polymarket market-flow screener with factual concentration and liquidity-compatibility fields for the observed window.","parameters":[{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":20},"description":"Maximum number of ranked rows to return (integer from 1 through 40)."}],"x-payment-info":{"protocols":["x402"],"scheme":"x402","asset":"USDC","network":"base","payTo":"0x7b13107779CfDA1bEba3289d0Fbe27310436f3E3","price":{"mode":"fixed","currency":"USD","amount":"0.05"}},"responses":{"200":{"description":"Polymarket intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketScreener"},"example":{"asOf":"2026-07-01T00:00:00.000Z","windowHours":24,"observedMarkets":128,"decomposed":40,"markets":[{"conditionId":"0x1111111111111111111111111111111111111111111111111111111111111111","title":"Static contract sample — not a live Polymarket market","bucket":"moderate","apparentVolumeUsd":12345.67,"topTraderShare":0.42,"effectiveTraders":7,"apparentVsBookFlag":false,"marketClosed":false,"resolution":{"category":"Example","categoryDisputeRatePct":4.2,"categoryFlipRatePct":null,"titleLooksUncheckable":false}}],"caveats":["STATIC CONTRACT SAMPLE ONLY: this payload is not live market intelligence.","Paid screener responses describe the observed materialized window and retain their own caveats."]}}}},"400":{"description":"Invalid path or query input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"Market or route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required Polymarket data unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/resolution-risk":{"get":{"operationId":"getResolutionRisk","summary":"UMA resolution dispute and flip base rates by category and criterion clarity; descriptive historical compatibility, not a market-specific forecast.","description":"UMA resolution dispute and flip base rates by category and criterion clarity; descriptive historical compatibility, not a market-specific forecast.","x-payment-info":{"protocols":["x402"],"scheme":"x402","asset":"USDC","network":"base","payTo":"0x7b13107779CfDA1bEba3289d0Fbe27310436f3E3","price":{"mode":"fixed","currency":"USD","amount":"0.05"}},"responses":{"200":{"description":"Polymarket intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolutionRiskLandscape"},"example":{"asOf":"2026-07-19T00:00:00.000Z","flipAsOf":null,"dataDegraded":false,"elevatedRiskCategories":["Example"],"byCategory":[{"category":"Example","disputeRatePctHighVolume":4.2,"disputeRatePctChronological":null,"disputeInsufficientSample":false,"elevated":true,"lockupHoursPerMarket":null,"lockupHoursIfDisputed":null,"flipRatePct":null,"flipInsufficientSample":true}],"clarity":{"checkableTitle":{"marketsScanned":100,"disputeRatePct":1.2},"uncheckableTitle":{"marketsScanned":20,"disputeRatePct":4.2}},"flipOverall":null,"howToRead":"Historical category base rates describe resolution compatibility; they are not a forecast for an individual market.","caveats":["Example only: live responses retain artifact-specific caveats and timestamps."]}}}},"400":{"description":"Invalid path or query input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"Market or route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required Polymarket data unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/resolution-watchlist":{"get":{"operationId":"getResolutionWatchlist","summary":"Live Polymarket watchlist ranked by structural UMA resolution base-rate signals, with flip risk kept as a separate conditional axis.","description":"Live Polymarket watchlist ranked by structural UMA resolution base-rate signals, with flip risk kept as a separate conditional axis.","parameters":[{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":25},"description":"Maximum number of ranked rows to return (integer from 1 through 40)."}],"x-payment-info":{"protocols":["x402"],"scheme":"x402","asset":"USDC","network":"base","payTo":"0x7b13107779CfDA1bEba3289d0Fbe27310436f3E3","price":{"mode":"fixed","currency":"USD","amount":"0.05"}},"responses":{"200":{"description":"Polymarket intelligence response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolutionWatchlist"},"example":{"asOf":"2026-07-19T00:00:00.000Z","windowHours":24,"liveMarketsRanked":1,"tierCounts":{"watch":1},"flipReferencePct":14,"flipReferenceStatus":"measured","flipReferenceWithheldReason":null,"markets":[{"conditionId":"0x0000000000000000000000000000000000000000000000000000000000000000","title":"Static contract example — not a live Polymarket market","tier":"watch","disputeFlagCount":1,"flags":{"elevatedCategory":true,"titleLooksUncheckable":false,"flipProne":false},"category":"Example","titleLooksUncheckable":false,"categoryElevated":true,"categoryDisputeRatePctHighVolume":4.2,"flipRatePct":null,"apparentVolumeUsd":12345.67,"marketClosed":false}],"howToRead":"Tiers rank structural resolution signals among live, decomposed markets; they are not accusations or forecasts.","caveats":["Example only: live responses retain artifact-specific caveats and timestamps."]}}}},"400":{"description":"Invalid path or query input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"Market or route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Required Polymarket data unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/samples/screener":{"get":{"operationId":"getPolymarketScreenerSample","summary":"Static contract sample for the paid Polymarket screener response.","description":"Free, static and intentionally non-live response. Use it only to evaluate the paid screener JSON shape and field semantics.","responses":{"200":{"description":"Static contract sample; not current market intelligence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketScreener"},"example":{"asOf":"2026-07-01T00:00:00.000Z","windowHours":24,"observedMarkets":128,"decomposed":40,"markets":[{"conditionId":"0x1111111111111111111111111111111111111111111111111111111111111111","title":"Static contract sample — not a live Polymarket market","bucket":"moderate","apparentVolumeUsd":12345.67,"topTraderShare":0.42,"effectiveTraders":7,"apparentVsBookFlag":false,"marketClosed":false,"resolution":{"category":"Example","categoryDisputeRatePct":4.2,"categoryFlipRatePct":null,"titleLooksUncheckable":false}}],"caveats":["STATIC CONTRACT SAMPLE ONLY: this payload is not live market intelligence.","Paid screener responses describe the observed materialized window and retain their own caveats."]}}},"headers":{"Cache-Control":{"description":"HTTP cache policy for this free evaluation resource.","schema":{"type":"string"}},"X-Data-Sample":{"description":"Identifies this response as a static contract example.","schema":{"type":"string","enum":["static-contract-example"]}}}}}}},"/coverage":{"get":{"operationId":"getPolymarketCoverage","summary":"Free aggregate coverage, freshness and degradation metadata.","description":"Free metadata only. Counts describe observed and decomposed artifacts, not the entire Polymarket universe; no premium market rows are returned.","responses":{"200":{"description":"Aggregate coverage metadata from materialized Polymarket artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketCoverage"},"example":{"marketFlow":{"asOf":"2026-07-01T00:00:00.000Z","windowHours":24,"observedMarkets":128,"decomposedMarkets":40,"marketsWithResolutionRisk":32,"liveMarketsWithResolutionRisk":28},"resolution":{"asOf":"2026-07-01T00:00:00.000Z","categoriesCovered":7,"highVolumeScanDegraded":false,"chronologicalScanDegraded":false,"clarity":{"checkableTitlesScanned":100,"uncheckableTitlesScanned":100}},"flipReference":{"asOf":"2026-07-01T01:00:00.000Z","disputedResolved":80,"categoriesCovered":7}}}},"headers":{"Cache-Control":{"description":"HTTP cache policy for this free evaluation resource.","schema":{"type":"string"}}}},"503":{"description":"Required Polymarket coverage artifacts unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","additionalProperties":false,"required":["error","requestId"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}},"MarketAuthenticity":{"oneOf":[{"type":"object","additionalProperties":false,"required":["asOf","windowHours","conditionId","title","found","bucket","marketClosed","apparentVolumeUsd","trades","concentration","priceBand","structure","dominantFlow","resolutionRisk","caveats"],"properties":{"asOf":{"type":"string","format":"date-time"},"windowHours":{"type":"number","minimum":0},"conditionId":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$","description":"Polymarket condition ID."},"title":{"type":"string"},"found":{"type":"boolean","const":true},"bucket":{"type":"string","enum":["unranked","structurally-thin","concentrated","moderate","broad"],"description":"Descriptive taker-flow structure bucket, not a fraud verdict."},"marketClosed":{"type":["boolean","null"]},"apparentVolumeUsd":{"type":"number","minimum":0},"trades":{"type":"integer","minimum":0},"concentration":{"type":"object","additionalProperties":false,"required":["topTraderShare","hhi","effectiveTraders","distinctTraders"],"properties":{"topTraderShare":{"type":"number","minimum":0,"maximum":1},"hhi":{"type":"number","minimum":0,"maximum":1},"effectiveTraders":{"type":"integer","minimum":0},"distinctTraders":{"type":"integer","minimum":0}}},"priceBand":{"type":"object","additionalProperties":false,"required":["subCentShare","nearResolutionShare"],"properties":{"subCentShare":{"type":"number","minimum":0,"maximum":1},"nearResolutionShare":{"type":"number","minimum":0,"maximum":1}}},"structure":{"type":"object","additionalProperties":false,"required":["bookLiquidityUsd","spread","orderbookEnabled","rewardsSubsidized","apparentVsBookFlag"],"properties":{"bookLiquidityUsd":{"type":["number","null"],"minimum":0},"spread":{"type":["number","null"],"minimum":0},"orderbookEnabled":{"type":["boolean","null"]},"rewardsSubsidized":{"type":["boolean","null"]},"apparentVsBookFlag":{"type":["boolean","null"]}}},"dominantFlow":{"type":["object","null"],"additionalProperties":false,"required":["side","outcome","vwap","notionalUsd","walletMarkets","distinctCounterparties","betResolvedInFavor"],"properties":{"side":{"type":"string","enum":["BUY","SELL"]},"outcome":{"type":"string"},"vwap":{"type":"number","minimum":0,"maximum":1},"notionalUsd":{"type":"number","minimum":0},"walletMarkets":{"type":["integer","null"],"minimum":0},"distinctCounterparties":{"type":["integer","null"],"minimum":0},"betResolvedInFavor":{"type":["boolean","null"]}}},"resolutionRisk":{"type":["object","null"],"additionalProperties":false,"required":["category","categoryDisputeRatePct","categoryDisputeSample","categoryInsufficientSample","categoryElevated","titleLooksCheckable","categoryFlipRatePct","flipInsufficientSample"],"properties":{"category":{"type":"string"},"categoryDisputeRatePct":{"type":["number","null"],"minimum":0,"maximum":100},"categoryDisputeSample":{"type":"string"},"categoryInsufficientSample":{"type":"boolean"},"categoryElevated":{"type":"boolean"},"titleLooksCheckable":{"type":"boolean"},"categoryFlipRatePct":{"type":["number","null"],"minimum":0,"maximum":100},"flipInsufficientSample":{"type":"boolean"}}},"caveats":{"type":"array","items":{"type":"string"}}}},{"type":"object","additionalProperties":false,"required":["asOf","conditionId","found","note","caveats"],"properties":{"asOf":{"type":"string","format":"date-time"},"conditionId":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"found":{"type":"boolean","const":false},"note":{"type":"string"},"caveats":{"type":"array","items":{"type":"string"}}}}]},"PolymarketScreener":{"type":"object","additionalProperties":false,"required":["asOf","windowHours","observedMarkets","decomposed","markets","caveats"],"properties":{"asOf":{"type":"string","format":"date-time"},"windowHours":{"type":"number","minimum":0},"observedMarkets":{"type":"integer","minimum":0},"decomposed":{"type":"integer","minimum":0},"markets":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["conditionId","title","bucket","apparentVolumeUsd","topTraderShare","effectiveTraders","apparentVsBookFlag","marketClosed","resolution"],"properties":{"conditionId":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$","description":"Polymarket condition ID."},"title":{"type":"string","description":"Observed Polymarket market title."},"bucket":{"type":"string","enum":["unranked","structurally-thin","concentrated","moderate","broad"],"description":"Descriptive taker-flow structure bucket, not a fraud verdict."},"apparentVolumeUsd":{"type":"number","minimum":0,"description":"Observed taker-side volume in the materialized window, in USD."},"topTraderShare":{"type":"number","minimum":0,"maximum":1,"description":"Share of observed taker volume attributed to the top trader."},"effectiveTraders":{"type":"integer","minimum":0,"description":"HHI-derived effective trader count for the observed taker flow."},"apparentVsBookFlag":{"type":["boolean","null"],"description":"Whether observed volume is structurally inconsistent with available book liquidity."},"marketClosed":{"type":["boolean","null"],"description":"Whether the market was closed in the artifact."},"resolution":{"type":["object","null"],"additionalProperties":false,"required":["category","categoryDisputeRatePct","categoryFlipRatePct","titleLooksUncheckable"],"properties":{"category":{"type":"string","description":"Heuristic category inferred from the market title."},"categoryDisputeRatePct":{"type":["number","null"],"minimum":0,"maximum":100},"categoryFlipRatePct":{"type":["number","null"],"minimum":0,"maximum":100},"titleLooksUncheckable":{"type":"boolean","description":"True when the market TITLE states no checkable threshold (price, number, score, head-to-head). Read from the title only — the resolution rules are not read."}}}}}},"caveats":{"type":"array","items":{"type":"string"}}}},"ResolutionRiskLandscape":{"type":"object","additionalProperties":false,"required":["asOf","flipAsOf","dataDegraded","elevatedRiskCategories","byCategory","clarity","flipOverall","howToRead","caveats"],"properties":{"asOf":{"type":"string","format":"date-time"},"flipAsOf":{"type":["string","null"],"format":"date-time"},"dataDegraded":{"type":"boolean"},"elevatedRiskCategories":{"type":"array","items":{"type":"string"}},"byCategory":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["category","disputeRatePctHighVolume","disputeRatePctChronological","disputeInsufficientSample","elevated","lockupHoursPerMarket","lockupHoursIfDisputed","flipRatePct","flipInsufficientSample"],"properties":{"category":{"type":"string"},"disputeRatePctHighVolume":{"type":"number","minimum":0,"maximum":100},"disputeRatePctChronological":{"type":["number","null"],"minimum":0,"maximum":100},"disputeInsufficientSample":{"type":"boolean"},"elevated":{"type":"boolean"},"lockupHoursPerMarket":{"type":["number","null"],"minimum":0},"lockupHoursIfDisputed":{"type":["number","null"],"minimum":0},"flipRatePct":{"type":["number","null"],"minimum":0,"maximum":100},"flipInsufficientSample":{"type":"boolean"}}}},"clarity":{"type":["object","null"],"additionalProperties":false,"required":["checkableTitle","uncheckableTitle"],"properties":{"checkableTitle":{"type":"object","additionalProperties":false,"required":["marketsScanned","disputeRatePct"],"properties":{"marketsScanned":{"type":"integer","minimum":0},"disputeRatePct":{"type":"number","minimum":0,"maximum":100}}},"uncheckableTitle":{"type":"object","additionalProperties":false,"required":["marketsScanned","disputeRatePct"],"properties":{"marketsScanned":{"type":"integer","minimum":0},"disputeRatePct":{"type":"number","minimum":0,"maximum":100}}}}},"flipOverall":{"type":["object","null"],"additionalProperties":false,"required":["flipRatePct","disputedResolved"],"properties":{"flipRatePct":{"type":"number","minimum":0,"maximum":100},"disputedResolved":{"type":"integer","minimum":0}}},"howToRead":{"type":"string"},"caveats":{"type":"array","items":{"type":"string"}}}},"ResolutionWatchlist":{"type":"object","additionalProperties":false,"required":["asOf","windowHours","liveMarketsRanked","tierCounts","flipReferencePct","markets","howToRead","caveats"],"properties":{"asOf":{"type":"string","format":"date-time"},"windowHours":{"type":"number","minimum":0},"liveMarketsRanked":{"type":"integer","minimum":0},"tierCounts":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"flipReferencePct":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Referência de flip em %. `null` quando RETIDA — ver flipReferenceStatus. Nunca um default inventado."},"flipReferenceStatus":{"type":"string","enum":["measured","withheld"]},"flipReferenceWithheldReason":{"type":["string","null"]},"markets":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["conditionId","title","tier","disputeFlagCount","flags","category","titleLooksUncheckable","categoryElevated","categoryDisputeRatePctHighVolume","flipRatePct","apparentVolumeUsd","marketClosed"],"properties":{"conditionId":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$","description":"Polymarket condition ID."},"title":{"type":"string"},"tier":{"type":"string","enum":["elevated","watch","baseline"]},"disputeFlagCount":{"type":"integer","minimum":0},"flags":{"type":"object","additionalProperties":false,"required":["elevatedCategory","titleLooksUncheckable","flipProne"],"properties":{"elevatedCategory":{"type":"boolean"},"titleLooksUncheckable":{"type":"boolean"},"flipProne":{"type":"boolean"}}},"category":{"type":"string"},"titleLooksUncheckable":{"type":"boolean"},"categoryElevated":{"type":"boolean"},"categoryDisputeRatePctHighVolume":{"type":"number","minimum":0,"maximum":100},"flipRatePct":{"type":["number","null"],"minimum":0,"maximum":100},"apparentVolumeUsd":{"type":"number","minimum":0},"marketClosed":{"type":["boolean","null"]}}}},"howToRead":{"type":"string"},"caveats":{"type":"array","items":{"type":"string"}}}},"PolymarketCoverage":{"type":"object","additionalProperties":false,"required":["marketFlow","resolution","flipReference"],"properties":{"marketFlow":{"type":"object","additionalProperties":false,"required":["asOf","windowHours","observedMarkets","decomposedMarkets","marketsWithResolutionRisk","liveMarketsWithResolutionRisk"],"properties":{"asOf":{"type":"string","format":"date-time"},"windowHours":{"type":"number","minimum":0},"observedMarkets":{"type":"integer","minimum":0},"decomposedMarkets":{"type":"integer","minimum":0},"marketsWithResolutionRisk":{"type":"integer","minimum":0},"liveMarketsWithResolutionRisk":{"type":"integer","minimum":0}}},"resolution":{"type":"object","additionalProperties":false,"required":["asOf","categoriesCovered","highVolumeScanDegraded","chronologicalScanDegraded","clarity"],"properties":{"asOf":{"type":"string","format":"date-time"},"categoriesCovered":{"type":"integer","minimum":0},"highVolumeScanDegraded":{"type":"boolean"},"chronologicalScanDegraded":{"type":"boolean"},"clarity":{"type":["object","null"],"additionalProperties":false,"required":["checkableTitlesScanned","uncheckableTitlesScanned"],"properties":{"checkableTitlesScanned":{"type":"integer","minimum":0},"uncheckableTitlesScanned":{"type":"integer","minimum":0}}}}},"flipReference":{"type":["object","null"],"additionalProperties":false,"required":["asOf","disputedResolved","categoriesCovered"],"properties":{"asOf":{"type":["string","null"],"format":"date-time"},"disputedResolved":{"type":"integer","minimum":0},"categoriesCovered":{"type":"integer","minimum":0}}}}}}}}