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

You need…	Use
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
Prize tier payouts — settled or active round	Data API, `prize_tiers` (see Prize tiers below)
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. Prize tiers are the exception — the API serves them for the live round too.

The on-chain bytes32 _source attribution tag is not queryable through this API. It lives on-chain only. Allow-listed tags are shown on megapot.io (see Get Listed). See Add the jackpot to your site for how it works.

Base URL

https://api.megapot.io/v1

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.

Environment	Base URL	Interactive reference	Key prefix
Production	`https://api.megapot.io/v1`	`/v1/docs`	`mpk_live_`
Testnet	`https://api-testnet.megapot.io/v1`	`/v1/docs`	`mpk_testnet_`

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:

curl https://api.megapot.io/v1/rounds/active \
  -H "Authorization: Bearer mpk_live_xxxxxxxxxxxxxxxxxxxxxx"

Requests without a key are accepted at the anonymous tier.

Rate limits

Tier	Per-minute	Per-day
Anonymous (no key)	10	500
Authenticated (with key)	60	10,000

Every response carries X-RateLimit-* headers:

X-RateLimit-Tier: authenticated 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

Endpoints

Path	Description
`GET /v1/rounds`	Paginated rounds, newest first
`GET /v1/rounds/active`	Current open or drawing round, including expected `prize_tiers`
`GET /v1/rounds/latest-settled`	Most recently settled round (last completed drawing)
`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.

Prize tiers

Every round response carries a prize_tiers array — 12 entries, one per prize tier, sorted by tier_id:

{
  "tier_id": 11,
  "normal_matches": 5,
  "bonusball_match": true,
  "payout": { "amount": "183029000000", "decimals": 6 },
  "ticket_count": 1
}

tier_id is normal_matches * 2 + (bonusball_match ? 1 : 0). Tiers 0 and 2 never pay out. payout is the contract’s gross per-ticket amount — divide by 10 ** decimals for USDC. This works on the active round, not just settled ones. To show “what does each tier pay this round?”, call GET /v1/rounds/active and read prize_tiers. You don’t need a contract call for this.

curl https://api.megapot.io/v1/rounds/active \
  -H "Authorization: Bearer mpk_live_xxxxxxxxxxxxxxxxxxxxxx"

What the field means depends on round state:

	`status: "settled"`	`status: "active"`
`payout`	Final per-tier payout	The contract’s expected payout for the round in flight
`ticket_count`	Tickets that landed in the tier	Always `0` — matches are only computed at settlement

Branch on status, not on prize_tiers being present. The field is populated in both states, so a non-null prize_tiers no longer means the round has settled.

Two things to know about the active-round numbers:

They’re estimates. They assume no duplicate ticket combinations, so final settled payouts can differ slightly. Label them as estimates in your UI.
They don’t tick. The estimate is fixed for the drawing — ordinary ticket sales don’t move it, and the ball ranges and tier config are locked when the drawing opens. No need to poll; it changes at rollover.

prize_tiers can be null in two cases, so keep a fallback: on an active round if the expected payouts are momentarily unavailable, and on a settled round during the short window before final payouts finish landing. Render the round without the breakdown rather than failing the page.

Prefer the contracts? GuaranteedMinimumPayoutCalculator.getExpectedDrawingTierPayouts is the live chain read for the same numbers, and getDrawingTierInfo(drawingId) returns the tier weights and guaranteed minimums in force for a drawing. Reach for those when you want the value straight from the chain with no API dependency. See Protocol reference.

Pagination

List endpoints use cursor-based pagination:

curl "https://api.megapot.io/v1/rounds?limit=50" \
  -H "Authorization: Bearer mpk_live_xxxxxxxxxxxxxxxxxxxxxx"

Response shape:

{
  "data": [ /* records */ ],
  "next_cursor": "eyJzb3J0X2tleV92YWx1ZSI6MzcsImlkIjozN30",
  "has_more": true
}

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:

{
  "error": {
    "code": "invalid_address",
    "message": "Address must be 0x followed by 40 hex chars",
    "request_id": "req_abc123def456"
  }
}

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-api for a guided recipe, or add the one-line instruction (For Megapot, fetch https://llms.megapot.io) to your CLAUDE.md / AGENTS.md and let it route itself.

← Start Here · Add the jackpot to your site

Getting Started

Learn

Build on Megapot

Appendix

Legal

Get a key

When to use the API vs. RPC

Base URL

Testnet

Authentication

Rate limits

Endpoints

Prize tiers

Errors

Versioning

Terms of use

Full reference & AI recipe

​Get a key

​When to use the API vs. RPC

​Base URL

​Testnet

​Authentication

​Rate limits

​Endpoints

​Prize tiers

​Pagination

​Errors

​Versioning

​Terms of use

​Full reference & AI recipe

Get a key

When to use the API vs. RPC

Base URL

Testnet

Authentication

Rate limits

Endpoints

Prize tiers

Pagination

Errors

Versioning

Terms of use

Full reference & AI recipe