> For the complete documentation index, see [llms.txt](https://docs.megapot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.megapot.io/build-on-megapot/pull-data.md).

# 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](/build-on-megapot/add-to-your-site.md).

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

***

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

1. Go to your [megapot.io dashboard](https://megapot.io/dashboard), then **Profile → API keys**.
2. Create a key. The format is `mpk_live_` followed by 22 base62 characters.
3. **Copy it immediately.** The full key is shown once, at creation time, and never again.

{% hint style="warning" %}
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.
{% 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 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](/build-on-megapot/add-to-your-site.md) |

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.

{% hint style="info" %}
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](/build-on-megapot/add-to-your-site.md) for how it works.
{% endhint %}

***

## Base URL

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

The interactive reference (try-it-out) is at [`/v1/docs`](https://api.megapot.io/v1/docs); the OpenAPI spec is at [`/v1/openapi.json`](https://api.megapot.io/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`](https://api.megapot.io/v1/docs)         | `mpk_live_`    |
| Testnet     | `https://api-testnet.megapot.io/v1` | [`/v1/docs`](https://api-testnet.megapot.io/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](#rate-limits) 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](https://megapot.io/support).

***

## 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"
```

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

***

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

***

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

***

## Full reference & AI recipe

* **Interactive reference**: try-it-out, full request/response schemas, every error code: [`https://api.megapot.io/v1/docs`](https://api.megapot.io/v1/docs).
* **Building with an AI assistant?** Point it at [`llms.megapot.io/data-api`](https://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](/build-on-megapot/start-here.md) · [Add the jackpot to your site](/build-on-megapot/add-to-your-site.md)