API reference

ChainLabel API

One REST endpoint turns a list of addresses into entity names, wallet roles and risk tags across 16 chains. Authenticate with a Bearer key, POST a batch of addresses (1–20 per call depending on plan), get structured JSON back.

Introduction

The base URL for all requests is:

https://api.chainlabel.io

All requests are HTTPS and return JSON. There is a single labeling endpoint, POST /v1/labels, plus a helper to list supported chains.

Authentication

Create an API key in your dashboard and send it as a Bearer token on every request. Keys look like cl_live_…. Keep them secret — treat a key like a password and rotate it if it leaks.

Authorization: Bearer cl_live_your_key

Quota & rate limits

Usage is metered per address lookup: one address lookup = one label, regardless of how many chains it returns labels on. Duplicate addresses in the same call are counted once.

• Hard monthly cap, no overage. When you hit your plan limit, requests return 402 until you upgrade or the period resets.
• Batch size by plan. Addresses per call: Starter 1, Growth 5, Scale 20 (Enterprise custom). Larger lists belong in a bulk export.
• Per-key rate limit. Each key is capped at a requests-per-second rate (1 req/s on Free, 5 req/s on all paid plans, custom on Enterprise). Exceeding it returns 429 with a Retry-After header telling you how many seconds to wait.

The limiter is a token bucket, so short bursts are fine as long as your average stays under the cap. Back off on 429 and honor Retry-After rather than retrying immediately.

POST

/v1/labels

Label addresses

Request body parameters:

addressesstring[] · required

Wallet or contract addresses. The maximum per call depends on your plan (Starter 1, Growth 5, Scale 20; Enterprise custom) — over the limit returns 422. EVM addresses are matched case-insensitively; case-sensitive chains (e.g. Tron, Solana) are matched exactly, so send the address as it appears on-chain.

chainstring · optional

Restrict results to a single chain. Accepts a chain id (ethereum), a network label (BNB CHAIN) or a common alias (eth, matic). Omit to return labels across all chains.

request

curl -X POST https://api.chainlabel.io/v1/labels \
  -H "Authorization: Bearer cl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["0x28C6c06298d514Db089934071355E5743bf21d60"]
  }'

Filtering by chain

By default a single address can return several rows — one per network it is known on. Pass chain to keep only labels for that network. The response echoes the resolved chain id in the top-level chain field. An unknown value returns 422.

Response object

results preserves the order of the addresses you sent. Each entry has the exact string you queried (query_address) and a labels array — empty when nothing is known.

200 OK

{
  "results": [
    {
      "query_address": "0x28C6c06298d514Db089934071355E5743bf21d60",
      "labels": [
        {
          "network": "ETHEREUM",
          "chain": "ethereum",
          "address": "0x28c6c06298d514db089934071355e5743bf21d60",
          "title": "Binance: Hot Wallet",
          "entity_name": "Binance",
          "label_name": "Hot Wallet",
          "chain_tags": "Centralized Exchange; Hot Wallet",
          "is_contract": false
        }
      ]
    }
  ],
  "chain": null,
  "usage": {
    "used": 1,
    "remaining": 49999,
    "limit": 50000,
    "plan": "starter"
  }
}

networkstring

Human-readable network name, e.g. ETHEREUM.

chainstring

Internal chain id used by the chain filter.

addressstring

The address as stored on that chain.

titlestring

Display label — entity and wallet role combined, e.g. Binance: Hot Wallet.

entity_namestring

The owning entity, e.g. Binance. Empty if unknown.

label_namestring

The wallet role on its own, e.g. Hot Wallet.

chain_tagsstring

Semicolon-separated tags for screening, e.g. Centralized Exchange; Hot Wallet.

is_contractboolean

Whether the address is a contract.

GET

/v1/chains

List supported chains

Returns every chain we label. Pass any id below (or its network label / alias) as the chain filter.

200 OK

{
  "chains": [
    { "id": "ethereum", "network": "ETHEREUM" },
    { "id": "bsc", "network": "BNB CHAIN" },
    { "id": "base", "network": "BASE" }
    // …
  ]
}