API reference · Balances

Token balance

Elysium: One token of one address on Elysium: 0 when not held, now or at a past block.
HyperCore: One token of one address on HyperCore: 0 when not held, now or at a past block.
HyperEVM: One token of one address on HyperEVM: 0 when not held, now or at a past block.

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

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>`
`token`	path	`<token>` (Elysium); `USDC`, `HYPE`, `UBTC`, `PURR` (HyperCore); `0x5555555555555555555555555555555555555555` (HyperEVM)	EVM token address, `native` (HYPE), or a HyperCore coin name
`layer`	query	`elysium` (Elysium); `hypercore` (HyperCore); `hyperevm` (HyperEVM)	Default: hypercore for a coin name, hyperevm for an address
`block`	query	(optional)	Past balance at this block
`at`	query	(optional)	Past balance at this time (Unix ms)
`verify`	query	`(empty)`, `true`	EVM layers: read it again on the node at the same block (Elysium, HyperEVM)

Elysium

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

HyperCore

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

HyperEVM

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

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

Field	Type	Meaning
`balance`	object	One token held by the address on one layer: {layer, kind, asset, symbol, name, decimals, raw, amount, priceUsd, priceSource, usd, spam, …}
`balance.onchain`	object	verify=true: the same balance read again on the node at the same block: {raw, match, error}
`layers.<layer>`	object	Provenance of the layer read: source, height, asOf: {source, height, asOf, network, chainId, testnet, syncing, dataUntil, requested, usd, usdComplete, count, …}
`token`	string	Token asked

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