Overview

One entry per requested chain (default: all supported). Amounts are base-unit strings (USDC 6dp integer string, native in wei); nativeUsdPrice is the chain's native gas-token USD price in decimal dollars (null when unavailable). Per-chain error isolation: a failed RPC marks that chain error: "rpc_error" and never fails the whole response.

Endpoint

GET https://earn-api.quicknode.dev/functions/v1/api/v1/wallets/{addr}/balances

Authorization

Include the published apikey header. This read request is public and does not require a SIWE signature.

Parameters

Parameter	Location	Type	Required	Description
addr	path	string	Yes	Wallet address (`0x` + 40 hex).
chains	query	string	No	CSV of supported chain ids. Defaults to all.

Example request

curl --location 'https://earn-api.quicknode.dev/functions/v1/api/v1/wallets/0x1234567890abcdef1234567890abcdef12345678/balances' \
  --header 'Accept: application/json' \
  --header 'apikey: <EARN_PUBLIC_API_KEY>'

Response

Field	Type	Required	Description
address	string	Yes	Lowercased wallet address.
chains	array<object>	Yes	Balance result for each requested chain. Defaults to all supported chains.
chains[].chainId	integer	Yes	Numeric identifier of the chain.
chains[].nativeSymbol	string	Yes	Symbol of the chain's native gas token, such as ETH, POL, or MON.
chains[].nativeBalanceWei	string | null	Yes	Native gas-token balance in wei as a base-unit string. Returns null when the RPC read fails.
chains[].nativeUsdPrice	number | null	Yes	USD price of the chain's native gas token. Returns null when price data is unavailable.
chains[].usdc	string | null	Yes	USDC token address on the chain, or null when USDC is not configured.
chains[].usdcBalance	string | null	Yes	USDC balance as a six-decimal base-unit string. For example, `1000000` represents 1 USDC. Returns null when the RPC read fails.
chains[].error	string (rpc_error) | null	Yes	Returns `rpc_error` when the chain read fails; otherwise, returns null. Errors are isolated to the affected chain.

Example response

{
	"address": "0x1234567890abcdef1234567890abcdef12345678",
	"chains": [
		{
			"chainId": 8453,
			"nativeSymbol": "ETH",
			"nativeBalanceWei": "44127564589110835",
			"nativeUsdPrice": 1880.7437102818824,
			"usdc": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
			"usdcBalance": "44988328",
			"error": null
		},
		{
			"chainId": 1,
			"nativeSymbol": "ETH",
			"nativeBalanceWei": "3977664413963610716",
			"nativeUsdPrice": 1880.7437102818824,
			"usdc": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
			"usdcBalance": "128000000",
			"error": null
		},
		{
			"chainId": 10,
			"nativeSymbol": "ETH",
			"nativeBalanceWei": "10430174303599012",
			"nativeUsdPrice": 1880.7437102818824,
			"usdc": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
			"usdcBalance": "1000000",
			"error": null
		},
		{
			"chainId": 130,
			"nativeSymbol": "ETH",
			"nativeBalanceWei": "0",
			"nativeUsdPrice": 1880.7437102818824,
			"usdc": "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
			"usdcBalance": "0",
			"error": null
		},
		{
			"chainId": 137,
			"nativeSymbol": "POL",
			"nativeBalanceWei": "5659164418960018502",
			"nativeUsdPrice": 0.07153907555691406,
			"usdc": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
			"usdcBalance": "36953373",
			"error": null
		},
		{
			"chainId": 143,
			"nativeSymbol": "MON",
			"nativeBalanceWei": "25027040112373086031",
			"nativeUsdPrice": 0.020911670985421467,
			"usdc": "0x754704Bc059F8C67012fEd69BC8A327a5aafb603",
			"usdcBalance": "0",
			"error": null
		},
		{
			"chainId": 42161,
			"nativeSymbol": "ETH",
			"nativeBalanceWei": "9134530030154837",
			"nativeUsdPrice": 1880.7437102818824,
			"usdc": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
			"usdcBalance": "39163619",
			"error": null
		}
	]
}

HTTP responses

Status	Description
200	Per-chain balances.
400	The wallet address or requested chain list is malformed or unsupported.
429	Rate limit exceeded. `Retry-After` (seconds) tells you when to retry. Reads, feedback, and push writes are keyed per IP; create/update/delete are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per strategy+IP.

OpenAPI source

This page is based on operation getWalletBalances in the Earn OpenAPI 3.1 specification.