Holdings on every chain

GET

/wallet/{wallet}/balances

const url = 'https://api.getchord.xyz/v1/wallet/example/balances';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.getchord.xyz/v1/wallet/example/balances

What a wallet holds right now on Chord’s six chains (Monad, Robinhood Chain, Arc, Avalanche, Base, BNB Chain), read on-chain: the native coin plus every token on Chord’s list for each chain, priced by Chord’s own maps. raw is the exact balance in the token’s smallest unit (use it for a Max button); amount is the same number in whole tokens. Each chain answers on its own deadline: a slow or failing chain comes back unavailable with a reason and the others still answer. Only listed tokens are seen; a token outside Chord’s lists will not show. Cached 15 s per wallet and chain set.

Parameters

Path Parameters

wallet

required

EVM address, hex, case-insensitive.

string

/^0x[a-fA-F0-9]{40}$/

Query Parameters

chains

string

Comma list of chain ids (143, 4663, 5042, 43114, 8453, 56). Default: all six; unknown ids are ignored.

Responses

200

application/json

object

wallet

EVM address, hex, case-insensitive.

string

/^0x[a-fA-F0-9]{40}$/

totalUsd

Sum of priced holdings.

number

updatedAt

Unix time, milliseconds — when the server built this answer.

integer

chains

Array<object>

object

chain

integer

name

string

status

string

Allowed values: ok unavailable no_rpc

reason

Only when not ok.

string

totalUsd

number

holdings

Highest value first.

Array<object>

object

symbol

string

name

string | null

address

Null for the native coin.

string | null

native

boolean

decimals

integer

raw

Exact balance, smallest unit.

string

amount

Whole tokens.

string

priceUsd

number | null

valueUsd

number | null

logoURI

string | null

stable

boolean

Example

{
  "wallet": "0x0d36a315083033d3d097950c9e494acc04588f99",
  "chains": [
    {
      "chain": 8453,
      "name": "Base",
      "status": "ok",
      "totalUsd": 1221.38,
      "holdings": [
        {
          "symbol": "ETH",
          "name": null,
          "address": null,
          "native": true,
          "decimals": 18,
          "raw": "454663939527832318",
          "amount": "0.454663939527832318",
          "priceUsd": 2686.342436128022,
          "valueUsd": 1221.38,
          "logoURI": null,
          "stable": false
        },
        {
          "symbol": "WETH",
          "name": null,
          "address": "0x4200000000000000000000000000000000000006",
          "native": false,
          "decimals": 18,
          "raw": "148044",
          "amount": "0.000000000000148044",
          "priceUsd": 2686.342436128022,
          "valueUsd": 0,
          "logoURI": null,
          "stable": false
        }
      ]
    }
  ],
  "totalUsd": 1221.38,
  "updatedAt": 1791052461304
}

400

Invalid parameters — error names the check that failed (INVALID_PARAMS, BAD_ADDRESS, BAD_LIMIT, BAD_HOURS, …).

application/json

Every non-2xx body.

object

error

required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string

message

For humans.

string

statusCode

HTTP status, when included.

integer

Example

{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}