# Account native balances Source: https://docs.settlemint.com/docs/api-reference/wallets/account-native-balances Read indexed native balances and history for accounts, plus the live custody wallet gas balance, in the active DALP system. Use account native-balance reads when an integration needs the latest indexed gas balance for a platform-relevant address, such as an operator wallet, smart account, system contract, or asset contract. DALP returns indexed account state for the active system. Each account result includes the chain ID, address, entity type, optional contract name, latest native balance, the observed block, and the observed timestamp. Use the observed block and timestamp as freshness evidence before triggering funding alerts or deciding that a recent top-up is missing. ## Endpoints [#endpoints] The account native-balance API exposes three read endpoints: | Endpoint | Use it for | | ----------------------------------------------------------------- | ------------------------------------------------------- | | `GET /api/v2/accounts` | List indexed accounts with their latest native balance. | | `GET /api/v2/accounts/{chainId}/{address}` | Read one indexed account by chain ID and address. | | `GET /api/v2/accounts/{chainId}/{address}/native-balance/history` | Read recent native-balance history for one account. | All three endpoints require account-native-balance read access for the active system. The collection endpoint reads the active chain from DALP configuration. The by-address and history endpoints also validate that the requested `chainId` matches that active chain. All three endpoints return indexed state. If a wallet was funded very recently, compare `nativeBalanceObservedAtBlock` with chain and indexer health before treating a missing or stale balance as final. Indexed reads reflect what the Ledger Index has observed, not the chain head. ## Read one account [#read-one-account] Use the by-address endpoint when you already know the account address. ```bash curl "$DALP_API_URL/api/v2/accounts/1/0x1000000000000000000000000000000000000001" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` A successful response contains one account, plus links to the same resource and its history endpoint: ```json { "data": { "chainId": 1, "address": "0x1000000000000000000000000000000000000001", "entityType": "operator-wallet", "contractName": "Operator Wallet", "nativeBalance": "12345", "nativeBalanceObservedAtBlock": "8154321", "nativeBalanceObservedAt": "2026-05-01T11:59:30.000Z" }, "links": { "self": "/v2/accounts/1/0x1000000000000000000000000000000000000001", "history": "/v2/accounts/1/0x1000000000000000000000000000000000000001/native-balance/history" } } ``` DALP returns a not-found response when the address is unknown to the active system, or when no indexed native-balance state exists for it. ## List indexed accounts [#list-indexed-accounts] Use the collection endpoint when you need to discover monitored addresses before reading one account. ```bash curl --globoff "$DALP_API_URL/api/v2/accounts?filter[chainId][eq]=1&filter[entityType][eq]=operator-wallet&sort=address&page[limit]=50" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` The list endpoint returns a paginated collection envelope with `data`, `meta`, and `links`. Each row uses the same account fields as the by-address response. The `meta` object includes the total result count and available facets. The `links` object contains pagination links for the current query. The endpoint filters by `chainId` and `entityType`. It sorts by `firstSeenBlock`, `address`, `nativeBalance`, and `nativeBalanceObservedAt`. Equal sort-key rows are ordered by address so offset pages stay stable. Supported `entityType` values include `eoa`, `asset`, `bond`, `equity`, `fund`, `vault`, `deposit`, `stablecoin`, `real-estate`, `precious-metal`, `system`, `smart-account`, `operator-wallet`, and `contract`. ## Read balance history [#read-balance-history] Use the history endpoint when you need recent balance observations for one account. The request must include `filter[since]` as an observed-block lower bound. Each page can return at most 100 rows. ```bash curl --globoff "$DALP_API_URL/api/v2/accounts/1/0x1000000000000000000000000000000000000001/native-balance/history?filter[since][gte]=8154000&page[limit]=100&sort=-observedAtBlock" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` History rows include `id`, `chainId`, `address`, `nativeBalance`, `nativeBalanceObservedAtBlock`, and `nativeBalanceObservedAt`. Results are scoped to the active system and exclude rows outside the configured retention window. DALP sorts rows by observed block descending by default and uses the row ID as a tie-breaker, so pagination stays deterministic. Use this endpoint for trend checks and alert investigation, not as a full archive. Start with the latest block you have already processed in `filter[since]` and follow the pagination links until the page is exhausted. ## Read a live custody wallet gas balance [#read-a-live-custody-wallet-gas-balance] Indexed account reads can lag a very recent top-up. When your DALP system uses [DFNS custody](/docs/architects/integrations/custody-providers), you can read the live native gas-token balance of the signed-in user's custody wallet directly from the provider, without waiting for the indexer to observe it. ```bash curl "$DALP_API_URL/api/v2/smart-wallets/custody/gas-balance" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` The endpoint takes no parameters. It resolves the custody wallet from the authenticated session. The platform returns the live native-token balance the custody provider reports: ```json { "data": { "balance": "1000000000000000000", "symbol": "ETH", "decimals": 18 }, "links": { "self": "/v2/smart-wallets/custody/gas-balance" } } ``` `data` is `null` in three cases: the active system does not use DFNS custody, the signed-in user has no custody wallet, or the provider reports no native-token asset for that wallet. The live balance endpoint supports DFNS custody only. Other custody providers always return `null` here. Treat a `null` result as "no live custody balance available", not as a zero balance, and fall back to the indexed account reads above. | Field | Meaning | | ---------- | ------------------------------------------------------------ | | `balance` | Live native-token balance as a bigint-compatible string. | | `symbol` | Native token symbol, such as `ETH`. | | `decimals` | Native token decimal places, for converting the raw balance. | Use this live read when you need an up-to-the-moment custody-wallet balance, for example before submitting a gas-funded operation. Use the indexed account reads above for discovery, history, and balances across operator wallets, smart accounts, and contracts. ## Response fields [#response-fields] | Field | Meaning | | ------------------------------ | ----------------------------------------------------------------------- | | `chainId` | Active EVM chain where DALP indexed the account. | | `address` | Lowercase EVM account address. | | `entityType` | Account category, such as `operator-wallet`, `smart-account`, or asset. | | `contractName` | Contract label when DALP knows one, otherwise `null`. | | `nativeBalance` | Indexed native-token balance as a bigint-compatible string. | | `nativeBalanceObservedAtBlock` | Block number for the balance observation. | | `nativeBalanceObservedAt` | Timestamp for the balance observation. | ## Troubleshooting [#troubleshooting] | Symptom | What to check | | --------------------------- | ------------------------------------------------------------------------------------------------- | | Account returns not found | Confirm the address belongs to the active DALP system and has indexed native-balance state. | | History request is rejected | Include `filter[since]` and keep `page[limit]` at 100 rows or fewer. | | Balance looks stale | Compare `nativeBalanceObservedAtBlock` with the latest indexed block and chain monitoring status. | | Expected account is missing | List by `entityType` first, then read the exact address from the list response. | ## Read the latest balance from the CLI [#read-the-latest-balance-from-the-cli] For scripts and operations checks, use the CLI account command to read the latest indexed native balance for one address: ```bash dalp account native-balance read 1 0x1000000000000000000000000000000000000001 ``` It calls the same by-address account read used by the API. Use API collection and history reads when you need pagination, filtering, or historical observations. ## Related [#related] * [API reference](/docs/api-reference/reference/openapi) * [Blockchain monitoring](/docs/developers/operations/blockchain-monitoring) * [CLI command reference](/docs/developers/cli/command-reference)