# Stats and supply

Three summary endpoints. /api/stats is the chain head and the ledger's running totals, /api/supply is the allocation and what each protocol account has paid out, and /api/token is everything the token page shows.

## GET /api/stats {#stats}

```endpoint try
GET /api/stats
```

The chain, its newest block, the ledger's running totals, how much MLX Macs have mined, the live spot spread and what the spot market can pay sellers right now. Not cached (`no-store`).

```bash tab=curl
curl https://mlx.app/api/stats
```

```js tab=JavaScript
const s = await (await fetch("https://mlx.app/api/stats")).json();
const mined = BigInt(s.mined.paid); // base units
console.log(`block ${s.head.height}, ${Number(mined) / 1e6} MLX mined`);
```

```python tab=Python
import requests

s = requests.get("https://mlx.app/api/stats").json()
print(s["head"]["height"], int(s["mined"]["paid"]) / 10**6, "MLX mined")
```

No parameters.

```json title="Response"
{
  "chain": "mlx-1",
  "network": "genesis",
  "storage": "redis",
  "sequencer": "92114fe09a90d1a3aced63f35463e4120969d1b323c41070a9ee3ca3cf6ae9a3",
  "head": {
    "height": 397,
    "hash": "ef5f250abbe3aa7f14767ea19ce5b1b67525fff8a8c039f0e72d5a7d33d04601",
    "ts": 1793113786120
  },
  "stats": {
    "accounts": 61,
    "nodes": 12,
    "tiers": { "S": 2, "M": 1, "L": 0, "SX": 2, "MX": 0, "LX": 0, "N": 6, "T": 1 },
    "devices": { "iphone": 0, "ipad": 0, "mac": 12, "other": 0 },
    "chips": { "M6": 2, "M5": 2, "M4 Pro": 1, "M4": 6, "M1": 1 },
    "countries": { "SE": 3, "SG": 2, "CH": 4, "JP": 1, "TR": 1, "MY": 1 },
    "txs": 398,
    "emitted": "0",
    "referralPaid": "0",
    "raisedUSDC": "2650180696",
    "units": 27.020000000000003,
    "deposited": "1260277511",
    "swapped": "4159614206",
    "updated": 1793113786120,
    "adjustedIn": "11000000000",
    "spotBuyUsd": "52000000",
    "withdrawRequested": "1000000000",
    "withdrawPaid": "1000000000"
  },
  "mined": {
    "allocated": "3500000000000000",
    "remaining": "3499999508244581",
    "paid": "491755419"
  },
  "pool": null,
  "market": { "buyPremium": 0.25, "sellDiscount": 0.2 },
  "liquidity": { "usd": "1677000000", "mlx": "1499995840385794" }
}
```

| Field | Type | Notes |
| --- | --- | --- |
| `chain` | string | Chain id, `mlx-1` on production. Part of every signed transaction and block hash. |
| `network` | string | `genesis` on the public chain. |
| `storage` | string | `redis` in production; `memory` on a local development server. |
| `sequencer` | string | The sequencer's Ed25519 public key (hex). Every block is signed with it: see [Blocks](/network/blocks#verify). |
| `head` | object | The newest block: `height`, `hash`, `ts`. |
| `stats.accounts` | number | Wallets created. |
| `stats.nodes` | number | Dedicated seats sold or granted. |
| `stats.tiers` | object | Seats per tier id (`N` Nano, `T` Lite, `S` Core, `M` Pro, `L` Ultra; `SX`, `MX`, `LX` the newest-chip editions). See [Seats](/protocol/seats). |
| `stats.devices`, `stats.chips`, `stats.countries` | object | Seats by the device, chip and country recorded when each was bought. |
| `stats.txs` | number | Transactions sealed, the genesis transaction included. |
| `stats.emitted` | string | MLX paid to seats up front, base units. Seats now mine instead and get nothing up front, so this no longer grows. Mined MLX is `mined`. |
| `stats.referralPaid` | string | MLX paid as referral bonuses, base units. |
| `stats.raisedUSDC` | string | Dollars paid for seats, base units. |
| `stats.units` | number | The network's position on the curve, in seat units. See [Curve](/protocol/curve). |
| `stats.deposited` | string | Dollars deposited and credited as USDC, base units. |
| `stats.swapped` | string | MLX bought on the spot market, base units. |
| `stats.sold` | string | MLX sold back to the spot market, base units. Absent until the first sale. |
| `stats.spotBuyUsd`, `stats.spotSellUsd` | string | Dollars spent buying and paid out for selling on the spot market, base units. |
| `stats.commissionPaid` | string | USDC paid to distributors, base units. |
| `stats.adjustedIn`, `stats.adjustedOut` | string | USDC credited and debited by operator balance adjustments (the public `adjust` transaction), base units. |
| `stats.withdrawRequested`, `stats.withdrawPaid` | string | USDC asked for and paid out by withdrawals, base units. |
| `stats.updated` | number | Time of the block that last changed the totals. |
| `mined` | object | The compute pool (`compute.mlx`): `allocated`, `remaining` and `paid` (allocated less remaining), base units. This is all the MLX Macs have mined. Itemised at [`/api/compute`](/network/compute). |
| `pool` | object or null | Balances of `pool.mlx`; `null` when that account doesn't exist. |
| `market` | object | The live spot spread, as fractions: `buyPremium` on buys, `sellDiscount` on sells. The code defaults are 3% and 20%; this field is what applies now. |
| `liquidity` | object | What `treasury.mlx` holds, base units: `usd` (USDC) is what sells can be paid from, `mlx` is what buys are filled from. |

