{"openapi":"3.1.0","info":{"title":"Polymarket data API","description":"Wallet trades, reconstructed P&L including resolved losses, market history, and order books. Public API history can be truncated; coverage accompanies results.","version":"0.1.0"},"paths":{"/health":{"get":{"tags":["Operations"],"summary":"API and data freshness status","operationId":"health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/wallets/{id}/pnl":{"get":{"tags":["Wallets"],"summary":"Polymarket wallet P&L including hidden losses","description":"Reconcile visible buys and sells with market resolutions. Coverage flags explain missing history, transfers, and unresolved positions.","operationId":"wallet_pnl","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletPnl"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/wallets/{id}/trades":{"get":{"tags":["Wallets"],"summary":"Download a Polymarket wallet's trade history","description":"Page through locally retained fills. The upstream per-wallet offset cap means older fills may be missing.","operationId":"wallet_trades","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$","title":"Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000000,"minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletTrades"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets":{"get":{"tags":["Markets"],"summary":"Find Polymarket markets and resolutions","description":"Read live Gamma market metadata with keyset pagination. With resolved=true, read confirmed winners from the local archive; each response identifies its pagination source.","operationId":"markets","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Cursor"}},{"name":"resolved","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Resolved"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{id}/history":{"get":{"tags":["Markets"],"summary":"Polymarket historical prices for both outcomes","description":"Return each outcome token's price series at the requested minute fidelity, with source coverage.","operationId":"market_history","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$","title":"Id"}},{"name":"fidelity","in":"query","required":false,"schema":{"type":"integer","maximum":10080,"minimum":1,"default":60,"title":"Fidelity"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketHistory"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/markets/{id}/book":{"get":{"tags":["Markets"],"summary":"Polymarket order book snapshots","description":"Fetch current bid and ask levels. Subscribe to a market to keep recording snapshots.","operationId":"market_book","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketBook"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/leaderboard/true-pnl":{"get":{"tags":["Leaderboard"],"summary":"True P&L for the monthly Polymarket leaderboard","description":"Daily reconciliation of the current top 50 monthly wallets. The observed trade window is separate from official monthly P&L.","operationId":"true_pnl_leaderboard","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Leaderboard"}}}}},"security":[{"APIKeyHeader":[]}]}},"/resolutions":{"get":{"tags":["Markets"],"summary":"Polymarket resolved markets and winning outcomes","operationId":"resolutions","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/subscriptions/{id}":{"put":{"tags":["Subscriptions"],"summary":"Record live order books for a market","operationId":"subscribe_book","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Subscriptions"],"summary":"Stop recording a subscribed market","operationId":"unsubscribe_book","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/subscriptions/{id}/books":{"get":{"tags":["Subscriptions"],"summary":"Download recorded Polymarket order books","description":"Read retained websocket events and REST snapshots captured during this API key's subscription windows. Ending a subscription preserves access to its recordings until retention expires. Records outside those windows are excluded. Paginate by row ID; retention is seven days or 100,000 rows per market, whichever comes first.","operationId":"recorded_books","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9_.-]+$","title":"Id"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at","title":"Since"},"description":"Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at","title":"Until"},"description":"Inclusive timestamp with timezone, compared at the microsecond precision of recorded_at"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordedBooks"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/account":{"get":{"tags":["Account"],"summary":"API plan and request usage","operationId":"account","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}}},"security":[{"APIKeyHeader":[]}]}},"/signup":{"post":{"tags":["Account"],"summary":"Create a free API key","description":"Create a Free-plan key (100 requests a day). The key is shown once; the server stores only its hash. Limited to 3 signups per address per day.","operationId":"signup","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/checkout":{"post":{"tags":["Billing"],"summary":"Start a Builder or Pro subscription","description":"Create a Stripe Checkout session when live billing is configured. Local mode returns a test result and charges nothing.","operationId":"billing_checkout","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/billing/webhook":{"post":{"tags":["Billing"],"summary":"Receive signed Stripe subscription events","description":"Stripe signs events with STRIPE_WEBHOOK_SECRET. Local test billing is never exposed over HTTP.","operationId":"billing_webhook","parameters":[{"name":"stripe-signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Account":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"plan":{"type":"string","enum":["free","builder","pro"],"title":"Plan"},"requests_today":{"type":"integer","title":"Requests Today"},"limit":{"type":"integer","title":"Limit"},"remaining":{"type":"integer","title":"Remaining"}},"type":"object","required":["id","name","plan","requests_today","limit","remaining"],"title":"Account"},"Checkout":{"properties":{"provider":{"type":"string","enum":["local","stripe"],"title":"Provider"},"session_id":{"type":"string","title":"Session Id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"plan":{"type":"string","enum":["builder","pro"],"title":"Plan"}},"additionalProperties":true,"type":"object","required":["provider","session_id","url","plan"],"title":"Checkout"},"CheckoutRequest":{"properties":{"plan":{"type":"string","enum":["builder","pro"],"title":"Plan"}},"type":"object","required":["plan"],"title":"CheckoutRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Health":{"properties":{"status":{"type":"string","enum":["ok","warming","degraded"],"title":"Status"},"uptime_seconds":{"type":"number","title":"Uptime Seconds"},"billing_mode":{"type":"string","title":"Billing Mode"},"database":{"type":"string","title":"Database"},"data":{"additionalProperties":true,"type":"object","title":"Data"}},"type":"object","required":["status","uptime_seconds","billing_mode","database","data"],"title":"Health"},"Leaderboard":{"properties":{"status":{"type":"string","title":"Status"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"},"wallets_requested":{"type":"integer","title":"Wallets Requested"},"wallets_computed":{"type":"integer","title":"Wallets Computed"},"rows":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rows"}},"additionalProperties":true,"type":"object","required":["status","updated_at","wallets_requested","wallets_computed","rows"],"title":"Leaderboard"},"MarketBook":{"properties":{"market_id":{"type":"string","title":"Market Id"},"recorded_at":{"type":"string","title":"Recorded At"},"books":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Books"},"recent_trades":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Recent Trades"}},"additionalProperties":true,"type":"object","required":["market_id","recorded_at","books","recent_trades"],"title":"MarketBook"},"MarketHistory":{"properties":{"condition_id":{"type":"string","title":"Condition Id"},"fidelity_minutes":{"type":"integer","title":"Fidelity Minutes"},"series":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Series"},"coverage":{"type":"string","title":"Coverage"}},"additionalProperties":true,"type":"object","required":["condition_id","fidelity_minutes","series","coverage"],"title":"MarketHistory"},"MarketPage":{"properties":{"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"additionalProperties":true,"type":"object","required":["items"],"title":"MarketPage"},"RecordedBooks":{"properties":{"market_id":{"type":"string","title":"Market Id"},"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"},"retention":{"type":"string","title":"Retention"}},"type":"object","required":["market_id","items","next_cursor","retention"],"title":"RecordedBooks"},"SignupRequest":{"properties":{"email":{"type":"string","maxLength":200,"minLength":3,"pattern":"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$","title":"Email"}},"type":"object","required":["email"],"title":"SignupRequest"},"Subscription":{"properties":{"market_id":{"type":"string","title":"Market Id"},"subscribed":{"type":"boolean","title":"Subscribed"}},"additionalProperties":true,"type":"object","required":["market_id","subscribed"],"title":"Subscription"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WalletPnl":{"properties":{"wallet":{"type":"string","title":"Wallet"},"realized_pnl_usd":{"type":"number","title":"Realized Pnl Usd","description":"Observed sells and resolved remaining inventory P&L, before unobserved costs"},"hidden_loss_usd":{"type":"number","title":"Hidden Loss Usd","description":"Remaining observed cost basis of resolved losing tokens, expressed as a positive loss amount"},"coverage":{"additionalProperties":true,"type":"object","title":"Coverage"},"positions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Positions"},"limitations":{"items":{"type":"string"},"type":"array","title":"Limitations"}},"additionalProperties":true,"type":"object","required":["wallet","realized_pnl_usd","hidden_loss_usd","coverage","positions","limitations"],"title":"WalletPnl"},"WalletTrades":{"properties":{"wallet":{"type":"string","title":"Wallet"},"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"coverage":{"additionalProperties":true,"type":"object","title":"Coverage"}},"additionalProperties":true,"type":"object","required":["wallet","items","total","limit","offset","coverage"],"title":"WalletTrades"},"WebhookResult":{"properties":{"received":{"type":"boolean","title":"Received"},"state":{"type":"string","title":"State"}},"additionalProperties":true,"type":"object","required":["received","state"],"title":"WebhookResult"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}