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.

Already integrated with our smart contracts? Use the API for off-chain reads (round history, wallet lifetime stats, leaderboards) and keep the RPC path for live state and writes.

---

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)	RPC (read-state recipe)
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 dashboard to create an API key.

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/support.

---

Base URL

https://api.megapot.io/v1

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

---

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"

Key format: mpk_live_<22 base62 chars>. Treat keys like passwords — store them somewhere safe. Lost a key? Visit your megapot.io dashboard 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-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

If your use case warrants higher limits, reach out at megapot.io/support.

---

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 reference.

---

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. 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 4xx (except 429). Quote request_id when reporting any non-2xx.

---

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.

---

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.

---

Building with an AI coding assistant?

A dedicated Megapot Data API skill is available alongside the on-chain skills at llms.megapot.io. 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/docs.