# EggoxDB API

Every mint in Eggox, as JSON anyone can read. No key, no account.

[EggoxDB](https://mints.eggox.net) is the official database of every
mint in Eggox: what it is, who made it, how many exist, how many
people hold one, whether its master is still alive. The same numbers
the game shows in a thing's Supply block. It has a JSON API, open to
everyone, so you can build on it: a price guide, a collection tracker,
a bot that says when something new is struck.

No key and no account. Plain `GET` requests, JSON back, CORS open to
any origin. Please keep to a request or two a second; a caller that
goes well past that gets `429` for a minute.

The API lives at `https://mints.eggox.net/api/mints` and, the same,
at `https://eggox.net/api/mints`. There are no kinds: a Voxel coin or
a competition prize is a mint by `Eggox`, found like any other.

## The list

    GET /api/mints?q=lantern&in=name&sort=editions&page=1&per_page=50

| Parameter | What it does |
| --- | --- |
| `q` | A word of the name. |
| `in` | Where `q` looks: `name` (the default), `author`, or `any`. |
| `author` | An author's name, exactly (case aside). `Eggox` is the Mint: the Voxel coins and the competition prizes. |
| `from`, `to` | Days (`YYYY-MM-DD`) the first edition was struck between, both ends included. |
| `master` | `alive` or `destroyed`. |
| `sort` | `first` (first struck, the default), `last`, `name`, `author`, `editions`, `holders`, `master`, `version`. |
| `dir` | `asc` or `desc`. Names go up and numbers and dates down unless told. |
| `page`, `per_page` | Paging; `per_page` is 50 by default and at most 100. |

The answer:

    {
      "mints": [ { ...a mint... } ],
      "page": 1, "per_page": 50, "pages": 3, "total": 121
    }

## One mint

    GET /api/mints/ln_9df3dabd223d525eb08fe440

    {
      "mint": {
        "lineage_id": "ln_9df3dabd223d525eb08fe440",
        "name": "Harbour lantern",
        "creator": { "name": "Nadia", "url": "https://mints.eggox.net/?author=Nadia" },
        "editions": 25,
        "holders": 9,
        "master_alive": true,
        "version": 2,
        "first_minted_at": "2026-10-02T14:11:08Z",
        "last_minted_at": "2026-10-02T14:11:08Z",
        "content_hash": "3f1c…",
        "picture": "https://mints.eggox.net/pictures/3f1c….png",
        "url": "https://mints.eggox.net/m/ln_9df3dabd223d525eb08fe440",
        "coin_value": null,
        "award": null
      }
    }

Field by field:

- `lineage_id`: the mint's lineage, the id to keep. It never changes,
  whatever version an edition wears.
- `creator`: whoever holds the master, as the game shows it; `null`
  once a player has destroyed their master (the game no longer knows
  either). Eggox's own mints say `Eggox`.
- `editions`: how many exist, summed across every holder. `holders`:
  how many people hold at least one.
- `master_alive`: `false` means the supply is final: no more will ever
  be made.
- `content_hash`: the SHA-256 of the mint's bytes, the same
  certificate the game shows. `picture` is drawn from those bytes.
- `coin_value`: for a Voxel coin, its face value in Voxels; otherwise
  `null`.
- `award`: for a competition prize, the engraving: the competition,
  the place, the entry, the stars, the day; otherwise `null`.

Unknown id: `404` with `{"reason": "not_found"}`.

## The numbers

    GET /api/mints/stats

    {
      "lineages": 312, "editions": 48210, "holders": 1203,
      "voxels": { "total": 182350, "wallets": 171900, "coins": 10450 },
      "coins": [
        { "value": 1, "name": "Voxel Bit", "count": 950, "voxels": 950 },
        { "value": 50, "name": "Voxel Egg", "count": 190, "voxels": 9500 }
      ]
    }

`voxels.total` is every Voxel in existence: what sits in wallets plus
the face value of every coin out there.

## Pictures

`GET /pictures/<content_hash>.png` is the mint drawn by the game's own
renderer, cut to the thing itself and centred on a transparent square,
kept forever under that hash. Use the `picture` field as it is: its
`?v=` changes when the pictures do, so a cache never holds an old one.
Hot-link it freely. The renderer draws one at a time, so a picture
asked for the first time can take a moment.