Retrieve wallets

List a customer's wallets with their balances, or read one wallet. Balances are cached decimal strings.

Get wallets lists wallets, newest first. Get a single wallet reads one, with its balances. Reading wallets needs no key permission.

Example. Ada has a Polygon wallet with 250 USDC and a Stellar wallet with 120 USDC. One list call with include_balances=true returns both, and your screen shows "USDC 370 across 2 wallets". Add the balances as decimal strings, not floats.

List a customer's wallets

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>'

{
  "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
}

Query	What it does
`customer_id`	One customer's wallets
`network`	One network, in lower case
`wallet_address`	One address, exactly as Gravv returned it (case-sensitive)
`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`	Page until `has_next_page` is `false`. A value above 100 returns 100 items per page, so read `items_per_page` back from the response

Filters other than wallet_name are exact and case-sensitive, so network=Polygon returns nothing.

Read one wallet

curl --request GET \
     --url https://api.gravv.xyz/v1/wallets/bbab27f6-04b8-457d-83ed-b92009758340 \
     --header 'Api-Key: <API_KEY>'

The response is the wallet with its assets. Each asset has symbol, balance (a decimal string), decimals and updated_at.

Gravv caches balances. A missing coin means "not read yet", not zero.
stale true means the balance is older than 5 minutes and Gravv has queued a refresh. Read the wallet again a few seconds later.
USDC has 6 decimals on EVM networks and 7 on Stellar.

What can go wrong

Response	Why	Fix
400 `wallet not found`	Unknown id, or an id from the other environment (sandbox or live)	Use an id from the same environment
400 `invalid request payload`	A `page` or `items_per_page` that is not a number, or `include_balances` that is not `true`/`false`	Fix the value
An empty list	A filter in the wrong case	Send values exactly as Gravv returns them