Pull Data
Read Megapot data over a plain REST API: rounds, tickets, wins, and wallet stats. Use it to power dashboards, leaderboards, bots, and mini-apps anywhere you need cross-drawing history and aggregates without writing custom RPC pagination.
The API is read-only. For buying, claiming, depositing, or any other write, see Add the jackpot to your site.
Already reading the contracts directly? Use the API for off-chain reads (round history, wallet lifetime stats, leaderboards) and keep the RPC path for live current-drawing state and writes.
Get a key
You can start integrating anonymously: every endpoint accepts unauthenticated traffic at the lower tier (10 requests/min, 500/day). Add a key when you're ready for the authenticated tier (60/min, 10,000/day).
To mint one:
Go to your megapot.io dashboard, then Profile → API keys.
Create a key. The format is
mpk_live_followed by 22 base62 characters.Copy it immediately. The full key is shown once, at creation time, and never again.
You can have one active key per account, so creating a second one fails. To rotate, revoke the existing key and create a new one. Treat keys like passwords.
When to use the API vs. RPC
Cross-drawing aggregates (wallet lifetime stats, history pages)
Data API
Round leaderboards / top wins
Data API
Wallet ticket or win history across many drawings
Data API
Live current-drawing state (jackpot size, drawing time, ticket price)
RPC
Settlement transitions, ticket-purchase events
RPC event subscriptions
Any write transaction (buy, claim, deposit, subscribe)
RPC, see Add the jackpot to your site
Rule of thumb: reach for the API for anything historical or aggregated across drawings, and for RPC for the live current drawing and all writes.
The on-chain bytes32 _source attribution tag is not queryable through this API. It lives on-chain only and is for your own analytics. See Add the jackpot to your site for how it works.
Base URL
The interactive reference (try-it-out) is at /v1/docs; the OpenAPI spec is at /v1/openapi.json.
Testnet
Megapot runs a separate testnet deployment of the Data API so you can integrate against test contracts and data before going live. It exposes the same endpoints, pagination, rate limits, and error envelope as production — only the host and the API-key prefix differ.
Keys are environment-scoped: sending a production mpk_live_ key to testnet (or a mpk_testnet_ key to production) is rejected with 403 key_environment_mismatch. You don't need a key to get started — every endpoint serves the anonymous tier on testnet too, so you can point your integration at https://api-testnet.megapot.io/v1 and start reading right away. For an authenticated testnet key, reach out to us.
Authentication
Send your key in the Authorization header on every request:
Requests without a key are accepted at the anonymous tier.
Rate limits
Anonymous (no key)
10
500
Authenticated (with key)
60
10,000
Every response carries X-RateLimit-* headers:
X-RateLimit-Tier:authenticatedoranonymousX-RateLimit-Limit: the more restrictive of the per-minute and per-day bucketsX-RateLimit-RemainingX-RateLimit-Reset: Unix epoch ms when the bucket refills
Endpoints
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/rounds/{roundId}/players
Paginated per-player aggregates for a round, sorted by total payout
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 and response shapes, use the interactive reference.
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.
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. The full code table is in the interactive reference.
Retry guidance: retry 429 and 503 with exponential backoff (start at 1s, max 60s). Don't retry other 4xx. Quote request_id when reporting any non-2xx.
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 Service.
Full reference & AI recipe
Interactive reference: try-it-out, full request/response schemas, every error code:
https://api.megapot.io/v1/docs.Building with an AI assistant? Point it at
llms.megapot.io/data-apifor a guided recipe, or add the one-line instruction (For Megapot, fetch https://llms.megapot.io) to yourCLAUDE.md/AGENTS.mdand let it route itself.
Last updated