> ## Documentation Index > Fetch the complete documentation index at: https://docs.seesaw.fun/llms.txt > Use this file to discover all available pages before exploring further. # Get a leaderboard (global, zone, or contest) > Parameters depend on `scope`: - **global** — `type` (credits|accuracy|volume, default credits), `period` (all|monthly|weekly, default all), `limit`. Top-N only: `next_cursor` is always `null`. - **zone** — `id` (zone slug, **required**), `month` (`YYYY-MM`, default current month), `cursor`/`limit`. - **contest** — `round` (optional), `cursor`/`limit`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /leaderboards/{scope} openapi: 3.1.0 info: title: SeeSaw Open API version: 1.0.0-beta description: > The **read-only open API** of SeeSaw — a dedicated surface for AI agents and third-party integrations, exposed both as REST (`/open/v1/*`) and as an **MCP server** (`/mcp`, Streamable HTTP, stateless) in the same process. This contract is independent from the app-facing API (`docs/api/swagger.yaml`): it does not inherit app DTO shapes and follows its own conventions. ## Conventions - Field names are `snake_case`; enums are lowercase strings. - Decimals (credits, probabilities, volumes) are **strings**, never floats. - Timestamps are RFC 3339 UTC (`2026-07-04T12:00:00Z`). - The public user identifier is `handle`; every resource carries a human-visitable `url`. - Lists use **opaque cursor pagination**: `{data, next_cursor, has_more}`. `limit` defaults to 20, max 100. Reusing a cursor with different query params does not guarantee continuity. - Single resources are returned bare (no wrapper); errors use `{"error": {"code", "message", "details"}}`. ## Authentication Every request (public data included) requires a **personal API key** (PAT): `Authorization: Bearer sspat_…`. Keys are issued per user (max 5 active), carry `scopes` (currently always `read`), and can be revoked anytime. Key management lives on the app API (`/v1/users/me/api-keys`, JWT auth — see swagger.yaml), NOT on this surface. ## Rate limits (per key) - 120 requests/min and 10,000 requests/day across the surface. - Search is additionally capped at 30 requests/min — a dedicated per-key budget shared by REST `/search` and the MCP `search_topics` tool (search consumes both this window and the general one). - `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` response headers reflect the binding minute window; 429 responses carry `Retry-After`. Over MCP, exceeding a quota surfaces as a tool error naming the retry delay. ## MCP server `POST https://api.seesaw.fun/mcp` (Streamable HTTP, stateless, same `Authorization` header) exposes the same 14 capabilities as tools: `search_topics`, `list_topics`, `get_topic`, `list_topic_comments`, `get_topic_price_history`, `get_user`, `list_user_topics`, `get_leaderboard`, `list_zones`, `get_contest`, `get_my_profile`, `list_my_positions`, `list_my_settlements`, `list_my_topics`. Tool results carry the corresponding REST response JSON. ## Known behavior notes - `status=open` filters by the stored active state: it includes topics past their deadline but not yet settled (the item itself then shows `status: closed`). - `GET /search` with `type=all` returns a fixed-size preview: it ignores `cursor`/`limit` and always reports `has_more: false` with `next_cursor: null`; to paginate, request a single `type`. - The global leaderboard is top-N only (no cursor). servers: - url: https://api.seesaw.fun/open/v1 description: Production security: - apiKey: [] tags: - name: Topics description: Prediction markets and polls (unified "topics") - name: Users description: Public user profiles and their created topics - name: Leaderboards description: Global, zone, and contest leaderboards - name: Zones description: Topic zones (communities) - name: Contests description: World Cup pick'em contests - name: Me description: Data of the authenticated key owner paths: /leaderboards/{scope}: get: tags: - Leaderboards summary: Get a leaderboard (global, zone, or contest) description: | Parameters depend on `scope`: - **global** — `type` (credits|accuracy|volume, default credits), `period` (all|monthly|weekly, default all), `limit`. Top-N only: `next_cursor` is always `null`. - **zone** — `id` (zone slug, **required**), `month` (`YYYY-MM`, default current month), `cursor`/`limit`. - **contest** — `round` (optional), `cursor`/`limit`. operationId: getLeaderboard parameters: - name: scope in: path required: true schema: type: string enum: - global - zone - contest - name: type in: query description: 'scope=global: ranking dimension' schema: type: string enum: - credits - accuracy - volume default: credits - name: period in: query description: 'scope=global: time window' schema: type: string enum: - all - monthly - weekly default: all - name: id in: query description: 'scope=zone: zone slug (required)' schema: type: string - name: month in: query description: 'scope=zone: month like 2026-07 (default: current month)' schema: type: string pattern: ^\d{4}-\d{2}$ - name: round in: query description: 'scope=contest: round filter (omit for the overall board)' schema: type: string - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' responses: '200': description: The leaderboard with its query context echoed back content: application/json: schema: $ref: '#/components/schemas/Leaderboard' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: Cursor: name: cursor in: query description: Opaque pagination cursor from a previous response's `next_cursor`. schema: type: string Limit: name: limit in: query description: Page size (max 100). schema: type: integer default: 20 minimum: 1 maximum: 100 schemas: Leaderboard: type: object description: >- Self-describing envelope — `context` echoes the resolved query so agents can cite what board they are looking at. required: - scope - context - data - next_cursor - has_more properties: scope: type: string enum: - global - zone - contest context: type: object additionalProperties: true description: 'global: {type, period}; zone: {slug, month}; contest: {round}.' data: type: array items: $ref: '#/components/schemas/LeaderboardEntry' next_cursor: type: - string - 'null' description: Always null for scope=global (top-N board). has_more: type: boolean LeaderboardEntry: type: object description: | Scope-dependent optional fields: `score` (global+zone), `topics_count`/`unique_traders_count` (zone), `correct_count`/`settled_count`/`prize_level` (contest). required: - rank - user properties: rank: type: integer user: $ref: '#/components/schemas/UserSummary' score: type: string description: Decimal string. topics_count: type: integer unique_traders_count: type: integer correct_count: type: integer settled_count: type: integer prize_level: type: string Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - INVALID_ARGUMENT - RATE_LIMITED - SERVICE_DISABLED - INTERNAL description: | Stable contract values. `SERVICE_DISABLED` (HTTP 503) is the emergency kill switch; `FORBIDDEN` (HTTP 403) is reserved for future scopes. message: type: string details: type: object description: >- Optional context, e.g. `{"field": "limit"}` or `{"retry_after": 12}`. additionalProperties: true UserSummary: type: object description: >- Embedded wherever a user appears. Deliberately carries no financial fields. required: - id - handle - nickname - avatar_url - account_type - url properties: id: type: string format: uuid handle: type: - string - 'null' nickname: type: string avatar_url: type: - string - 'null' account_type: type: string enum: - user - bot url: type: string description: 'Public profile page: https://seesaw.fun/profile/{id}' responses: BadRequest: description: Invalid argument (`details.field` names the offending parameter) content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing, invalid, revoked, or expired API key (carries `WWW-Authenticate`) headers: WWW-Authenticate: schema: type: string description: Bearer realm="seesaw-open-api" content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- Resource missing, unknown handle, hidden by privacy settings, or removed/hidden by moderation (existence does not leak) content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Rate limit exceeded (see `Retry-After` and `details.retry_after` seconds) headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sspat_ personal API key description: | Personal API key issued per SeeSaw user account: `Authorization: Bearer sspat_…`. Manage keys on the app API (`/v1/users/me/api-keys`). Revocation propagates within ~60 seconds (validation cache window). ````