# Accounts

Every wallet and protocol account with its public balances, one account in full with its locks, linked Macs and history, live mining for a wallet, and lookups by name, key or anything the explorer's search box takes.

## GET /api/accounts {#list}

```endpoint try
GET /api/accounts?kind=holders&sort=mlx&limit=2
```

Accounts as slim rows, filtered and sorted, with the same public balances each account page shows. Protocol accounts are included and marked `system`.

```bash tab=curl
curl "https://mlx.app/api/accounts?kind=holders&sort=mlx&limit=10"
```

```js tab=JavaScript
const url = new URL("https://mlx.app/api/accounts");
url.search = new URLSearchParams({ kind: "holders", sort: "mlx", limit: "10" });
const { accounts, next } = await (await fetch(url)).json();
for (const a of accounts) console.log(a.name, Number(BigInt(a.mlx)) / 1e6, "MLX");
```

```python tab=Python
import requests

d = requests.get("https://mlx.app/api/accounts", params={"kind": "holders", "sort": "mlx", "limit": 10}).json()
for a in d["accounts"]:
    print(a["name"], int(a["mlx"]) / 10**6, "MLX")
```

| Parameter | Type | Notes |
| --- | --- | --- |
| `q` | string | Only names containing this text. |
| `kind` | `all`, `holders`, `nodes`, `referrers`, `system` or `suspicious` | All accounts (default); wallets holding MLX; wallets holding a dedicated seat; wallets that referred someone; protocol accounts only; [suspicious wallets](#suspicious). |
| `sort` | `new`, `old`, `mlx`, `usdc`, `nodes`, `earned`, `referrals` or `name` | Newest first (default), oldest first, most MLX, most dollars, most seats, most earned, most referrals, or by name. Ties are broken by name. |
| `offset` | integer | Rows to skip. Pass the previous page's `next`. |
| `limit` | integer | Page size. The route has a default and a maximum. |

```json title="Response"
{
  "total": 62,
  "indexed": 62,
  "system": 7,
  "matched": 1,
  "offset": 0,
  "accounts": [
    {
      "name": "luca.mlx",
      "system": false,
      "created": 1792312855563,
      "createdHeight": 1,
      "mlx": "99763394",
      "locked": "99763394",
      "usdc": "0",
      "nodes": 1,
      "earned": "0",
      "referrals": 0
    }
  ],
  "next": null
}
```

| Field | Type | Notes |
| --- | --- | --- |
| `total` | integer | Wallets on the ledger. |
| `indexed` | integer | Wallets in the list this endpoint reads (normally equal to `total`). |
| `system` | integer | Protocol accounts in the list. |
| `matched` | integer | Rows that pass the filter. |
| `next` | integer or null | The `offset` of the next page. |
| `accounts[].mlx` | string | All MLX the account holds, spendable and locked, base units. |
| `accounts[].locked` | string | The part of `mlx` still locked now. |
| `accounts[].usdc` | string | USDC plus any legacy USDT, base units. |
| `accounts[].nodes` | integer | Dedicated seats held. |
| `accounts[].earned` | string | MLX earned from up-front seat rewards and referrals (the old model), base units. Mined MLX isn't counted here; see `locks` on the account. |
| `accounts[].referrer` | string | Who referred the wallet, when someone did. |
| `accounts[].flags` | array | With `kind=suspicious`: `{ id, strong, label }` for each [flag](#suspicious). Flagged wallets are left out of every other `kind`. |
| `suspicious` | integer | Wallets flagged right now. |

The list is cached for a few seconds on the server, so a wallet created a moment ago can take a little while to appear.

## GET /api/account/{name} {#account}

```endpoint try
GET /api/account/treasury.mlx
```

One account in full. Add `txs` for its history and `nodes` for its seats. Not cached.

| Parameter | Type | Notes |
| --- | --- | --- |
| `name` | string (path) | The full name with `.mlx` (`luca.mlx`). Not case-sensitive. |
| `txs` | integer | Include the account's newest transactions, this many. The route caps it. |
| `offset` | integer | With `txs`: skip this many of the newest, to page back. |
| `nodes` | any non-empty value | Include the account's seat records, newest first (the newest ones only, for an account with very many). |
| `flags` | any non-empty value | Include `flags`: why the wallet is listed as [suspicious](#suspicious) (`{ id, strong, label, detail }`), or `[]`. |

```json title="Response (GET /api/account/luca.mlx?txs=1&nodes=1), locks trimmed to two"
{
  "account": {
    "name": "luca.mlx",
    "pk": "53fbe3a2e4ee9ee2ad907174562e8f2fc9b2bb3e1074f8ce274935439422c4ab",
    "nonce": 7,
    "bal": { "MLX": "0", "USDT": "0", "USDC": "0" },
    "created": 1792312855563,
    "createdHeight": 1,
    "nodes": [2],
    "earned": "0",
    "referrals": 0,
    "devices": [
      {
        "pk": "02f9b1f9aec77a141ae279d386cc1cd8f9c940b3102329b27af9ae5c018cfd185d",
        "name": "MacBook Pro",
        "chip": "M5",
        "memoryGB": 16,
        "os": "macOS 26.6.2",
        "at": 1792314044695,
        "height": 2
      }
    ],
    "locks": [
      { "amount": "19999992", "until": 1793404800000, "node": 0, "kind": "compute", "from": 1792540800000 },
      { "amount": "1055555", "until": 1793923200000, "node": 0, "kind": "compute", "from": 1793059200000 }
    ]
  },
  "txs": [
    {
      "hash": "2069d74fed709fd06538433002fa7e331c389f753709a62affc2179be2bf608d",
      "tx": {
        "body": { "amount": "5000000", "to": "review.mlx", "token": "USDC", "type": "transfer" },
        "chain": "mlx-1",
        "from": "luca.mlx",
        "nonce": 7,
        "pk": "53fbe3a2e4ee9ee2ad907174562e8f2fc9b2bb3e1074f8ce274935439422c4ab",
        "sig": "8c806f69381a9d190528ba2a15e42d6feadf0b184e4b77769fcb1c6413444d28be7196ab1bef8195bc16d904b030bb173dbcf24c8e1d2ed2b214564b28033e04",
        "ts": 1793018575027
      },
      "status": "success",
      "receivedAt": 1793018575432,
      "effects": [{ "kind": "transfer", "token": "USDC", "from": "luca.mlx", "to": "review.mlx", "amount": "5000000" }],
      "height": 347,
      "index": 0
    }
  ],
  "nodes": [
    {
      "id": 2,
      "owner": "luca.mlx",
      "tier": "S",
      "reward": "0",
      "base": 24999.566786837695,
      "position": 3.75,
      "device": { "class": "mac", "chip": "M5", "appleSilicon": true, "cores": 8, "screen": "1800x1169@2", "model": "MacBook" },
      "country": "SE",
      "height": 80,
      "tx": "e74fb256b0faa50d1863fa8064e49540f74543c56a9c5d0aecec88cda6eacae7",
      "ts": 1792519094698,
      "status": "pledged",
      "unlockAt": 1793383094698
    }
  ]
}
```

### Account fields {#account-fields}

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | The wallet name. |
| `pk` | string or null | The wallet's Ed25519 public key (its Public Wallet address), hex. `null` for protocol accounts, which only the sequencer moves. |
| `nonce` | integer | The nonce of its last successful transaction (`0` after `create_account`). Its next transaction signs `nonce + 1`; see [Submitting](/transactions/submitting). |
| `bal` | object | Spendable balances per token, base units. Locked MLX is **not** in `bal.MLX`; it is in `locks`. A token the account never held can be missing. |
| `created`, `createdHeight` | integer | When and in which block the account was created. |
| `referrer` | string | Who referred it, if anyone. |
| `nodes` | integer[] | Ids of the dedicated seats it holds. |
| `earned` | string | MLX from up-front seat rewards and referrals (the old model), base units. |
| `referrals` | integer | Wallets it referred. |
| `system` | `true` | On protocol accounts. |
| `locks` | array | Locked MLX: `amount` (base units), `until` (unlock time, ms), `kind` (`compute` for mined MLX, `node` or `referral` for old up-front rewards, `swap`), `node` (the seat id, `0` when none) and, on mined MLX, `from` (the UTC day it was mined). Mined MLX is one lock per day. See [Lock-ins](/protocol/lock-ins). |
| `devices` | array | Linked Macs: `pk` (the Mac's own key), `name` (**the kind of Mac**, never its own name), `chip`, `memoryGB`, `os`, `at` (when linked, ms) and `height` (the block it was linked in). |
| `issued` | string | `bridge.mlx` only: USDC issued for deposits and liquidity, base units. |

A lock whose `until` has passed stays listed until the account's next transaction folds it into `bal.MLX`; it is spendable from its `until`. To get what is locked right now, add up the locks with `until` in the future, or read `locked` from the [mining endpoint](#mining).

The history in `txs` is the ledger's per-account list, which keeps only the newest transactions. Hourly compute rewards aren't added to it (there would be one an hour); mined MLX shows in `locks`, in [`/api/compute`](/network/compute) and in live mining.

## GET /api/account/{name}/mining {#mining}

```endpoint try
GET /api/account/treasury.mlx/mining
```

Live mining for one wallet: MLX earned in hours not yet paid, how fast it is growing, and the locked MLX read at the same moment. This is what the MLX Wallet counts up from. Not cached; poll it.

| Parameter | Type | Notes |
| --- | --- | --- |
| `name` | string (path) | The full wallet name. |

```json title="Response (GET /api/account/luca.mlx/mining)"
{
  "at": 1793116884577,
  "locked": "98999505",
  "pending": "791666",
  "rate": 0.00023147916666666667,
  "active": true,
  "macs": 1,
  "state": "mining",
  "kinds": {
    "02f9b1f9aec77a141ae279d386cc1cd8f9c940b3102329b27af9ae5c018cfd185d": "macbook-pro"
  },
  "models": {
    "02f9b1f9aec77a141ae279d386cc1cd8f9c940b3102329b27af9ae5c018cfd185d": { "name": "MacBook Pro 14-inch", "art": "macbook-pro" }
  }
}
```

| Field | Type | Notes |
| --- | --- | --- |
| `at` | integer | When it was read, ms. |
| `locked` | string | MLX locked right now (every lock with `until` in the future), base units. |
| `pending` | string | MLX earned in the running hour (and an hour that just ended but isn't settled yet), base units. It moves into `locked` when the hour is paid. |
| `rate` | number | Growth of `pending` in **whole MLX per second**, while a Mac is working. `0` when nothing is. |
| `active` | boolean | A linked Mac is working or ready now and the hour has earned something. |
| `macs` | integer | Linked Macs that count as mining right now. |
| `state` | string | `mining`, `paused` (the online Macs are paused or stopped), `waiting` (online but not eligible) or `idle` (no Mac online, or none linked). |
| `kinds` | object | Per linked Mac's key: what kind of Mac it is (`macbook-pro`, `mac-mini`…), when known. |
| `models` | object | Per linked Mac's key: the model (`name`) and the drawing used for it (`art`, a file under `mlx.app/macs/<art>.svg`), when known. |

To show a live number, add `rate × (now − at) / 1000` to `pending` between polls. The rewards themselves are explained on [Rewards](/protocol/rewards).

## GET /api/name/{name} {#name}

```endpoint try
GET /api/name/luca
```

Whether a wallet name can be registered. `.mlx` is added when missing, and the name is lower-cased.

| Parameter | Type | Notes |
| --- | --- | --- |
| `name` | string (path) | With or without `.mlx`. |

```json title="Response"
{ "name": "treasury.mlx", "available": false, "reason": "That name is reserved." }
```

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | The name as it would be registered. |
| `available` | boolean | Free to take right now. Nothing is held for you: the first `create_account` to be sealed wins. |
| `reason` | string or null | Why not: a rule it breaks (length, characters, reserved names and look-alikes of protocol names) or `"<name> is taken"`. |

## GET /api/key/{pk} {#key}

```endpoint try
GET /api/key/53fbe3a2e4ee9ee2ad907174562e8f2fc9b2bb3e1074f8ce274935439422c4ab
```

The account behind a Public Wallet key (the wallet's Ed25519 public key, 64 hex characters). Returns `{ "account": … }` in the format above, with Macs by kind.

| Parameter | Type | Notes |
| --- | --- | --- |
| `pk` | string (path) | Hex, any case. |

## GET /api/search {#search}

```endpoint try
GET /api/search?q=%232
```

Resolves what someone typed into the explorer's search box to a page on explorer.mlx.app.

| Parameter | Type | Notes |
| --- | --- | --- |
| `q` | string | `#12` (a seat), `12` (a block height, else a seat id), a 64-hex hash (a transaction, else a wallet key) or a wallet name with or without `.mlx`. |

```json title="Response"
{ "to": "/node/2" }
```

`to` is a path on explorer.mlx.app (`/block/<height>`, `/node/<id>`, `/tx/<hash>`, `/account/<name>`), or `null` when nothing matched.

## Errors

| Status | When |
| --- | --- |
| 404 | `/api/account/{name}` and `/mining`: `"Account not found"`. `/api/key/{pk}`: `"No account uses this key"`. |
| 500 | The ledger couldn't be read. |

`/api/name` and `/api/search` always answer 200: an invalid name comes back with `available: false` and its `reason`, and no match is `{ "to": null }`.

## Suspicious accounts {#suspicious}

explorer.mlx.app/accounts → **Suspicious accounts** lists wallets whose behaviour looks automated or abusive. Each flag says what was seen; none is a verdict about who runs the wallet. A wallet is listed with one strong flag or two weak ones, recomputed every few minutes.

| Flag (`id`) | Strong | When |
| --- | --- | --- |
| `probing` | 2 or more | Transactions sealed as failed with errors no wallet or app produces (unknown type, malformed amount, unknown token). One is a weak flag. |
| `door` | 3 or more | Signed transactions refused at `POST /api/tx` as malformed. Fewer are weak. |
| `failures` / `failing` | 10 or more failed | Many failed transactions (strong); 3 or more failed and more failed than successful (weak). |
| `lookalike` | yes | The name has a staff word as one of its parts (`official-…`, `…-support`). New names like this can't be registered. |
| `machine` | no | A random hex tail (`…-3f3fa1`), as scripts name wallets. |
| `burst` | yes | A machine-made name, opened within 15 minutes of 3 or more wallets flagged on their own. |
| `network` | no | Opened from one network with 4 or more other wallets within an hour (the network is kept only as a one-way hash, for 30 days). |
| `referred` | no | Referred by a listed wallet. |
| `mac-exec` | yes | A linked Mac failed most of its [execution checks](/protocol/jobs#execution-checks) (2 or more failed). |
| `mac-chip` | yes | A linked Mac reports a chip its model identifier never shipped with ([chip checks](/protocol/jobs#chip-checks)). |
| `mac-hops` | no | A linked Mac was linked to 3 or more different wallets in 30 days ([Fair use](/resources/fair-use)). |
| `mac-keys` | no | The same Mac (by its [hardware ID](/resources/fair-use#hardware)) used 4 or more device keys in 30 days. |
| `mac-hwid` | 2 or more | A linked Mac's device key reported a different hardware ID than its first. One is a weak flag. |
| `mac-speed`, `mac-answers` | no | A linked Mac far slower than its chip, or whose answers mostly disagree with its GPU group's. |
| `manual` | yes | Flagged by MLX Network after a review, with the reason. MLX Network can also clear a wallet the rules flag by mistake. |

Write to support@mlx.app if you think a wallet is listed by mistake.