# Account Balances Tutorial
URL: https://www.quiltt.dev/get-started/tutorials/account-balances
Description: Build an account dashboard that lists a user's connected accounts and displays their balances with Quiltt's GraphQL API. Complete React tutorial with code examples.
Navigation: get-started → tutorials → account-balances
Tags: Tutorials, Accounts, Balances
Content Length: 8k characters

Once a user connects a bank, the first thing most apps show is their accounts and balances. This tutorial builds a React dashboard that queries a Profile's connected accounts, displays each balance, and computes a net total across every account.

**Time:** ~10 minutes

**Framework:** React (concepts apply to any client)

## What you'll build

A dashboard that:

1. Queries the connected accounts for a Profile
2. Displays each account with its institution, type, and balance
3. Formats balances correctly for asset and liability accounts
4. Computes a net total across every account

## Balances explained

Every Account in Quiltt exposes a `balance` with three amounts:

| Field | Meaning |
| ----- | ------- |
| `current` | The balance based on posted transactions |
| `available` | The balance accounting for pending transactions |
| `limit` | The overdraft or credit limit, when the provider reports one |

Quiltt normalizes the sign of these amounts across providers, so the same convention applies regardless of the upstream source:

- **Asset accounts** (checking, savings, investment): a positive balance means money in the account.
- **Liability accounts** (credit cards, loans): a negative balance means the amount owed.

Because the signs are consistent, summing every account's `current` balance produces a true net figure — assets add and liabilities subtract. You'll use this to compute a net total in step 4.

## Prerequisites

