API reference, Balances

Balances stream

Elysium: What an address holds on Elysium (GET /v1/balances/{address}: every token, USD, totals), pushed on subscribe and in the block that changes it.
HyperEVM: What an address holds on HyperEVM (GET /v1/balances/{address}: every token, USD, totals), pushed on subscribe and in the block that changes it.

Not on HyperCore: a HyperCore account’s balances move with its fills, transfers and funding: the wallet channel streams those (hc.trades, hc.ledger), GET /v1/balances/{address}?layer=hypercore reads them live from our node

WebSocket channel balances on wss://api.femtos.xyz/v1/ws

Parameters

Param	In	Example or values	Meaning
`address`	filter	`0x876f1301aaa8452ceb98201cd4407fa9510a8181` (Elysium); `0x1b86c68e4003a8e139d71a9f06a1b1cc18678626` (HyperEVM)	The address: 0x, or a named wallet's handle
`layer`	filter	`elysium` (Elysium); `hyperevm` (HyperEVM)	hyperevm or elysium
`tokens`	filter	(optional)	Comma list of token addresses (`native` = HYPE): only those, held or not (0)
`minUsd`	filter	(optional)	Leave out holdings worth less (and unpriced ones)
`includeSpam`	filter	(optional)	true: also spam tokens (flagged spam), never in the totals
`limit`	filter	(optional)	Rows, largest first, default 100 (1..1000)

Elysium

{"op":"subscribe","channel":"balances","filter":{"address":"0x876f1301aaa8452ceb98201cd4407fa9510a8181","layer":"elysium"}}

HyperEVM

{"op":"subscribe","channel":"balances","filter":{"address":"0x1b86c68e4003a8e139d71a9f06a1b1cc18678626","layer":"hyperevm"}}

Key: Authorization: Bearer $FEMTOS_KEY. Get a free key, or with no browser through agent onboarding.

Field	Type	Meaning
`snapshot: true`	object	the full GET /v1/balances/{address} answer: the first frame, and any frame sent whole
`patch: true`	JsonPatch	with "patch": true on subscribe: the operations, in order, that turn the previous answer into this one
`billing`	rest	the snapshot a subscribe asks for counts as GET /v1/balances/{address} (rest); every other frame by its bytes (1 credit per 48 KiB)

Balances GET /v1/balances/{address} Elysium, HyperCore, HyperEVM
Every token an address holds on HyperCore, with USD value and the block it is read at.
Token balance GET /v1/balances/{address}/{token} Elysium, HyperCore, HyperEVM
One token of one address on HyperCore: 0 when not held, now or at a past block.
Batch balances POST /v1/balances/batch Elysium, HyperCore, HyperEVM
Up to 100 addresses on HyperCore in one call, the same answer for each.
Balances, all layers GET /v1/balances/{address} Elysium, HyperCore, HyperEVM
One address on HyperCore, HyperEVM and Elysium in one list, with totals per layer.