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)

500

Authenticated (with key)

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

PreviousProtocol Reference

NextGet Listed

Last updated 9 days ago