The `stats` fields marked optional in the ledger (`sold`, `spotBuyUsd`, `spotSellUsd`, `commissionPaid`, `adjustedIn`, `adjustedOut`, `withdrawRequested`, `withdrawPaid`) appear once the first transaction of that kind is sealed.

## GET /api/supply {#supply}

```endpoint try
GET /api/supply
```

The fixed supply, how it was allocated at genesis, how much each allocation has paid out, and the protocol accounts themselves. Not cached.

No parameters.

```json title="Response"
{
  "total": 10000000000,
  "allocation": [
    {
      "account": "compute.mlx",
      "label": "Compute rewards",
      "share": 0.35,
      "note": "Earned by Macs for verified AI work, hour by hour. Each day's rewards unlock 30 days later on a free seat, or after the seat's lock-in (3 to 20 days) with a dedicated seat."
    }
  ],
  "paid": [
    {
      "account": "compute.mlx",
      "allocated": "3500000000000000",
      "movedIn": "0",
      "movedOut": "0",
      "moves": [],
      "holds": "3499999508244581",
      "locked": "0",
      "paidOut": "491755419",
      "remaining": "3499999508244581",
      "paid": "491755419"
    }
  ],
  "system": [
    {
      "name": "compute.mlx",
      "pk": null,
      "nonce": 0,
      "bal": { "MLX": "3499999508244581", "USDT": "0", "USDC": "0" },
      "created": 1792312766202,
      "createdHeight": 0,
      "nodes": [],
      "earned": "0",
      "referrals": 0,
      "system": true
    }
  ],
  "stats": { "accounts": 61, "nodes": 12, "txs": 398 }
}
```

Each array is trimmed to one entry here, and `stats` to three fields; the live response lists every allocation and protocol account, and the full `stats` object from `/api/stats`.

