Data API

Read-only REST API for Megapot rounds, tickets, wins, and wallet stats. Use it to power partner dashboards, leaderboards, mini-apps, and analytics — anywhere you need cross-drawing aggregates without writing custom RPC pagination.

circle-check

When to use the API vs. RPC

You need...
Use

Cross-drawing aggregates (wallet lifetime stats, history pages)

Data API

Round leaderboards / top wins

Data API

Wallet ticket history across many drawings

Data API

Live current-drawing state (jackpot size, drawing time)

Settlement transitions, ticket-purchase events

RPC event subscriptions

Any write transaction (buy, claim, deposit, subscribe)

RPC (buy-tickets, etc.)

The API is read-only. For writes, see Add Megapot to Your Site.


Get a key

Visit your megapot.io dashboardarrow-up-right to create an API key.

circle-info

You can begin integration work without a key. Every endpoint accepts anonymous traffic at a lower rate-limit tier (see below). The key just elevates you to the partner tier.

Need help? Reach out at megapot.io/supportarrow-up-right.


Base URL

The interactive reference (Scalar UI with try-it-out) is at /v1/docsarrow-up-right; the OpenAPI 3.x spec is at /v1/openapi.jsonarrow-up-right.


Authentication

Send your key in the Authorization header on every request:

Key format: mpk_live_<22 base62 chars>. Treat keys like passwords — store them somewhere safe. Lost a key? Visit your megapot.io dashboardarrow-up-right to manage and rotate keys.


Rate limits

Tier
Per-minute
Per-day

Authenticated (with key)

60

10,000

Anonymous (no key)

10

500

Every response carries:

  • X-RateLimit-Tierauthenticated or anonymous

  • X-RateLimit-Limit — the more restrictive of the per-minute and per-day buckets

  • X-RateLimit-Remaining

  • X-RateLimit-Reset — Unix epoch ms when the bucket refills

If your use case warrants higher limits, reach out at megapot.io/supportarrow-up-right.


Endpoints

Path
Description

GET /v1/rounds

Paginated rounds, newest first

GET /v1/rounds/active

Current open or drawing round

GET /v1/rounds/{roundId}

Single round + per-round aggregates

GET /v1/rounds/{roundId}/tickets

Paginated tickets in a round

GET /v1/rounds/{roundId}/wins

Paginated wins in a round, sorted by amount

GET /v1/wallets/{address}/stats

Aggregate ticket and winnings stats

GET /v1/wallets/{address}/tickets

Paginated tickets for a wallet

GET /v1/wallets/{address}/tickets/rounds/{roundId}

Wallet tickets in a specific round

GET /v1/wallets/{address}/wins

Paginated wins for a wallet

GET /v1/wallets/{address}/wins/rounds/{roundId}

Wallet wins in a specific round

For full request/response shapes, see the interactive referencearrow-up-right.


Errors

Every non-2xx response uses the same envelope:

Discriminate on error.code. Common codes: invalid_request, invalid_address, invalid_api_key, rate_limited, not_found, internal_error. Full code table is in the interactive referencearrow-up-right.

Retry guidance: retry 429 and 503 with exponential backoff (start at 1s, max 60s). Don't retry 4xx (except 429). Quote request_id when reporting any non-2xx.


Pagination

List endpoints use cursor-based pagination:

Response shape:

To fetch the next page, pass next_cursor back as ?cursor=.... When has_more is false, you're at the end. limit defaults to 50, max 100.


Versioning

URL-based: /v1/. We don't break things within a version.

  • Additive changes (new endpoints, new optional fields, new error codes) — non-breaking; ship anytime.

  • Breaking changes (renamed/removed fields, narrower validation, changed types) — go to /v2/.

  • Deprecation — when an endpoint or field is on the way out, we add a Sunset: header and announce 90 days before removal.


Terms of use

Use of this API is governed by the Megapot Data API Terms of Servicearrow-up-right.


Building with an AI coding assistant?

A dedicated Megapot Data API skillarrow-up-right is available alongside the on-chain skills at llms.megapot.ioarrow-up-right. Add the standard one-line instruction (For Megapot contract work, fetch https://llms.megapot.io) to your CLAUDE.md / AGENTS.md / .cursorrules and your assistant will route to the right skill — including this API — based on what you're building. See AI Agent Skills for the full list.


Full reference

The complete interactive reference — try-it-out, full request/response schemas, every error code — lives at https://api.megapot.io/v1/docsarrow-up-right.

Last updated