# Market Event Screener

## Get Prediction Market Event Screener

> Browse and filter Polymarket events (groups of related markets). Includes aggregated\
> volume, liquidity, and trader counts across all markets in each event.\
> \
> \*\*What it helps to answer:\*\*\
> \
> 1\. \*\*What are the most popular prediction market events?\*\*\
> 2\. \*\*How much total volume does an event have across all its markets?\*\*\
> 3\. \*\*Which events have the most active trading?\*\*

```json
{"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apiKey","description":"API key for authentication"}},"schemas":{"EventScreenerRequest":{"properties":{"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SortOrder_ScreenerSortField_"},"type":"array"}],"title":"Order By","description":"Sort order"},"sort_by":{"$ref":"#/components/schemas/ScreenerSortField","description":"Deprecated: use 'order_by' instead.","default":"volume_24hr"},"query":{"type":"string","maxLength":200,"title":"Query","description":"Search query to filter results","default":""},"status":{"$ref":"#/components/schemas/MarketStatus","description":"Filter by status (active, closed, or empty for all)","default":""},"tags":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Tags","description":"Filter by tags"},"min_liquidity":{"type":"number","minimum":-1,"title":"Min Liquidity","description":"Minimum liquidity filter (-1 = no filter)","default":-1},"max_liquidity":{"type":"number","minimum":-1,"title":"Max Liquidity","description":"Maximum liquidity filter (-1 = no limit)","default":-1},"max_unique_traders_24h":{"type":"integer","minimum":-1,"title":"Max Unique Traders 24H","description":"Maximum unique traders in 24h (-1 = no limit)","default":-1},"min_volume_24hr":{"type":"number","minimum":-1,"title":"Min Volume 24Hr","description":"Minimum 24h volume filter (-1 = no filter)","default":-1},"neg_risk":{"anyOf":[{"type":"boolean"}],"title":"Neg Risk","description":"Filter by neg-risk framework (null = no filter)"},"min_open_interest":{"type":"number","minimum":-1,"title":"Min Open Interest","description":"Minimum open interest filter (-1 = no filter)","default":-1},"max_open_interest":{"type":"number","minimum":-1,"title":"Max Open Interest","description":"Maximum open interest filter (-1 = no limit)","default":-1},"end_date_before":{"type":"string","maxLength":100,"title":"End Date Before","description":"Filter markets ending before this datetime (ISO 8601)","default":""},"end_date_after":{"type":"string","maxLength":100,"title":"End Date After","description":"Filter markets ending after this datetime (ISO 8601)","default":""},"pagination":{"$ref":"#/components/schemas/PaginationRequest"}},"additionalProperties":false,"type":"object","title":"EventScreenerRequest","description":"Request for event screener endpoint."},"SortOrder_ScreenerSortField_":{"properties":{"field":{"$ref":"#/components/schemas/ScreenerSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SortOrder[ScreenerSortField]"},"ScreenerSortField":{"type":"string","enum":["volume_24hr","volume","volume_1wk","volume_1mo","liquidity","open_interest","unique_traders_24h","age_hours"],"title":"ScreenerSortField","description":"Valid sort fields for screener endpoints."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"MarketStatus":{"type":"string","enum":["active","closed",""],"title":"MarketStatus","description":"Valid status filters for screener endpoints."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"EventScreenerResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo"},"data":{"items":{"$ref":"#/components/schemas/EventScreenerItem"},"type":"array","title":"Data","description":"List of event screener records"}},"type":"object","required":["data"],"title":"EventScreenerResponse","description":"Response for event screener endpoint."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"EventScreenerItem":{"properties":{"event_id":{"type":"string","title":"Event Id","description":"Event ID"},"event_title":{"anyOf":[{"type":"string"}],"title":"Event Title","description":"Event title"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"}],"title":"Tags","description":"Event tags"},"neg_risk":{"anyOf":[{"type":"boolean"}],"title":"Neg Risk","description":"Uses neg-risk framework"},"market_count":{"anyOf":[{"type":"integer"}],"title":"Market Count","description":"Number of markets"},"total_volume":{"anyOf":[{"type":"number"}],"title":"Total Volume","description":"Total volume (USD)"},"total_volume_24hr":{"anyOf":[{"type":"number"}],"title":"Total Volume 24Hr","description":"Total 24h volume (USD)"},"total_volume_1wk":{"anyOf":[{"type":"number"}],"title":"Total Volume 1Wk","description":"Total 1 week volume (USD)"},"total_volume_1mo":{"anyOf":[{"type":"number"}],"title":"Total Volume 1Mo","description":"Total 1 month volume (USD)"},"total_liquidity":{"anyOf":[{"type":"number"}],"title":"Total Liquidity","description":"Total liquidity (USD)"},"total_open_interest":{"anyOf":[{"type":"number"}],"title":"Total Open Interest","description":"Total open interest (USD)"},"total_volume_change_pct":{"anyOf":[{"type":"number"}],"title":"Total Volume Change Pct","description":"Total volume change percentage"},"total_traders_24h":{"anyOf":[{"type":"integer"}],"title":"Total Traders 24H","description":"Total unique traders in 24h"},"max_age_hours":{"anyOf":[{"type":"number"}],"title":"Max Age Hours","description":"Max market age in hours"},"top_market_id":{"anyOf":[{"type":"string"}],"title":"Top Market Id","description":"Top market by 24h volume"},"top_market_question":{"anyOf":[{"type":"string"}],"title":"Top Market Question","description":"Top market question"},"top_market_volume_24hr":{"anyOf":[{"type":"number"}],"title":"Top Market Volume 24Hr","description":"Top market 24h volume"},"markets":{"anyOf":[{"items":{"$ref":"#/components/schemas/EventScreenerMarket"},"type":"array"}],"title":"Markets","description":"Nested market data"}},"type":"object","required":["event_id"],"title":"EventScreenerItem","description":"Event screener data from ch_api_pm_event_screener."},"EventScreenerMarket":{"properties":{"market_id":{"type":"string","title":"Market Id"},"question":{"type":"string","title":"Question"},"volume_24hr":{"anyOf":[{"type":"number"}],"title":"Volume 24Hr"},"open_interest":{"anyOf":[{"type":"number"}],"title":"Open Interest"},"best_bid":{"anyOf":[{"type":"number"}],"title":"Best Bid"},"best_ask":{"anyOf":[{"type":"number"}],"title":"Best Ask"},"last_trade_price":{"anyOf":[{"type":"number"}],"title":"Last Trade Price"},"one_day_price_change":{"anyOf":[{"type":"number"}],"title":"One Day Price Change"},"volume_change_pct":{"anyOf":[{"type":"number"}],"title":"Volume Change Pct"},"unique_traders_24h":{"anyOf":[{"type":"integer"}],"title":"Unique Traders 24H"},"end_date":{"anyOf":[{"type":"string","format":"date-time"}],"title":"End Date"}},"type":"object","required":["market_id","question"],"title":"EventScreenerMarket","description":"Single market within an event screener row."}},"headers":{"XNansenCreditsUsed":{"description":"Number of credits consumed by this API request","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Time in seconds until the rate limit window resets","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via the x402 protocol. The `Payment-Required` response header contains a base64-encoded JSON object describing accepted payment options (scheme, network, asset, amount, recipient). To pay, include a `Payment-Signature` header with a base64-encoded signed payment payload. See https://www.x402.org for protocol details.","headers":{"Payment-Required":{"description":"Base64-encoded JSON describing accepted payment options","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","description":"Empty object. Payment details are in the Payment-Required header."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":"string"}},"msg":{"type":"string"},"type":{"type":"string"}}}}}}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}},"paths":{"/api/v1/prediction-market/event-screener":{"post":{"tags":["Prediction Markets"],"summary":"Get Prediction Market Event Screener","description":"Browse and filter Polymarket events (groups of related markets). Includes aggregated\nvolume, liquidity, and trader counts across all markets in each event.\n\n**What it helps to answer:**\n\n1. **What are the most popular prediction market events?**\n2. **How much total volume does an event have across all its markets?**\n3. **Which events have the most active trading?**","operationId":"get_prediction_market_event_screener_api_v1_prediction_market_event_screener_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventScreenerRequest"}}},"required":true},"responses":{"200":{"description":"Event screener data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventScreenerResponse"}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"}}}}}}
```