- [Quiltt Dashboard](https://dashboard.quiltt.dev) account ([sign up](https://dashboard.quiltt.dev/signup))
- A React app with `QuilttAuthProvider` set up and at least one connected account. If you don't have this yet, complete the [Authentication Tutorial](/get-started/tutorials/authentication) first — it wires up the provider and launches the Connector.
- Node.js 18 or higher

This tutorial continues from the [Authentication Tutorial](/get-started/tutorials/authentication), reusing its `QuilttAuthProvider` and GraphQL client.

## Build the dashboard

### 1. Explore the query

Before writing any code, test the query in the GraphQL Explorer (Dashboard → Profiles → select a Profile). The `accounts` query returns every account on the Profile:

GraphQLRequest:

Query:
```graphql
query GetAccounts {
  accounts {
    id
    name
    mask
    kind
    currencyCode
    institution {name}
    balance [current
      available
      limit
      at]
  }
}
```

  

Response:
```json
{
  "data": {
    "accounts": [
      {
        "id": "acct_12sf19AeKaWfukStXAL7nN",
        "name": "Premium Checking",
        "mask": "3141",
        "kind": "DEPOSITORY",
        "currencyCode": "USD",
        "institution": ["name": "MX Bank"],
        "balance": ["current": 3141.59,
          "available": 3000.0,
          "limit": null,
          "at": "2024-06-09T07:40:20Z"]
      },
      {
        "id": "acct_12vAFU1c4t514E40Nb9NTW",
        "name": "Premium Credit Card",
        "mask": "2134",
        "kind": "CREDIT",
        "currencyCode": "USD",
        "institution": ["name": "MX Bank"],
        "balance": ["current": -2134.34,
          "available": 12665.66,
          "limit": -15000.0,
          "at": "2024-06-01T18:55:35Z"]
      }
    ]
  }
}
```

The credit card's `current` of `-2134.34` means the user owes **$2,134.34**. See the [Account Balances reference](/api/balances#balance-values-by-account-type) for the full sign convention.

### 2. Format balances

Balances are plain numbers, so format them with the account's `currencyCode`. Create a helper that renders any amount in the account's currency:

```tsx
// lib/formatCurrency.ts

  if (amount === null) return '—'

  return new Intl.NumberFormat('en-US', [style: 'currency',
    currency: currencyCode,]).format(amount)
}
```

A `balance` can be `null` when a Connection is still syncing, so this helper returns a placeholder rather than crashing.

### 3. Fetch and render accounts

Query the accounts with `useQuery` and render each one. This reuses the GraphQL client from the [Authentication Tutorial](/get-started/tutorials/authentication):

```tsx
// components/AccountList.tsx
'use client'

const ACCOUNTS_QUERY = gql`
  query GetAccounts {
    accounts {
      id
      name
      mask
      kind
      currencyCode
      institution {name}
      balance [current
        available
        at]
    }
  }
`

  const client = useQuilttClient()
  const [data, loading, error] = useQuery(ACCOUNTS_QUERY, {client})

  if (loading) return Loading accounts...
  if (error) return Couldn't load accounts. Try again.

  const accounts = data?.accounts ?? []

  if (accounts.length === 0) [return No connected accounts yet. Launch the Connector to add one.]

  return (
    
{accounts.map((account) => (
        • [account.name]
              {account.mask && ••[account.mask]}
            [account.institution.name] · [account.kind]
          [formatCurrency(account.balance?.current ?? null, account.currencyCode)]

      ))}

  )
}
```

### 4. Add a net total

Sum each account's `current` balance to show a net total. Because Quiltt normalizes the sign, liabilities subtract automatically:

```tsx
// components/AccountList.tsx (add above the return)
const netTotal = accounts.reduce(
  (total, account) => total + (account.balance?.current ?? 0),
  0,
)

const currencyCode = accounts[0]?.currencyCode ?? 'USD'
```

Render it above the list:

```tsx
Net total
  [formatCurrency(netTotal, currencyCode)]
```

Warning:
The net total is only meaningful when every account shares one currency. If a Profile holds accounts in multiple currencies, group by `currencyCode` and show a total per currency instead of one combined figure.

### 5. Add the dashboard to your page

Drop the `AccountList` component into the page you built in the Authentication Tutorial:

```tsx
// app/page.tsx
'use client'

const CONNECTOR_ID = process.env.NEXT_PUBLIC_QUILTT_CONNECTOR_ID

    [AccountList]

      

QuilttButton:
Connect another account

  )]
```

## Verification

1. Start your dev server and open [http://localhost:3000](http://localhost:3000).
2. Confirm each connected account appears with its institution, type, and balance.
3. Check that a credit card or loan shows a negative balance and that the net total reflects it.
4. Connect another account with the Connector, then refresh — the new account appears in the list.

## Troubleshooting

| Problem | Cause | Fix |
| ------- | ----- | --- |
| `accounts` is empty | The Profile has no connected accounts, or the token is for a different Profile | Connect an account, and confirm the Session token belongs to the right Profile. |
| Balance shows `—` | The Connection is still syncing, so `balance` is `null` | Wait for the `connection.synced.successful` webhook, then re-query. |
| All balances read `$0.00` | Balances aren't formatted with the account's currency | Pass `account.currencyCode` to `formatCurrency`. |
| Net total looks wrong | Accounts span multiple currencies | Group by `currencyCode` and total each currency separately. |

## Next steps

You now display connected accounts and balances. To keep balances fresh for payment flows, [trigger a real-time balance refresh](/api/balances#trigger-a-balance-refresh) and listen for the `balance.created` webhook.

### Related tutorials

- [Authentication Tutorial](/get-started/tutorials/authentication) - Session token setup and management
- [Multi-Aggregator Connectors Tutorial](/get-started/tutorials/connectors) - Build a full connection flow
- [Syncing Transactions](/get-started/tutorials/transaction-sync) - Keep transaction data in sync with webhooks

### Reference documentation

- [Accounts API reference](/api/accounts) - Fields, filters, and mutations
- [Account Balances reference](/api/balances) - Balance sign conventions and real-time refresh
- [GraphQL API reference](/api/graphql) - Available queries and mutations

### Questions?

[Contact support](mailto:support@quiltt.io)