---
title: "List and read accounts"
description: "List your accounts with GET /v2/accounts, read one with GET /v2/accounts/{id}, and give payers the right bank details."
---
**API version:** v2.

Use these calls to read one account, give payers its bank details, read its balances and list accounts.

**A money example.** Ada's USD account is `active`. You read it and show her client the bank name, beneficiary name, account number and routing number. The client sends 1,200.00 USD by ACH, and the next read shows the new `balance`.

## Read one account

```bash title="Read an account"
curl --request GET \
     --url https://api.gravv.xyz/v2/accounts/6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11 \
     --header 'Api-Key: <API_KEY>'
```

```json title="Active USD account"
{
  "data": {
    "id": "6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11",
    "status": "active",
    "currency": "USD",
    "category": "sub_account",
    "wallet_address": "0x5a3e9b0c7d2f41e8a6b4c3d2e1f0a9b8c7d6e5f4",
    "blockchain_network": "polygon",
    "virtual_account_bank_name": "Example Bank NA",
    "virtual_account_bank_account_number": "9876543210",
    "virtual_account_bank_routing_number": "123456780",
    "virtual_account_bank_beneficiary_name": "Ada Okafor",
    "balance": "0",
    "balance_source": "wallet",
    "settlement_enabled": false,
    "application_id": "5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6"
  },
  "error": null
}
```

## Bank details to give the payer

Bank details exist only once the account is `active`.

| Account | `virtual_account_bank_account_number` | `virtual_account_bank_routing_number` | Also show |
| :-- | :-- | :-- | :-- |
| USD | US account number | ABA routing number | `virtual_account_bank_name`, `virtual_account_bank_address`, `virtual_account_bank_beneficiary_name`, `virtual_account_bank_beneficiary_address` |
| EUR, wallet-backed | IBAN | BIC | bank name, beneficiary name |
| GBP, wallet-backed | UK account number | sort code | bank name, beneficiary name |
| EUR or GBP, fiat-only (one IBAN) | the full IBAN | sort code | `virtual_account_bank_metadata.bic`. For a UK Faster Payment, the 8-digit account number is the last 8 characters of the IBAN |
| NGN | 10-digit account number | empty | bank name, beneficiary name |
| KES | account number | empty | bank name |
| Any wallet-backed account | | | `wallet_address` and `blockchain_network`. The payer must send only USDC on that network |

- `bank_name` and `bank_code` say which option holds the account. `virtual_account_bank_name` is the bank the payer names. The two can differ.
- A fiat-only USD account for a US resident has no `virtual_account_bank_name` or `virtual_account_bank_address` today, so show `bank_name`. Those two fields are not yet live on that account.
- The payer can use the rails in the option's `rails` list in [capabilities](/platform/accounts/find-an-account-option).

## Balances

- `balance_details.available` is the amount available to spend now. Use it when it is present.
- `balance` is in major units (dollars, euros). `balance_source` says where Gravv read it, `wallet` or `institution`.
- `ledger_balance.posted` and `ledger_balance.projected` are in **minor units**. With `scale` 2, `120000` is 1,200.00. Never show them as major units.

## List accounts

[`GET /v2/accounts`](/api-reference/accounts-v2/get-v2-accounts) lists all your accounts, newest first.

```bash title="List a customer's USD accounts"
curl --request GET \
     --url 'https://api.gravv.xyz/v2/accounts?customer_id=0b6f3c1e-2a4d-4c8e-9f10-7d2a6b5e4c33&currency=USD&limit=50&offset=0' \
     --header 'Api-Key: <API_KEY>'
```

```json title="List response"
{
  "data": {
    "items": [],
    "items_per_page": 50,
    "page": 1,
    "total_items": 0,
    "total_pages": 0
  },
  "error": null
}
```

You can filter by `customer_id`, `excluded_customer_id`, `status`, `category`, `currency`, `network`, `bank_code`, `label` (exact match), `type`, `search`, `created_from` and `created_to`. To find your business's own account and its customer id, filter by `category=main`. Page through the results with `limit` (1 to 200, default 50) and `offset`. Only these parameters work. Any other parameter returns 400 `invalid request payload: unknown field "…"`, and a `limit` that is not a whole number returns 400.

## Applications

`GET /v2/accounts/applications` lists applications, filtered by `customer_id` and `status` (lower case), with `limit` and `offset`. Its `count` is the number of items on the page, not a total. Applications not made with `POST /v2/accounts` appear too, and can have the status `draft` or `submitted`. Sandbox may not show them.