> ## 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.

# Addresses

> Query address info, balances, and activity from the Alephium indexer.

The indexer address endpoints give you a more complete view of an address than the raw node. You get full transaction history, token balances with metadata, and activity summaries, all paginated and sorted by the indexer.

## Get address info

Returns a summary of an address including its balance, transaction count, and token holdings.

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

```json theme={null}
{
  "address": "1DrDyTr9...",
  "balance": "1000000000000000000",
  "lockedBalance": "0",
  "txNumber": 42,
  "group": 0
}
```

## Get address balance

Returns the current ALPH balance and token balances for an address.

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

```json theme={null}
{
  "balance": "1000000000000000000",
  "lockedBalance": "0",
  "tokenBalances": [
    {
      "tokenId": "b2d71c...",
      "balance": "500000000000000000",
      "lockedBalance": "0"
    }
  ]
}
```

## Get address transactions

Returns paginated transaction history for an address sorted by timestamp descending.

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/indexer/addresses/{address}/transactions?page=1&limit=20" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
[
  {
    "hash": "503a2c...",
    "blockHash": "00000000ab3c...",
    "timestamp": 1748476800000,
    "inputs": [...],
    "outputs": [...],
    "gasAmount": 20000,
    "gasPrice": "100000000000",
    "scriptExecutionOk": true,
    "coinbase": false
  }
]
```

## Get address token transactions

Returns transactions involving a specific token for an address. Useful for tracking token transfers in and out.

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/indexer/addresses/{address}/tokens/{token-id}/transactions?page=1&limit=20" \
  -H "Authorization: Bearer API_KEY"
```

## Get all tokens held by an address

Returns a list of all token IDs held by an address with their balances.

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

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

A balance of `"1"` on a token typically means it's an NFT, fungible tokens usually have amounts in the range of `10^18`.

## Get address mempool transactions

Returns unconfirmed transactions for an address currently sitting in the mempool.

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

```json theme={null}
[
  {
    "hash": "604b3d...",
    "chainFrom": 0,
    "chainTo": 0,
    "inputs": [...],
    "outputs": [...],
    "gasAmount": 20000,
    "gasPrice": "100000000000"
  }
]
```

## Get address contract events

Returns contract events where the address appears as a field value. Useful for tracking activity involving a specific address across multiple contracts.

```bash theme={null}
curl "https://rpc.ralphstudio.xyz/{slug}/indexer/addresses/{address}/events?start=0&limit=20" \
  -H "Authorization: Bearer API_KEY"
```

```json theme={null}
{
  "events": [
    {
      "blockHash": "00000000ab3c...",
      "txId": "503a2c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [
        {
          "type": "Address",
          "value": "1DrDyTr9..."
        },
        {
          "type": "U256",
          "value": "1000000000000000000"
        }
      ]
    }
  ],
  "nextStart": 20
}
```

## Tracking deposits to an address

A common use case is monitoring when an address receives a payment. The recommended approach is to poll the transaction history endpoint and compare against the last seen transaction hash:

```javascript theme={null}
const BASE = "https://rpc.ralphstudio.xyz/{slug}/indexer";
const API_KEY = "API_KEY";

async function getLatestTransactions(address) {
  const res = await fetch(
    `${BASE}/addresses/${address}/transactions?page=1&limit=10`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  return res.json();
}
```

For a production setup, save the timestamp of the last processed transaction and filter results newer than that timestamp.

## Parameters reference

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| address   | string  | Base58-encoded Alephium address          |
| token-id  | string  | Token contract address                   |
| page      | integer | Page number (default: 1)                 |
| limit     | integer | Results per page (default: 20, max: 100) |
| start     | integer | Event offset for pagination              |