| Field | Type | Notes |
| --- | --- | --- |
| `total` | number | Total supply in **whole MLX** (10,000,000,000), not base units. |
| `allocation` | array | The genesis split: `account`, `label`, `share` (a fraction of `total`) and a plain-language `note`. The table is on [Parameters](/protocol/parameters). |
| `paid` | array | Per allocation, base units: `allocated` at genesis; `movedIn` and `movedOut`, MLX moved between protocol accounts, with each move in `moves` (`from`, `to`, `amount`, `at`, `tx`; so far only the seat reserve's move to `treasury.mlx` on 29 Oct 2026); `holds`, what the account holds now, locks included (`team.mlx` vests in locks), with `locked` the part still locked and `nextUnlock` when the next lock opens; and `paidOut`, what it has paid out to people, net: `allocated + movedIn − movedOut − holds` (for `treasury.mlx`, MLX sold on spot less MLX sold back). `remaining` and `paid` repeat `holds` and `paidOut`. |
| `system` | array | The protocol accounts in full (the allocation accounts plus `pool.mlx`, `faucet.mlx`, `bridge.mlx` and `withdrawals.mlx` where they exist), in the account format of [Accounts](/network/accounts#account-fields). `bridge.mlx` also carries `issued`: USDC issued for deposits and liquidity, base units. |
| `stats` | object | The same totals as `/api/stats`. |

## GET /api/token {#token}

```endpoint try
GET /api/token
```

Everything the token page on mlx.app shows, computed from the live ledger: price, spread, supply, holders, the next halving, history and recent buys and sells. Cached by the CDN for a few seconds, and in the server for a few more, so two calls close together can return the same `at`.

> [!NOTE]
> Unlike the rest of the API, `/api/token` gives amounts as **numbers in whole MLX and whole dollars**, not base-unit strings. Use it for display; use `/api/stats` and `/api/supply` for exact figures.

No parameters.

```json title="Response"
{
  "chain": "mlx-1",
  "at": 1793116774568,
  "position": 27.020000000000003,
  "price": 0.01000093648568847,
  "buyPrice": 0.012501170607110588,
  "sellPrice": 0.008000749188550777,
  "market": { "buyPremium": 0.25, "sellDiscount": 0.2 },
  "change": { "d1": 3.465735964880423e-8, "d7": 0.00008065092656917017, "d30": null },
  "marketCap": 46.5180521910856,
  "fdv": 100009364.8568847,
  "volume": { "d1": 1, "d7": 52, "all": 52 },
  "supply": {
    "total": 10000000000,
    "circulating": 4651.369625,
    "unlocked": 4159.614206,
    "locked": 491.7554189999999,
    "protocol": [
      { "account": "compute.mlx", "label": "Compute rewards", "share": 0.35, "allocated": 3500000000, "remaining": 3499999508.244581 }
    ]
  },
  "paidToNodes": 0,
  "paidToMacs": 491.7554187774658,
  "referralPaid": 0,
  "nodes": 12,
  "tiers": { "S": 2, "M": 1, "L": 0, "SX": 2, "MX": 0, "LX": 0, "N": 6, "T": 1 },
  "holders": {
    "count": 39,
    "top": [{ "name": "luca.mlx", "mlx": 98.999505, "locked": 98.999505 }]
  },
  "liquidity": { "usd": 1677, "mlx": 1499995840.385794 },
  "halving": {
    "epoch": 0,
    "nextAt": 200000,
    "usdToNext": 19997298,
    "progress": 0.0001351,
    "priceNext": 0.02,
    "rewardNow": 24997.55071132855,
    "rewardNext": 12499.945847986279
  },
  "ath": { "price": 0.01000093648568847, "at": 1793102873526 },
  "atl": { "price": 0.01, "at": 1792312766202 },
  "range": { "d1": [0.01000093613908243, 0.01000093648568847], "d7": [0.010000129965940905, 0.01000093648568847] },
  "since": 1792312766202,
  "ticks": [
    { "t": 1792312766202, "u": 0, "n": 0, "e": 0, "v": 0 },
    { "t": 1792510129015, "u": 3.75, "n": 1, "e": 37499.756316, "v": 0 }
  ],
  "activity": [
    {
      "hash": "a7ebe211a3e39fb634f1b5ff313d9a54e53520bd6d3237f42be39f4f631d4137",
      "t": 1793102872897,
      "kind": "buy",
      "who": "luca.mlx",
      "mlx": 79.99251,
      "usd": 1,
      "note": "Bought on the curve"
    }
  ]
}
```

`supply.protocol`, `holders.top`, `ticks` and `activity` are trimmed to one or two entries here.

| Field | Type | Notes |
| --- | --- | --- |
| `position` | number | The network's place on the curve, in seat units (same as `stats.units`). |
| `price` | number | The curve price, dollars per MLX. |
| `buyPrice`, `sellPrice` | number | `price` with the live buy premium and sell discount applied. A real fill also moves along the curve: ask [`/api/market/quote`](/network/market#quote) for an exact figure. |
| `change` | object | Price change over 1, 7 and 30 days as a fraction; `null` when the chain is younger than the period. |
| `marketCap` | number | Circulating MLX × `price`, dollars. |
| `fdv` | number | Total supply × `price`, dollars. |
| `volume` | object | Spot buys plus sells in dollars over the last day, the last 7 days and all time. |
| `supply.circulating` | number | MLX outside the protocol accounts, locked or not. |
| `supply.unlocked`, `supply.locked` | number | `circulating` split by whether it can be spent today. |
| `supply.protocol` | array | Per allocation account: `allocated` and `remaining`, whole MLX. |
| `paidToNodes` | number | MLX paid to seats up front (the old model; see `stats.emitted`). |
| `paidToMacs` | number | MLX mined by Macs: what `compute.mlx` has paid out. |
| `holders` | object | `count` of wallets holding any MLX and the `top` holders by MLX held (`mlx` includes `locked`). |
| `liquidity` | object | `treasury.mlx`'s USDC and MLX, whole units. |
| `halving` | object | Current `epoch`, the position of the next halving (`nextAt`), dollars of seat purchases still to go (`usdToNext`), `progress` through the epoch as a fraction and the curve price there (`priceNext`). `rewardNow` and `rewardNext` are the up-front MLX a Core seat was granted under the old model, at today's position and at the next halving; seats bought today are granted nothing up front. |
| `ath`, `atl` | object | Highest and lowest curve price reached, with the time. |
| `range` | object | Lowest and highest price over the last day and 7 days, `[low, high]`. |
| `since` | number | Time of the genesis block. |
| `ticks` | array | Price history: one point per block that moved the curve. `t` time, `u` position, `n` seats, `e` MLX paid to seats up front (cumulative), `v` spot volume in dollars (cumulative). |
| `activity` | array | The newest buys, sells and seat purchases from the recent transactions. `kind` is `buy`, `sell` or `node`; seat rows also carry `tier`, `node` (the seat id) and `granted`. |

## Errors

| Status | When |
| --- | --- |
| 500 | The ledger couldn't be read. `/api/token` cuts the message to a short line. |

All three endpoints take no input, so they have no 400 or 404.