API reference · Balances

Balances

Elysium: Every token an address holds on Elysium, with USD value and the block it is read at.
HyperCore: Every token an address holds on HyperCore, with USD value and the block it is read at.
HyperEVM: Every token an address holds on HyperEVM, with USD value and the block it is read at.

GET https://api.femtos.xyz/v1/balances/{address}

Parameters

Param	In	Example or values	Meaning
`address`	path	`<creator>` (Elysium); `<address>` (HyperCore); `<owner>` (HyperEVM)	0x address, or a named wallet's handle `<entityId>.<hex>`
`layer`	query	`elysium` (Elysium); `hypercore` (HyperCore); `hyperevm` (HyperEVM)	Layer(s) read
`minUsd`	query	(optional)	Leave out holdings worth less (and unpriced ones)
`sort`	query	`(empty)`, `usd`, `amount`	Order
`tokens`	query	(optional)	Comma list (at most 50; 20 with block / at): EVM token addresses (`native` = HYPE) and HyperCore coin names; every token asked is listed, held or not (0)
`includeSpam`	query	`(empty)`, `true`	List spam tokens (flagged spam / spamReason); never in the totals
`block`	query	(optional)	Past balances at this block (one layer; EVM: tokens= required; HyperCore: the snapshot at or before this height)
`at`	query	(optional)	Past balances at this time (Unix ms): the last block at or before it
`verify`	query	`(empty)`, `true`	EVM layers: read the rows answered (at most 50 per layer) again on the node at the same block (Elysium, HyperEVM)

Elysium

curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/balances/<creator>?layer=elysium"

HyperCore

curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/balances/<address>?layer=hypercore"

HyperEVM

curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/balances/<owner>?layer=hyperevm"

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

Field	Type	Meaning
`address`	string	The address: 0x address, or a named wallet's handle
`layer`	hypercore \| hyperevm \| elysium \| all	Layer(s) read
`balances[]`	object	Holdings, largest USD first (sort=amount: largest amount); spam left out unless includeSpam: {layer, kind, asset, symbol, name, decimals, raw, amount, priceUsd, priceSource, usd, spam, …}
`count`	int	Rows listed
`total`	int	Rows matching before `limit`
`totalUsd`	decimal \| null	USD of every holding (spam never counts; tokens= narrows it, minUsd and limit do not) + HyperCore perp account values; null on a past read
`totalUsdComplete`	boolean	Every holding had a price and every layer asked answered
`perp`	object \| null	HyperCore perp accounts (layer hypercore / all): kept apart from the token rows; null with tokens= or a past read: {dex, collateral, accountValue, withdrawable, totalMarginUsed, totalNtlPos, positions, usd, dexes, totalUsd, abstraction, inSpot}
`layers.<layer>`	object	Per layer asked: source, height, asOf (provenance), usd, count, verify: {source, height, asOf, network, chainId, testnet, syncing, dataUntil, requested, usd, usdComplete, count, …}
`includeSpam`	boolean	Spam tokens listed (the includeSpam asked)
`spamHidden`	int	Spam holdings left out
`entity`	object	Named wallet (labels), when known

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.