> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/user-performance/walletlabels.md).

# walletLabels (experimental)

Every labelled Hyperliquid wallet with its trader tag and market-maker / delta-neutral / new-wallet flags, as one gzip download. Experimental add-on.

{% hint style="warning" %}
**Experimental add-on.** This endpoint needs the `wallet-labels` add-on on your API key; without it the call returns `403`. The response shape may change while the endpoint is experimental.
{% endhint %}

Returns the full wallet label list (about 250k wallets) in a single response. The list is refreshed hourly, so polling more often returns the same data. The response header `x-fetched-at-ms` tells you when the current copy was fetched.

The body is always **gzip-compressed** (`Content-Encoding: gzip`, about 6 MB on the wire, about 36 MB decoded). Python `requests`/`httpx`, JavaScript `fetch`, and Rust `reqwest` decompress it automatically. With cURL, pass `--compressed`.

**Rate limit:** 10 requests per 10 minutes per API key, separate from your per-minute points budget.

## POST Request

<table><thead><tr><th width="180">Field</th><th width="105">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"walletLabels"</code></td></tr></tbody></table>

{% tabs %}
{% tab title="cURL" %}

```bash
curl --compressed -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "walletLabels"}' \
  -o wallet_labels.json
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

response = requests.post(
    "https://api.hydromancer.xyz/info",
    headers={"Authorization": f"Bearer {os.environ['HYDROMANCER_API_KEY']}"},
    json={"type": "walletLabels"},
)
response.raise_for_status()
wallets = response.json()  # requests decompresses gzip automatically
print(len(wallets), response.headers["x-fetched-at-ms"])
```

{% endtab %}
{% endtabs %}

## Response

A JSON array with one object per wallet, sorted by address.

<table><thead><tr><th width="180">Field</th><th width="105">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>address</code></td><td>string</td><td>Wallet address, lowercase <code>0x</code>-prefixed hex</td></tr><tr><td><code>name</code></td><td>string | null</td><td>Known name for the wallet, if any</td></tr><tr><td><code>tag</code></td><td>string</td><td>Trader classification, for example <code>"New wallet"</code>, <code>"+ day"</code>, <code>"- swing"</code>, <code>"+ intraday"</code>, <code>"- scalper"</code></td></tr><tr><td><code>marketMaker</code></td><td>bool</td><td>Wallet is classified as a market maker</td></tr><tr><td><code>deltaNeutral</code></td><td>bool</td><td>Wallet is classified as delta-neutral</td></tr><tr><td><code>newWallet</code></td><td>bool</td><td>Wallet is classified as new</td></tr></tbody></table>

```json
[
  {
    "address": "0x000000000000000000000000000000000000dead",
    "name": "Burn Address 2",
    "tag": "New wallet",
    "marketMaker": false,
    "deltaNeutral": false,
    "newWallet": true
  },
  {
    "address": "0x0000000000005ef5a16bd687b9b9c41b498435db",
    "name": null,
    "tag": "+ day",
    "marketMaker": false,
    "deltaNeutral": false,
    "newWallet": false
  }
]
```

## Errors

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| `403`  | Your API key does not have the `wallet-labels` add-on.               |
| `429`  | More than 10 requests in 10 minutes.                                 |
| `503`  | The list has not loaded yet after a restart. Retry in a few minutes. |
