API reference · Balances

Balances, all layers

One address on HyperCore, HyperEVM and Elysium in one list, with totals per layer.

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	`(empty)`, `hypercore`, `hyperevm`, `elysium`, `all`	Layer(s) read
`minUsd`	query	`1`	Leave out holdings worth less (and unpriced ones)
`includeSpam`	query	`(empty)`, `true`	List spam tokens (flagged spam / spamReason); never in the totals

Elysium

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

HyperCore

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

HyperEVM

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

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

Field	Type	Meaning
`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, …}
`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
`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, …}
`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}

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.