Skip to navigation
Stream

Filters and subscription scope

View as Markdown

Filters choose which permitted data you need. They do not grant additional access.

FieldSelectsBoundary
ownersOrder ownersNot signers or transaction senders
tokenIdsOutcome tokensCanonical unsigned decimal strings
conditionIdsConditions through a frozen mappingA known catalog binding is required
marketSlugsMarkets through a frozen slug mappingNot free-text question search
stagespending, included, reverted, canonicality, resolutionNecessary correction closure remains active

OR within lists, AND between facets

This filter fragment selects owner A or B, AND token 7 or 8, AND the included stage. Addresses and tokens are synthetic.

{
  "owners": ["0x1111111111111111111111111111111111111111", "0x2222222222222222222222222222222222222222"],
  "tokenIds": ["7", "8"],
  "stages": ["included"]
}

An omitted facet imposes no predicate. Current parsing also treats a facet set to null as omitted; prefer omission when constructing requests. Empty arrays are rejected. Each provided array has at most 256 entries before normalization; account and combined resource caps apply separately. Unknown fields are rejected.

Owners and conditions use canonical lowercase hex. Slugs contain lowercase letters, digits or hyphens, are 1–256 ASCII characters, and cannot start or end with a hyphen. Detailed shapes are in frames.

Access modes

Owner allowlist requires permitted owners. Market-filtered mode requires market_data and at least one entity selector. Full stream requires separate firehose permission. Stage and replay scopes are independent; an empty filter does not authorize firehose.

Frozen mappings

subscribed.frozenMarkets and frozenConditions record the selected mapping. Condition selectors can match their condition facet or a token in that condition’s frozen mapping, allowing supported receipt-only executions to match without a condition facet. Slug and condition groups remain independent AND predicates.

Catalog refresh cannot reinterpret an old cursor. Frozen snapshots do not promise freshness or completeness of the whole Polymarket catalog. Change a predicate using rebind; reconnect using the previous predicate and resume.

Quality notices route by entitled source/network/contract scope before wallet/token trade predicates. A quiet wallet can therefore receive a source notice without a matching trade.