> ## 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. # List holdings of an address > Every balance the address holds: XLM, trustlines (including zero balances with include=zero), liquidity pool shares, and SAC and custom-token balances held in contract storage, live or archived. Sorted by asset. Each record says how it was determined (source, verified); the completeness block says whether the whole answer is verified. G accounts also get an account block with spendable XLM; an unfunded or unknown G address answers 200 with `account: null` and no records. With as_of_ledger the holdings are read at a past ledger from the balance history (credit class assets-history, weight 5): include=closed is not available, unverified balances are not simulated, and publishable keys are not allowed. The history begins at read_view.bootstrap_ledger at the earliest; earlier ledgers need a snapshot job (`POST /snapshots`). Credit class assets-holdings: 1 × ceil(rows/100), at least one credit per started 64 KiB. Each unverified token simulated adds 1 credit. 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 /accounts/{address}/holdings 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: /accounts/{address}/holdings: get: tags: - Holdings summary: List holdings of an address description: >- Every balance the address holds: XLM, trustlines (including zero balances with include=zero), liquidity pool shares, and SAC and custom-token balances held in contract storage, live or archived. Sorted by asset. Each record says how it was determined (source, verified); the completeness block says whether the whole answer is verified. G accounts also get an account block with spendable XLM; an unfunded or unknown G address answers 200 with `account: null` and no records. With as_of_ledger the holdings are read at a past ledger from the balance history (credit class assets-history, weight 5): include=closed is not available, unverified balances are not simulated, and publishable keys are not allowed. The history begins at read_view.bootstrap_ledger at the earliest; earlier ledgers need a snapshot job (`POST /snapshots`). Credit class assets-holdings: 1 × ceil(rows/100), at least one credit per started 64 KiB. Each unverified token simulated adds 1 credit. Publishable keys allowed. - Unknown or repeated query parameters return 400, so a typo or an unsupported filter never returns unfiltered data. operationId: listHoldingsOfAddress parameters: - name: address in: path required: true description: >- Checksum-valid G or C address. An M… address resolves to its G account and the response carries muxed_input. B… and L… addresses are never holders. schema: type: string example: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR x-default: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR example: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR - name: kind in: query required: false schema: type: string enum: - native - trustline - pool_share - contract example: trustline description: Only holdings of this kind. - name: min_balance in: query required: false schema: type: string pattern: ^[0-9]+(\.[0-9]+)?$ example: '1' description: Decimal; holdings below it are left out. - name: include in: query required: false schema: type: string pattern: ^(zero|closed|unverified)(,(zero|closed|unverified))*$ example: zero description: >- Comma list: zero (zero-balance trustlines), closed (previously held, with closed_ledger), unverified (event-derived or simulated custom-token balances). Default: none of them. - name: asset in: query required: false schema: type: string description: >- Only this asset: `native`, `CODE:ISSUER` (case-sensitive), a C… token contract ID or `pool:<64 hex>`. A Stellar Asset Contract ID matches the balances of its classic asset (CODE:ISSUER, or native for the native SAC), which records report under that classic ID. - name: as_of_ledger in: query required: false schema: type: integer minimum: 1 example: 5300000 description: >- Read at this past ledger from the balance history (credit class assets-history, weight 5). 400 when after the latest applied ledger; 409 when the history cannot answer it exactly. Not available to publishable keys. - 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 holdings, the completeness block and, for a G account, the account entry. content: application/json: schema: $ref: '#/components/schemas/HoldingsPage' example: _embedded: records: - asset: native asset_type: native kind: native contract_id: CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC code: XLM issuer: null name: Lumens symbol: XLM decimals: 7 balance: '7054567984.5299856' balance_raw: '70545679845299856' source: ledger_entry verified: true archived: false live_until_ledger: null authorized: null maintain_liabilities: null clawback: null limit: null buying_liabilities: '0.0000000' selling_liabilities: '0.0000000' spendable: '7054567983.5299856' last_modified_ledger: 5332632 flags: [] paging_token: Im5hdGl2ZSI _links: self: href: >- /accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR/holdings?limit=10 account: balance: '7054567984.5299856' base_reserve: '0.5000000' buying_liabilities: '0.0000000' flags: 0 home_domain: '' id: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR last_modified_ledger: 5332632 minimum_balance: '1.0000000' selling_liabilities: '0.0000000' sequence: '695784702525' spendable: '7054567983.5299856' sponsored: 0 sponsoring: 0 subentries: 0 address: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR completeness: complete: true note: >- every holding is read from protocol ledger entries or recognized SEP-41 storage simulated: 0 simulation_skipped: 0 unverified: 0 unverified_contracts: [] verified: 1 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' '401': $ref: '#/components/responses/HTTP401' '402': $ref: '#/components/responses/HTTP402' '403': $ref: '#/components/responses/HTTP403' '405': $ref: '#/components/responses/HTTP405' '409': $ref: '#/components/responses/HTTP409' '429': $ref: '#/components/responses/HTTP429' '501': $ref: '#/components/responses/HTTP501' '503': $ref: '#/components/responses/HTTP503' x-codeSamples: - lang: bash label: cURL source: >- curl --fail-with-body -sS 'https://assets-testnet.lumeus.dev/accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR/holdings?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/accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR/holdings?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/accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR/holdings?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: HoldingsPage: 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/Holding' required: - records address: type: string description: >- The looked-up address (G or C; an M… input resolves to its G account). completeness: $ref: '#/components/schemas/Completeness' account: nullable: true allOf: - $ref: '#/components/schemas/AccountState' description: >- G accounts only: the account entry, or null when the account does not exist. Absent for C addresses. muxed_input: type: string description: The M… address from the request, when one was sent. required: - read_view - limit - _links - _embedded - address - completeness 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 Holding: 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 description: >- Derived from the asset ID: credit_alphanum4 for codes of 1 to 4 characters, credit_alphanum12 for 5 to 12. enum: - native - credit_alphanum4 - credit_alphanum12 - pool_share - contract kind: type: string description: >- native, trustline, pool_share or contract (a SAC or custom-token balance held in contract storage). enum: - native - trustline - pool_share - contract contract_id: type: string description: >- SAC contract ID for a classic asset, or the token contract for a custom token. Null when no contract is known (for example a classic asset without a deployed SAC). nullable: true code: type: string description: Null for native and pool shares. nullable: true issuer: type: string description: Null for native, pool shares and custom tokens. nullable: true name: type: string description: >- Token name from contract metadata; null when unknown (always for classic assets). nullable: true symbol: type: string description: Null when unknown. nullable: true decimals: type: integer description: >- 7 for XLM, classic assets and SAC balances; from the registry for custom tokens, null when unknown (balance is then in raw units). minimum: 0 maximum: 38 nullable: true balance: type: string description: >- Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. balance_raw: type: string description: Exact integer string (up to i128). pattern: ^-?[0-9]+$ source: type: string description: >- How the value was determined. ledger_entry: read from the protocol entry (account, trustline, pool share, claimable balance, SAC balance). token_storage: a custom SEP-41 token whose storage layout is recognized. simulation: balance() simulated at as_of_ledger (unverified). enum: - ledger_entry - token_storage - simulation verified: type: boolean description: >- True for ledger_entry. True for token_storage only when the token is classified SEP-41 and its storage layout is recognized. False otherwise. archived: type: boolean description: >- The entry is in the hot archive. It is still owned and is restored automatically on use. Never shown as zero. live_until_ledger: type: integer description: >- Contract balances: the ledger until which the storage entry is live (TTL). Null for classic entries. minimum: 0 nullable: true authorized: type: boolean description: >- Trustline or SAC balance authorization. Null for XLM and pool shares. nullable: true maintain_liabilities: type: boolean description: >- The raw trustline flag AUTHORIZED_TO_MAINTAIN_LIABILITIES (0x2). Unlike Horizon's is_authorized_to_maintain_liabilities, a fully authorized trustline reads authorized true and maintain_liabilities false. Null when not a trustline. nullable: true clawback: type: boolean description: >- Clawback is enabled for this trustline or SAC balance. Null for XLM and pool shares. nullable: true limit: type: string description: >- Trustline limit. Null when not a trustline. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. nullable: true buying_liabilities: type: string description: >- Classic only; null otherwise. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. nullable: true selling_liabilities: type: string description: >- Classic only; null otherwise. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. nullable: true spendable: type: string description: >- XLM and trustlines: balance minus selling liabilities; for XLM also minus the minimum balance (Core formula); 0 for an unauthorized trustline. Null for other kinds. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. nullable: true last_modified_ledger: type: integer minimum: 1 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. paging_token: type: string description: Opaque keyset cursor. closed: type: boolean description: >- Present (true) only on include=closed rows: the holding was removed or reached zero. last_balance: type: string description: >- include=closed rows only: the balance before the holding closed. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. closed_ledger: type: integer description: >- include=closed rows only: the ledger the holding was removed or reached zero. minimum: 1 simulated_ledger: type: integer description: >- Simulated (source simulation) rows only: the ledger balance() was simulated at. minimum: 1 required: - asset - asset_type - kind - contract_id - code - issuer - name - symbol - decimals - balance - balance_raw - source - verified - archived - live_until_ledger - authorized - maintain_liabilities - clawback - limit - buying_liabilities - selling_liabilities - spendable - last_modified_ledger - flags - paging_token Completeness: type: object properties: complete: type: boolean description: >- True only when every holding is verified and no candidate token was skipped. verified: type: integer minimum: 0 unverified: type: integer description: >- Unverified balances plus candidate token contracts whose storage layout is not recognized. minimum: 0 simulated: type: integer minimum: 0 simulation_skipped: type: integer description: >- Unverified candidate tokens not simulated in this response (budget, or simulation disabled on this host). minimum: 0 unverified_contracts: type: array items: type: string description: C… contract ID. description: >- Candidate token contracts with an unrecognized storage layout that this address may hold. note: type: string description: Plain-language explanation of the completeness state. required: - complete - verified - unverified - simulated - simulation_skipped - unverified_contracts - note AccountState: type: object properties: id: type: string description: G account ID. balance: type: string description: >- XLM balance. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. spendable: type: string description: >- XLM available to send: balance minus the minimum balance and selling liabilities. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. minimum_balance: type: string description: >- Reserve required by subentries and sponsorships. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. base_reserve: type: string description: >- Network base reserve used for minimum_balance. Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. subentries: type: integer sponsoring: type: integer sponsored: type: integer buying_liabilities: type: string description: >- Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. selling_liabilities: type: string description: >- Decimal string using the token's decimals (7 for XLM, classic assets and SACs). Never a float. flags: type: integer description: >- AccountFlags bit mask (1 auth required, 2 auth revocable, 4 auth immutable, 8 clawback enabled). minimum: 0 home_domain: type: string description: Empty string when unset. sequence: type: string description: Account sequence number as a decimal string. last_modified_ledger: type: integer minimum: 1 required: - id - balance - spendable - minimum_balance - base_reserve - subentries - sponsoring - sponsored - buying_liabilities - selling_liabilities - flags - home_domain - sequence - last_modified_ledger description: G accounts only. 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: description: Invalid input, including an unknown or repeated query parameter. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request error: >- unknown query parameter "foo"; supported: kind, min_balance, include, asset, limit, cursor, as_of_ledger 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: 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' examples: Origin not allowed: summary: Publishable key from an origin it does not allow value: code: forbidden error: >- this publishable key requires an Origin header matching one of its allowed origins request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Publishable key with as_of_ledger: summary: Publishable key with as_of_ledger value: code: forbidden error: >- publishable keys can only read account holdings and the asset registry; use a secret key on your server 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: 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 /accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR/holdings; 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}$ HTTP409: description: >- as_of_ledger is not answered from the balance history: it is before the history begins, inside a repaired gap, or not yet written (history is written in 64-ledger batches, so the last few minutes are missing); for holders, also when the asset has more than 100,000 holders. The message says which; the code is history_unavailable. Start a snapshot job (`POST /snapshots`) or retry later. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Before the balance history: summary: Before the balance history value: code: history_unavailable error: >- balance history begins at ledger 5253887; for ledger 5000000 start a snapshot job (POST /snapshots) request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Not written yet: summary: Not written yet value: code: history_unavailable error: >- balance history is written in 64-ledger batches and currently reaches ledger 5331456; retry in a few minutes or read the current state without as_of_ledger 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 HTTP501: description: Balance history is not enabled on this host. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_implemented error: historical reads (as_of_ledger) are not available yet 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}$ HTTP503: 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. With as_of_ledger, also when too many historical reads are running at once (code busy, Retry-After 2), a historical read exceeded its memory limit (busy, Retry-After 30) or its time limit (query_timeout, Retry-After 30), or the history is not initialized or rebuilding (index_not_ready). 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 Busy: summary: Too many historical reads (as_of_ledger, busy, Retry-After 2) value: code: busy error: >- too many historical reads are running; retry after the Retry-After delay 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.