cURL

curl --fail-with-body -sS 'https://assets-testnet.lumeus.dev/assets/BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX/holders/CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG' \
  -H "Authorization: Bearer $LUMEUS_API_KEY"

// Node 18+ (ES module)
const res = await fetch('https://assets-testnet.lumeus.dev/assets/BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX/holders/CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_API_KEY}`,
  },
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

import json
import os

import requests

res = requests.get(
    "https://assets-testnet.lumeus.dev/assets/BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX/holders/CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_API_KEY']}"},
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "holder_count": 55,
  "rank": 1,
  "rank_exact": true,
  "read_view": {
    "network": "testnet",
    "generation": "assets-testnet-v1-5253887",
    "as_of_ledger": 5332635,
    "as_of_closed_at": "2026-10-22T16:32:42Z",
    "bootstrap_ledger": 5253887
  },
  "record": {
    "archived": false,
    "asset": "BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX",
    "asset_type": "credit_alphanum4",
    "authorized": true,
    "balance": "1362.6745030",
    "balance_raw": "13626745030",
    "decimals": 7,
    "holder": "CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG",
    "kind": "contract",
    "last_modified_ledger": 5332606,
    "source": "ledger_entry",
    "verified": true
  }
}

Get one holder and its rank

One holder’s balance and rank. The rank is exact when holder_count is at most 100,000; above that it comes from a periodic refresh and rank_as_of says which ledger. Credit class assets-holder: 2 × ceil(rows/100), at least one credit per started 64 KiB. While a large asset’s rank is first computed the answer comes at once with rank null, rank_note and Retry-After, and is not charged. Publishable keys are not allowed.

Unknown or repeated query parameters return 400, so a typo or an unsupported filter never returns unfiltered data.

GET

/

assets

/

{asset}

/

holders

/

{address}

cURL

curl --fail-with-body -sS 'https://assets-testnet.lumeus.dev/assets/BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX/holders/CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG' \
  -H "Authorization: Bearer $LUMEUS_API_KEY"

// Node 18+ (ES module)
const res = await fetch('https://assets-testnet.lumeus.dev/assets/BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX/holders/CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_API_KEY}`,
  },
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

import json
import os

import requests

res = requests.get(
    "https://assets-testnet.lumeus.dev/assets/BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX/holders/CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_API_KEY']}"},
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "holder_count": 55,
  "rank": 1,
  "rank_exact": true,
  "read_view": {
    "network": "testnet",
    "generation": "assets-testnet-v1-5253887",
    "as_of_ledger": 5332635,
    "as_of_closed_at": "2026-10-22T16:32:42Z",
    "bootstrap_ledger": 5253887
  },
  "record": {
    "archived": false,
    "asset": "BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX",
    "asset_type": "credit_alphanum4",
    "authorized": true,
    "balance": "1362.6745030",
    "balance_raw": "13626745030",
    "decimals": 7,
    "holder": "CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG",
    "kind": "contract",
    "last_modified_ledger": 5332606,
    "source": "ledger_entry",
    "verified": true
  }
}

Authorizations

Authorization

string

header

required

Send Authorization: Bearer <key>, the same keys as Activity and RPC. Testnet: lum_test_…; Mainnet: lum_live_…. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable lum_pub_… keys work only on the routes marked "Publishable keys allowed", from an allowed browser origin.

Path Parameters

asset

string

required

native, CODE:ISSUER (case-sensitive, never padded), a C… token contract ID or pool:<64 hex>. A Stellar Asset Contract ID is accepted as an alias and resolves to its classic CODE:ISSUER.

Example:

"BTC:GAGVZMODPYFTULIVSY3RGFADIC5LF4LLSN37N4MFWGNZ57TYBXL2LQQX"

address

string

required

Checksum-valid G or C holder address. An M… address resolves to its G account and the response carries muxed_input.

Example:

"CCSXXPCXICXOC2MLU3UINWYKL6M5VNLVOTHA4ZQ5S5BEDZGRWDTP52CG"

Response

The holder record and its rank. Retry-After is present when rank is null and still being computed.

read_view

object

required

Show child attributes

record

object

required

Show child attributes

rank

integer | null

required

1-based position by balance desc, holder asc. Exact when holder_count is at most 100,000. Null while the rank of a large asset is being computed: rank_note says so, the response carries Retry-After and the answer is not charged.

Required range: x >= 1

rank_exact

boolean

required

True when rank is exact; false when it comes from the periodic refresh (rank_as_of) or is null.

holder_count

integer

required

Required range: x >= 0

rank_as_of

integer

Present when the asset has more than 100,000 holders: rank comes from a periodic refresh at this ledger.

Required range: x >= 1

rank_note

string

Present while the rank is being computed (rank is null). Retry after the Retry-After header; this answer is not charged.

muxed_input

string

The M… address from the request, when one was sent.