# Account native balances

Source: https://docs.settlemint.com/docs/developer-guides/api-integration/account-native-balances
Read the latest indexed native balance and recent balance history for accounts 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.

## 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.     |

These endpoints use 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.

## 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 and 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 account is unknown for the active
system or when the account has no indexed native-balance state for that system.

## 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`. It can filter by `chainId` and `entityType`. It can sort by
`firstSeenBlock`, `address`, `nativeBalance`, and `nativeBalanceObservedAt`.

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, and each page can request 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 `nativeBalance`, `nativeBalanceObservedAtBlock`, and
`nativeBalanceObservedAt`. Results are scoped to the active system and exclude
rows outside the configured history retention window.

## 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
```

The command 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/developer-guides/api-integration/api-reference)
* [Blockchain monitoring](/docs/developer-guides/operations/blockchain-monitoring)
* [CLI command reference](/docs/developer-guides/cli/command-reference)