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

{% hint style="success" %}
**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.
{% endhint %}

***

## 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](https://llms.megapot.io/tasks/read-state)) |
| Settlement transitions, ticket-purchase events                  | RPC event subscriptions                                             |
| Any write transaction (buy, claim, deposit, subscribe)          | RPC ([buy-tickets](/developers/buy-tickets.md), etc.)               |

The API is read-only. For writes, see [Add Megapot to Your Site](/developers/buy-tickets.md).

***

## Get a key

Visit your [megapot.io dashboard](https://megapot.io/dashboard) to create an API key.

{% hint style="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.
{% endhint %}

Need help? Reach out at [megapot.io/support](https://megapot.io/support).

***

## Base URL

```
https://api.megapot.io/v1
```

The interactive reference (Scalar UI with try-it-out) is at [`/v1/docs`](https://api.megapot.io/v1/docs); the OpenAPI 3.x spec is at [`/v1/openapi.json`](https://api.megapot.io/v1/openapi.json).

***

## Authentication

Send your key in the `Authorization` header on every request:

```bash
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](https://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](https://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](https://api.megapot.io/v1/docs).

***

## Errors

Every non-2xx response uses the same envelope:

```json
{
  "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](https://api.megapot.io/v1/docs).

**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:

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

Response shape:

```json
{
  "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](https://api.megapot.io/tos).

***

## Building with an AI coding assistant?

A dedicated [Megapot Data API skill](https://llms.megapot.io/data-api) is available alongside the on-chain skills at [llms.megapot.io](https://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](/developers/ai-agent-skills.md) 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`](https://api.megapot.io/v1/docs).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.megapot.io/developers/data-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.