Querying an Address Balance

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

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

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

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

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

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

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

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

[
  {
    "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:

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

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

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

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

Guides

Querying an Address Balance

Get the ALPH balance

Get token balances

Get token metadata

Get all tokens held by an address

Get UTXOs for an address

Check if a node is synced before querying

Parameters reference

Next steps

Submit a transaction

Read a contract

​Get the ALPH balance

​Get token balances

​Get token metadata

​Get all tokens held by an address

​Get UTXOs for an address

​Check if a node is synced before querying

​Parameters reference

​Next steps

Submit a transaction

Read a contract

Get the ALPH balance

Get token balances

Get token metadata

Get all tokens held by an address

Get UTXOs for an address

Check if a node is synced before querying

Parameters reference

Next steps