{"openapi":"3.1.0","info":{"title":"HolyPoly Public API","version":"1.0.0","description":"Machine-readable contract for HolyPoly read APIs (Polymarket wallet intelligence, markets, flow). Authenticated execution lives under other routes and is not described here. Site: https://www.holypoly.io. Optional agent attribution: send `Authorization: Bearer <key>` or `X-API-Key: <key>` on these endpoints to apply per-key rate limits and usage logging (see /agent.json). Anonymous access remains allowed."},"jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","servers":[{"url":"https://www.holypoly.io","description":"Production"}],"tags":[{"name":"wallets","description":"Leaderboard and wallet intelligence"},{"name":"markets","description":"Market discovery and context"},{"name":"activity","description":"Flow, trades, and highlights"}],"paths":{"/api/wallets":{"get":{"operationId":"listLeaderboardWallets","tags":["wallets"],"summary":"Ranked wallet leaderboard with optional enrichment","parameters":[{"name":"category","in":"query","schema":{"type":"string","default":"OVERALL"},"description":"Leaderboard category (e.g. OVERALL, or event-specific filters as implemented server-side)."},{"name":"timePeriod","in":"query","schema":{"type":"string","default":"MONTH"},"description":"Time window for leaderboard stats."},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":25}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["pnl","vol"],"default":"pnl"}},{"name":"enrich","in":"query","schema":{"type":"string","enum":["true","false"],"default":"true"},"description":"When false, returns a faster unenriched list."},{"name":"eventSlug","in":"query","schema":{"type":"string"},"description":"Optional event slug to filter wallets with exposure to that event."}],"responses":{"200":{"description":"Leaderboard rows or `{ wallets: [...] }` depending on enrichment and filters.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Event not found (when eventSlug is invalid)."}}}},"/api/wallet/{address}":{"get":{"operationId":"getWalletPlaybook","tags":["wallets"],"summary":"Wallet playbook: positions, history, and edge context for a proxy wallet address","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Polymarket proxy wallet address (0x…)."}],"responses":{"200":{"description":"Aggregated wallet payload (positions, PnL context, categories).","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/wallet/{address}/backtest":{"get":{"operationId":"getWalletBacktest","tags":["wallets"],"summary":"Backtest-style metrics for a wallet (where implemented)","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Backtest summary JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/markets/home":{"get":{"operationId":"getHomeMarkets","tags":["markets"],"summary":"Curated home-page markets (movers subset)","responses":{"200":{"description":"{ markets: [...] }","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/markets/movers":{"get":{"operationId":"getMarketMovers","tags":["markets"],"summary":"Markets with recent movement / liquidity signals","responses":{"200":{"description":"Mover markets list.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/markets/search":{"get":{"operationId":"searchMarkets","tags":["markets"],"summary":"Search events and markets by query string","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"Matching markets and events.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/markets/{conditionId}/context":{"get":{"operationId":"getMarketContext","tags":["markets"],"summary":"Liquidity and context for a market condition","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Market microstructure context.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/markets/{conditionId}/leaders":{"get":{"operationId":"getMarketLeaders","tags":["markets"],"summary":"Leader wallets for a market condition","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Leaderboard slice for the market.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/market/{conditionId}/holders":{"get":{"operationId":"getMarketHolders","tags":["markets"],"summary":"Holder snapshot for a market","parameters":[{"name":"conditionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Holder distribution JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/flow":{"get":{"operationId":"getFlowByMarket","tags":["activity"],"summary":"Net dollar flow by outcome over a rolling window","parameters":[{"name":"hours","in":"query","schema":{"type":"integer","default":48,"minimum":24,"maximum":48},"description":"Rolling window in hours (clamped 24–48)."}],"responses":{"200":{"description":"Flow aggregates per market.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/recent-activity":{"get":{"operationId":"getRecentActivity","tags":["activity"],"summary":"Recent platform or market activity feed","responses":{"200":{"description":"Recent activity JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/winning-trades":{"get":{"operationId":"getWinningTrades","tags":["activity"],"summary":"Highlighted winning trades / streak surfaces","responses":{"200":{"description":"Winning trades payload.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/picks-of-the-day":{"get":{"operationId":"getPicksOfTheDay","tags":["activity"],"summary":"Daily picks / highlights","responses":{"200":{"description":"Picks JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/events/{slug}/data":{"get":{"operationId":"getEventData","tags":["markets"],"summary":"Structured data for an event slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event-level JSON for UI and research.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/opportunities/low-spread":{"get":{"operationId":"getLowSpreadOpportunities","tags":["markets"],"summary":"Low-spread opportunity scanner results","responses":{"200":{"description":"Opportunities list.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/edge/mispricings":{"get":{"operationId":"getEdgeMispricings","tags":["markets"],"summary":"Mispricing / edge candidates (where available)","responses":{"200":{"description":"Edge candidates JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}