Show a customer their wallets and balances

List every wallet a customer holds with its coin balances in one call, and add them up as decimals for a balances screen.

This recipe lists every wallet a customer holds, with its coin balances, in one call, and adds the balances up as decimals for a balances screen. It is for a wallet app that is building a "My balances" screen.

Status. Available.

Money example

Ada has a Polygon wallet holding 250 USDC and a Stellar wallet holding 120 USDC.
One list call returns both wallets, with their balances.
Your screen shows "USDC 370 across 2 wallets".

Before you start

You have the customer id. Reading wallets needs no permission.

Find out what is required

Filter	Use
`customer_id`	One customer's wallets
`network`	One network, in lower case
`wallet_address`	One address, exactly as Gravv returned it
`wallet_name`	A name you set (not the generated label)
`wallet_type`	`customer` or `master`
`include_balances`	`true` adds `assets` to each item
`page`, `items_per_page`	Up to 100 per page

Steps

1. List the wallets with their balances

curl --request GET \
 --url 'https://api.gravv.xyz/v1/wallets?customer_id=401d68fb-fe97-4c56-84a6-5651cdbde747&include_balances=true&items_per_page=50' \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/wallets?customer_id=401d68fb-fe97-4c56-84a6-5651cdbde747&include_balances=true&items_per_page=50", {
method: "GET",
headers: {
"Api-Key": process.env.GRAVV_API_KEY,
},
});
console.log(response.status, await response.json());

import os

import requests

response = requests.get(
"https://api.gravv.xyz/v1/wallets?customer_id=401d68fb-fe97-4c56-84a6-5651cdbde747&include_balances=true&items_per_page=50",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

{
  "data": {
    "items": [
      {
        "id": "30803889-fa61-4774-8d11-8e3781728a07",
        "address": "GBJPEJTFUYGBFUUJDBOZKDXIQE3ASFTPNMIT2F4NNQH5HEA76I42CH5P",
        "network": "stellar",
        "name": "Ada USDC",
        "date_created": "2026-10-13T10:02:41Z",
        "customer_id": "401d68fb-fe97-4c56-84a6-5651cdbde747",
        "wallet_type": "customer",
        "assets": [{ "symbol": "USDC", "balance": "120.0000000", "decimals": 7, "updated_at": "2026-10-13T10:20:05Z" }]
      },
      {
        "id": "bbab27f6-04b8-457d-83ed-b92009758340",
        "address": "0xc47B2D22812ee674Ee5182320FCCA83854f21962",
        "network": "polygon",
        "name": "Ada top-up wallet",
        "date_created": "2026-10-13T09:14:03Z",
        "customer_id": "401d68fb-fe97-4c56-84a6-5651cdbde747",
        "wallet_type": "customer",
        "assets": [{ "symbol": "USDC", "balance": "250.000000", "decimals": 6, "updated_at": "2026-10-13T09:31:20Z" }]
      }
    ],
    "page": 1,
    "items_per_page": 50,
    "total_items": 2,
    "total_pages": 1,
    "has_next_page": false,
    "has_previous_page": false
  },
  "error": null
}

The list returns the newest wallet first. Without include_balances=true, items carry no assets. If you ask for an items_per_page above 100, you get 100, so read the value back from the response. Page until has_next_page is false.

2. Add up the balances

Add balances as decimal strings, never as floats. For example, 250.000000 plus 120.0000000 is 370. Treat a missing coin as "unknown", not 0. If an item has "stale": true, show "updating" and read that wallet again later with GET /v1/wallets/{wallet_id}.

What can go wrong

Response	Why	Fix
400 `invalid request payload`	`page` or `items_per_page` is not a number, `include_balances` is not `true` or `false`, or you sent a `wallet_ids` filter	Send numbers and `true` or `false`. Do not use `wallet_ids`
An empty list for `network=Polygon`	Filters are exact and case-sensitive	Send `network=polygon`
An empty list for a lower-case `0x…` address	Gravv stores EVM addresses in checksum (mixed) case	Use the address exactly as Gravv returned it
`wallet_name` finds nothing	It matches only names you set	Filter by `customer_id`
400 `wallet not found` on one wallet	The id is unknown or from the other environment	Use an id from the same environment