Balances

Normalized balances for an address across the requested chains.

GET/v1/balances/{address}

Query parameters

Parameter	Type	Description
chains	string	Comma-separated chain slugs (e.g. "ethereum,base,bitcoin"). Defaults to all supported chains.
minValueUsd	number	Dust filter. Omit to hide unpriced / zero-value tokens (default); pass 0 to include everything; pass a positive number to drop tokens worth less than it. Native balances are always kept.
includeSpam	boolean	Include tokens flagged as spam by upstream providers. Default false.

Example request

curl "https://chainkit.ai/v1/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chains=ethereum,base,bitcoin" \
  -H "Authorization: Bearer thw_live_xxxxxxxx"

Example response

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chains": ["ethereum", "base", "bitcoin"],
  "totalUsd": "12843.52",
  "updatedAt": "2026-06-04T10:15:00Z",
  "balances": [
    {
      "chain": "ethereum",
      "asset": "ETH",
      "type": "native",
      "contractAddress": null,
      "amount": "1.245",
      "rawAmount": "1245000000000000000",
      "decimals": 18,
      "priceUsd": "3820.12",
      "valueUsd": "4756.05",
      "name": "Ethereum"
    },
    {
      "chain": "base",
      "asset": "USDC",
      "type": "erc20",
      "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "2450.00",
      "rawAmount": "2450000000",
      "decimals": 6,
      "priceUsd": "1.00",
      "valueUsd": "2450.00",
      "name": "USD Coin",
      "isSpam": false
    }
  ],
  "errors": []
}

Response schema

Top level: address, chains, totalUsd, updatedAt, balances[], and errors[]. Each balances[] item:

Field	Type	Description
chain	string	Chain slug the balance belongs to.
asset	string	Ticker symbol (e.g. ETH, USDC).
type	string	"native" or "erc20".
contractAddress	string \| null	Token contract address; null for native assets.
amount	string	Human-readable amount as a decimal string.
rawAmount	string	Smallest-unit integer string (wei, sats, …).
decimals	number	Decimals used to derive amount from rawAmount.
priceUsd	string \| null	USD price per unit; null when unknown.
valueUsd	string \| null	amount × priceUsd; null when unpriced.
name	string?	Asset name, when known.
icon	string?	Logo URL, when known.
isSpam	boolean?	True when the upstream flagged the token as spam.

Filtering

By default the API hides dust — non-native tokens with no USD value — so you get a clean portfolio. Tune it:

?minValueUsd omitted — hide unpriced / zero-value tokens (default).

?minValueUsd=0 — include everything, even unpriced dust.

?minValueUsd=1 — only tokens worth ≥ $1 (native always kept).

?includeSpam=true — include tokens flagged as spam.

Partial failures

A single chain's provider failing never fails the whole response. Successful chains return in balances[]; failed ones appear in errors[] with a per-chain code, so you can render what you have and retry the rest. See Errors.

"errors": [
  { "chain": "arbitrum", "code": "UPSTREAM_PROVIDER_ERROR", "message": "Arbitrum provider temporarily unavailable." }
]

Response headers

Header	Description
X-Request-ID	Unique id for the request — include it in support tickets.
X-Credits-Charged	Credits this request consumed.
X-Credits-Remaining	Your organization credit balance after the request.
X-RateLimit-Limit	Requests allowed per window for this key + endpoint (set by your plan).
X-RateLimit-Remaining	Requests left in the current window.
X-RateLimit-Reset	Unix seconds when the window resets.

PreviousAuthentication NextAccount