> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ralphstudio.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying an Address Balance

> Get ALPH and token balances for any Alephium address.

This guide shows how to fetch the balance of an Alephium address both the native ALPH amount and any tokens held.

## Get the ALPH balance

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{your-slug}/addresses/{address}/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "balance": "2000000000000000000",
  "lockedBalance": "0",
  "utxoNum": 3
}
```

All amounts are in **attoALPH** the smallest unit of ALPH. To convert to ALPH divide by `10^18`.

| attoALPH              | ALPH     |
| --------------------- | -------- |
| `1000000000000000000` | 1 ALPH   |
| `2000000000000000000` | 2 ALPH   |
| `500000000000000000`  | 0.5 ALPH |

`lockedBalance` is ALPH that exists in outputs with a future `lockTime` it belongs to the address but cannot be spent yet. `utxoNum` is the number of unspent outputs the balance is spread across.

## Get token balances

The raw node balance endpoint only returns ALPH. To get token balances use the indexer:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{your-slug}/indexer/addresses/{address}/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "balance": "2000000000000000000",
  "lockedBalance": "0",
  "tokenBalances": [
    {
      "tokenId": "b2d71c116408ae47a83c6db0571a1b2d1f58dc87ac5d7e8e4c2a3d1f9e0b8c4",
      "balance": "500000000",
      "lockedBalance": "0"
    }
  ]
}
```

Token amounts use the token's own decimal precision not `10^18`. Always fetch the token metadata to get the correct `decimals` value before displaying an amount to a user.

## Get token metadata

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{your-slug}/indexer/tokens/{token-id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "id": "b2d71c...",
  "symbol": "USDT",
  "name": "Tether USD",
  "decimals": 6,
  "totalSupply": "1000000000000"
}
```

With `decimals: 6`, a raw balance of `500000000` equals `500 USDT`.

## Get all tokens held by an address

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{your-slug}/indexer/addresses/{address}/tokens" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
[
  {
    "tokenId": "b2d71c...",
    "balance": "500000000",
    "lockedBalance": "0"
  },
  {
    "tokenId": "c3e82d...",
    "balance": "1",
    "lockedBalance": "0"
  }
]
```

A balance of `"1"` almost always means the token is an NFT. Fungible tokens on Alephium typically have amounts well above `1` even after accounting for decimals.

## Get UTXOs for an address

If you need to build a transaction manually you need the raw UTXOs, not just the balance:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{your-slug}/addresses/{address}/utxos" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "utxos": [
    {
      "ref": {
        "hint": 123456,
        "key": "798e9e137aec7c2d59d9655b4ffa640f301f628bf7c365083bb255f6aa5f89ef"
      },
      "output": {
        "hint": 1,
        "key": "798e9e...",
        "attoAlphAmount": "2000000000000000000",
        "address": "1DrDyTr9...",
        "tokens": [],
        "lockTime": 0,
        "message": ""
      }
    }
  ]
}
```

Each entry in `utxos` is a spendable output. The SDK handles UTXO selection automatically when you use `transactions/build` you only need this endpoint if you are constructing raw transactions yourself.

## Check if a node is synced before querying

Balances returned by an unsynced node will be stale. Check sync status first:

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{your-slug}/infos/self-clique" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "cliqueId": "...",
  "networkId": 0,
  "numZerosAtLeastInHash": 37,
  "nodes": [
    {
      "address": "...",
      "restPort": 12973,
      "wsPort": 11973,
      "minerApiPort": 10973,
      "isSynced": true,
      "isCompactingMerkleTree": false,
      "clientVersion": "v3.0.0"
    }
  ]
}
```

Only proceed with balance queries when `isSynced` is `true`.

## Parameters reference

| Parameter | Type   | Description                     |
| --------- | ------ | ------------------------------- |
| address   | string | Base58-encoded Alephium address |
| token-id  | string | Token contract address          |

## Next steps

<CardGroup cols={2}>
  <Card title="Submit a transaction" icon="paper-plane" href="/guides/submitting-transaction">
    Build, sign, and broadcast a transfer
  </Card>

  <Card title="Read a contract" icon="file-code" href="/guides/reading-contracts">
    Call view functions on deployed contracts
  </Card>
</CardGroup>