DALP account native balance API for integrations

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. Use the observed block and timestamp as freshness evidence before triggering funding alerts or deciding that a recent top-up is missing.

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.

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

Use the by-address endpoint when you already know the account address.

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:

{
  "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

Use the collection endpoint when you need to discover monitored addresses before reading one account.

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.

It can filter by chainId and entityType. It can sort 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

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.

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 history retention window. DALP sorts history by observed block descending by default and uses the history row ID as a tie-breaker so pagination remains deterministic.

Use the history 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.

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

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

For scripts and operations checks, use the CLI account command to read the latest indexed native balance for one address:

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.

Account native balances