> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumeus.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search the token registry > Tokens known on this network, sorted by holder_count descending. Identity is the asset ID: tokens are never merged by symbol. Credit class assets-registry: 1 × ceil(rows/100), at least one credit per started 64 KiB. Publishable keys allowed. - Unknown or repeated query parameters return 400, so a typo or an unsupported filter never returns unfiltered data. ## OpenAPI ````yaml /api-reference/assets.json get /assets openapi: 3.0.3 info: title: Lumeus Assets API version: '2026-09-15' description: >- Lumeus Assets API on Stellar. Sign up at https://app.lumeus.dev: Free, Starter, Growth and Scale plans are self-serve, Enterprise by agreement. - **Pricing.** Testnet is free: Testnet requests cost no credits and are never billed. Each organization can make 10,000 Testnet requests a day across Activity, Assets and RPC (unlimited on Enterprise); the count resets at 00:00 UTC, and a request over it answers 429 rate_limited with Retry-After set to the seconds until then. Mainnet requests draw from the plan's monthly credits. Plans, limits and credit weights: `GET https://api.lumeus.dev/v1/plans`. - **Authentication.** Send `Authorization: Bearer `, 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. - **Headers.** Every response except `GET /readyz` carries X-Request-Id; authenticated responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; 429 and 503 carry Retry-After. - **Errors.** JSON with a machine-readable code (see [errors](/guides/errors)). A path with an empty, `.` or `..` segment answers 400 invalid_request, a trailing slash answers 404 not_found, and a method the path does not accept answers 405 with an Allow header. - **CORS.** Browser calls (CORS) are allowed from https://docs.lumeus.dev (the Try it playground of this reference) and https://app.lumeus.dev only, without cookies; responses expose ETag, Link, Location, Retry-After, X-Request-Id, X-Lumeus-Operation-Id, X-Lumeus-Idempotency and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (errors included). Other websites cannot read responses made with a server key: use a publishable key with your own allowed origins ([browser keys](/guides/browser-keys)). license: name: Lumeus API contract servers: - url: https://assets-testnet.lumeus.dev description: Testnet (default) - url: https://assets.lumeus.dev description: Mainnet security: - Bearer: [] tags: - name: Holdings description: >- Every balance an address holds: XLM, trustlines, liquidity pool shares and contract token balances, live or at a past ledger. - name: Account state description: Claimable balances, open DEX offers and token allowances of an address. - name: Tokens description: >- The token registry (identity, metadata, flags, supply) and the ranked holders of each token. - name: Snapshots description: >- Background jobs that compute holdings or holders at any past ledger, including before the balance history begins. - name: Health description: Liveness and readiness probes for monitoring. No authentication. paths: /assets: get: tags: - Tokens summary: Search the token registry description: >- Tokens known on this network, sorted by holder_count descending. Identity is the asset ID: tokens are never merged by symbol. Credit class assets-registry: 1 × ceil(rows/100), at least one credit per started 64 KiB. Publishable keys allowed. - Unknown or repeated query parameters return 400, so a typo or an unsupported filter never returns unfiltered data. operationId: searchTokenRegistry parameters: - name: q in: query required: false schema: type: string minLength: 1 maxLength: 64 example: USDC description: Case-insensitive code or symbol prefix, 1 to 64 characters. - name: kind in: query required: false schema: type: string enum: - native - classic - sep41 example: classic description: >- Only this kind: native (XLM), classic (CODE:ISSUER assets) or sep41 (custom contract tokens). - name: verified in: query required: false schema: type: string enum: - 'true' - 'false' example: 'true' description: >- true: only tokens whose balances are read from ledger entries or a recognized SEP-41 layout; false: only the others. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 example: 10 description: Records per page, 1 to 200 (default 50). - name: cursor in: query required: false schema: type: string description: Resume after this paging_token. Prefer following `_links.next.href`. responses: '200': description: A page of registry records, most holders first. content: application/json: schema: $ref: '#/components/schemas/AssetsPage' example: _embedded: records: - asset: >- USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 asset_type: credit_alphanum4 code: USDC contract_id: CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA decimals: 7 first_seen_ledger: 0 flags: - auth_revocable holder_count: 39417 home_domain: centre.io issuer: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 kind: classic layout: sac metadata_source: null name: null paging_token: >- eyJhIjoiVVNEQzpHQkJENDdJRjZMV0s3UDdNREVWU0NXUjdEUFVXVjNOWTNEVFFFVkZMNE5BVDRBUUgzWkxMRkxBNSIsIm4iOjM5NDE3fQ supply: '36968702153.4255427' supply_raw: '369687021534255427' supply_source: exact symbol: null toml: null verified: true - asset: CAUGJT4GREIY3WHOUUU5RIUDGSPVREF5CDCYJOWMHOVT2GWQT5JEETGJ asset_type: contract code: USDC contract_id: CAUGJT4GREIY3WHOUUU5RIUDGSPVREF5CDCYJOWMHOVT2GWQT5JEETGJ decimals: 7 first_seen_ledger: 0 flags: - impersonation_risk holder_count: 10055 home_domain: null issuer: null kind: sep41 layout: balance_i128 metadata_source: instance_storage name: Test USDC paging_token: >- eyJhIjoiQ0FVR0pUNEdSRUlZM1dIT1VVVTVSSVVER1NQVlJFRjVDRENZSk9XTUhPVlQyR1dRVDVKRUVUR0oiLCJuIjoxMDA1NX0 supply: '1710004492581.2111110' supply_raw: '17100044925812111110' supply_source: derived symbol: USDC toml: null verified: true _links: next: href: >- /assets?cursor=eyJhIjoiQ0IzVExXNzROQklPVDNCVVdPWjNUVU02UkZERjZBNEdWSVJVUVJRWkFCRzVLUE9VTDRKSk9WMkYiLCJuIjo2NDB9&limit=10&q=USDC self: href: /assets?q=USDC&limit=10 limit: 10 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 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer '400': $ref: '#/components/responses/HTTP400_3' '401': $ref: '#/components/responses/HTTP401' '402': $ref: '#/components/responses/HTTP402' '403': $ref: '#/components/responses/HTTP403_2' '405': $ref: '#/components/responses/HTTP405_5' '429': $ref: '#/components/responses/HTTP429' '503': $ref: '#/components/responses/HTTP503_2' x-codeSamples: - lang: bash label: cURL source: >- curl --fail-with-body -sS 'https://assets-testnet.lumeus.dev/assets?limit=10' \ -H "Authorization: Bearer $LUMEUS_API_KEY" - lang: javascript label: JavaScript source: >- // Node 18+ (ES module) const res = await fetch('https://assets-testnet.lumeus.dev/assets?limit=10', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUMEUS_API_KEY}`, }, }); console.log(res.status, JSON.stringify(await res.json(), null, 2)); - lang: python label: Python source: |- import json import os import requests res = requests.get( "https://assets-testnet.lumeus.dev/assets?limit=10", headers={"Authorization": f"Bearer {os.environ['LUMEUS_API_KEY']}"}, timeout=30, ) print(res.status_code, json.dumps(res.json(), indent=2)) components: schemas: AssetsPage: type: object properties: read_view: $ref: '#/components/schemas/ReadView' limit: type: integer description: 'Effective page size: default 50, maximum 200.' _links: type: object properties: self: type: object properties: href: type: string description: Relative URL; resolve against this product host. required: - href next: type: object properties: href: type: string description: Relative URL; resolve against this product host. required: - href description: Present only when more records remain. required: - self _embedded: type: object properties: records: type: array items: $ref: '#/components/schemas/Asset' required: - records required: - read_view - limit - _links - _embedded ReadView: type: object properties: network: type: string description: >- Network of this host, with the same vocabulary as Activity read_view: pubnet is Mainnet. enum: - pubnet - testnet generation: type: string description: >- State index generation. It changes when the index is rebuilt or Testnet resets; do not mix pages from two generations. as_of_ledger: type: integer description: >- The answer is exactly the post-state of this ledger. Same meaning as Activity read_view.snapshot_ledger. With the as_of_ledger query parameter it is the requested ledger. minimum: 1 as_of_closed_at: type: string format: date-time nullable: true description: >- Close time of as_of_ledger; null for as_of_ledger reads (the balance history does not record close times). bootstrap_ledger: type: integer description: >- Checkpoint the state index was bootstrapped from. Balance history (as_of_ledger queries) begins here at the earliest. minimum: 1 required: - network - generation - as_of_ledger - as_of_closed_at - bootstrap_ledger Asset: type: object properties: asset: type: string description: >- Canonical asset ID: native, CODE:ISSUER (case-sensitive, never padded), a C… contract ID for a custom token, or `pool:<64 hex>` for a liquidity pool share. A Stellar Asset Contract ID is accepted as an alias and resolves to its classic CODE:ISSUER. asset_type: type: string enum: - native - credit_alphanum4 - credit_alphanum12 - pool_share - contract kind: type: string description: >- native for XLM, classic for CODE:ISSUER (with its SAC when deployed), sep41 for a custom contract token, pool_share for a liquidity pool share. enum: - native - classic - sep41 - pool_share contract_id: type: string description: >- SAC contract ID for a classic asset, or the token contract. Null when no SAC is deployed. nullable: true code: type: string nullable: true issuer: type: string description: Null for native, pool shares and custom tokens. nullable: true name: type: string description: >- From contract metadata; null when unknown (classic assets have none). nullable: true symbol: type: string nullable: true decimals: type: integer description: >- 7 for native, classic and pool shares; null when a custom token's decimals are unknown. minimum: 0 maximum: 38 nullable: true layout: type: string description: >- How balances of this asset are stored and read. sac: native XLM and classic assets (trustlines and their Stellar Asset Contract). ledger_entry: liquidity pool shares, read from pool share trustlines. balance_i128: a custom contract token whose SEP-41 balance storage is recognized. unknown: a contract token whose storage layout is not recognized (its balances are unverified). Null when no layout is recorded. enum: - sac - ledger_entry - balance_i128 - unknown nullable: true verified: type: boolean description: >- Balances of this token are read from ledger entries or a recognized SEP-41 layout. metadata_source: type: string description: >- Where name, symbol and decimals came from; null when no metadata was read (classic assets). nullable: true home_domain: type: string description: Issuer home domain; null when unset. nullable: true toml: type: object properties: {} additionalProperties: true description: >- SEP-1 stellar.toml currency fields from home_domain. Null until fetched; stellar.toml fetching is not enabled yet, so this is currently always null. nullable: true flags: type: array items: type: string enum: - unverified_token - unreadable_metadata - impersonation_risk - likely_spam - auth_required - auth_revocable - auth_immutable - auth_clawback_enabled description: >- Registry labels. unverified_token: SEP-41 storage layout not verified. unreadable_metadata: contract metadata could not be read. impersonation_risk: the code, name or symbol imitates a well-known asset from another issuer. likely_spam: matches spam heuristics. auth_required, auth_revocable, auth_immutable, auth_clawback_enabled: classic issuer account flags (0x1, 0x2, 0x4, 0x8), cleared when the issuer account is deleted. Flags label one asset ID; tokens are never merged or hidden by symbol. holder_count: type: integer description: >- Holders with a non-zero balance, for every kind including pool shares (trustline and contract holders merged; archived contract balances included). For pool shares, pool.trustline_count also counts zero-balance trustlines. minimum: 0 supply: type: string description: >- Sum of every balance of the asset in the state index: account trustlines (or XLM account balances) plus SAC and custom-token contract balances, including archived ones. Claimable balances and liquidity pool reserves are not included. Null while not computed. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. nullable: true supply_raw: type: string description: Same as supply. Exact integer string (up to i128). pattern: ^-?[0-9]+$ nullable: true supply_source: type: string description: >- exact for ledger-derived supply; derived for custom tokens (sum of known balances). enum: - exact - derived first_seen_ledger: type: integer description: >- First ledger the token was observed. 0 when unknown: assets already present at the bootstrap checkpoint have no recorded first appearance. minimum: 0 pool: type: object properties: id: type: string description: Pool ID, 64 hex characters. asset_a: type: string description: >- Canonical asset ID: native, CODE:ISSUER (case-sensitive, never padded), a C… contract ID for a custom token, or `pool:<64 hex>` for a liquidity pool share. A Stellar Asset Contract ID is accepted as an alias and resolves to its classic CODE:ISSUER. asset_b: type: string description: >- Canonical asset ID: native, CODE:ISSUER (case-sensitive, never padded), a C… contract ID for a custom token, or `pool:<64 hex>` for a liquidity pool share. A Stellar Asset Contract ID is accepted as an alias and resolves to its classic CODE:ISSUER. fee_bp: type: integer description: Fee in basis points. reserve_a: type: string description: >- Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. reserve_b: type: string description: >- Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. total_shares: type: string description: >- Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. trustline_count: type: integer description: >- Pool share trustlines, including zero balances (holder_count counts only non-zero ones). minimum: 0 required: - id - asset_a - asset_b - fee_bp - reserve_a - reserve_b - total_shares - trustline_count description: Liquidity pool shares only. requested_as: type: string description: >- Present when the request named the asset by another ID (for example a SAC contract ID); asset is the canonical ID. paging_token: type: string description: Registry lists only. required: - asset - asset_type - kind - contract_id - code - issuer - name - symbol - decimals - layout - verified - metadata_source - home_domain - toml - flags - holder_count - supply - supply_raw - supply_source - first_seen_ledger Error: type: object properties: error: type: string description: Human-readable message. It may change; branch on code. code: type: string description: >- Machine-readable error code. Branch on code, not on the error text, which may change. RPC carries the same codes as the string error.data of a JSON-RPC error. invalid_request: 400: invalid input, including a malformed Idempotency-Key or an unknown or repeated query parameter (Webhooks also uses it for an oversized request body, 413). Fix the request; do not retry unchanged. unauthorized: 401: missing, revoked, invalid or wrong-network credential. payment_required: 402 (Mainnet): monthly credit quota exhausted on a hard-capped plan. forbidden: 403: the key or account policy does not allow this action. not_found: 404 (Webhooks also 410): the resource does not exist in this organization and network. topic_search_disabled: 404: contract-event topic search is not enabled on this network. method_not_allowed: 405: the route does not accept this method. conflict: 409: conflicting request identity, idempotency key, funding or recovery state. generation_changed: 409: the index generation or network changed since the snapshot was taken; restart the walk without generation and snapshot_ledger. history_unavailable: 409 (Assets): as_of_ledger is not answered from the balance history; start a snapshot job (POST /snapshots) or retry later. precondition_failed: 412 (Webhooks): the subscription version changed; fetch the current ETag. response_too_large: 413: the result exceeds the response budget; lower limit or narrow the request. precondition_required: 428 (Webhooks): If-Match with the subscription ETag is required. rate_limited: 429: a rate, concurrency or credit-cap limit was reached, or (Activity, Assets and RPC on Testnet) the daily Testnet request cap (message `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`, Retry-After until 00:00 UTC). Wait Retry-After seconds (a refused request consumes nothing). A Retry-After greater than 60 means the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. RPC carries it as the string error.data. internal_error: 500 or another unexpected 5xx; quote request_id when contacting support. not_implemented: 501: the feature is not enabled on this host. busy: 503: reads are saturated (the queue wait expired or the database refused another query or ran short of memory). Retry the same request after Retry-After (2) seconds. query_timeout: 503: the read ran out of time. Do not retry unchanged right away: narrow the ledger range (since_ledger/until_ledger) or lower limit; Retry-After is 30. index_not_ready: 503: the index or snapshot is not ready yet or is rebuilding; retry after Retry-After seconds. topic_coverage: 503: the effective range is outside the contract-event topic index coverage (the message states it); pass a range inside it or retry after Retry-After (60) seconds. unavailable: 503: another temporary failure (billing, rate limiter, queue); retry after Retry-After seconds. enum: - invalid_request - unauthorized - payment_required - forbidden - not_found - topic_search_disabled - method_not_allowed - conflict - generation_changed - history_unavailable - precondition_failed - response_too_large - precondition_required - rate_limited - internal_error - not_implemented - busy - query_timeout - index_not_ready - topic_coverage - unavailable request_id: type: string description: >- Identifier of this request, the same value as the X-Request-Id header. Quote it when contacting support. required: - error responses: HTTP400_3: description: Invalid input, including an unknown or repeated query parameter. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request error: q must be at most 64 characters request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP401: description: >- Missing, invalid, revoked or expired key, or a key for the other network (code unauthorized). Keys work only on the network they were created for. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized error: missing credentials request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP402: description: >- Mainnet only: the plan's monthly credits are used up on a hard-capped plan (Free; code payment_required). Upgrade, or wait for the next period. Testnet requests cost no credits, so Testnet never answers 402. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: payment_required error: >- monthly credit quota exhausted - top up credits or upgrade your plan request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP403_2: description: >- This key or account cannot call this route (code forbidden): for example a read-only key on a workspace route, or a publishable key on a route or from an origin it does not allow. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: forbidden error: >- this publishable key requires an Origin header matching one of its allowed origins request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP405_5: description: >- This path does not accept the HTTP method you sent (code method_not_allowed). The Allow header lists the methods it accepts. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: method_not_allowed error: 'method POST is not allowed on /assets; allowed: GET, HEAD' request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP429: description: >- A rate or concurrency limit was reached, or on Testnet the organization's daily Testnet request cap (10,000 requests a day across Activity, Assets and RPC); the code is rate_limited for both. Wait Retry-After seconds. A rate_limited answer whose Retry-After is greater than 60 is the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. A refused request costs nothing and does not count toward the cap. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Daily Testnet cap: summary: 'Daily Testnet request cap (Retry-After: seconds until 00:00 UTC)' value: code: rate_limited error: >- daily Testnet request cap of 10000 reached; resets at 00:00 UTC request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Plan rate limit: summary: 'Plan rate limit (Retry-After: a few seconds)' value: code: rate_limited error: rate limit exceeded request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: Identifier of this request; also in the error body as request_id. schema: type: string RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer HTTP503_2: description: >- The state index is not ready (bootstrapping, or behind the network; code index_not_ready): wait Retry-After seconds and retry. A read that ran out of time answers code query_timeout with Retry-After 30: lower limit or narrow the filters first. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Index not ready: summary: State index not ready (Retry-After 5) value: code: index_not_ready error: asset state is not ready yet; retry later request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Query timeout: summary: The read ran out of time (query_timeout, Retry-After 30) value: code: query_timeout error: >- the read exceeded its time limit; lower limit or narrow the filters, then retry (for a past ledger, start a snapshot job with POST /snapshots) request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: Identifier of this request; also in the error body as request_id. schema: type: string Retry-After: description: Seconds to wait before retrying. schema: type: integer securitySchemes: Bearer: type: http scheme: bearer description: >- Send `Authorization: Bearer `, 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.