<!-- source: https://secondlayer.tools/docs/api-reference#list-rune-balances -->

## Rune balances by address or outpoint

`GET /v1/index/runes/balances`

Current per-outpoint rune balances. Exactly one of `address` or `outpoint` is required; `rune` narrows either to one rune. Returns balances[], next_cursor, tip.

### Filters

| Name | Type | Description |
| --- | --- | --- |
| `address` | string | Mainnet Bitcoin address. Mutually exclusive with `outpoint`; exactly one is required. |
| `outpoint` | string | `<txid>:<vout>`. Mutually exclusive with `address`; exactly one is required. |
| `rune` | string | A rune id (`<block>:<tx>`, e.g. `840000:3`) or name — spacers and case are ignored, so `DOG•GO•TO•THE•MOON`, `dog.go.to.the.moon` and `doggotothemoon` are the same rune. Narrows the result to one rune. |

### Range and paging

| Name | Type | Description |
| --- | --- | --- |
| `cursor` | string | Opaque token from a previous page's `next_cursor`. Resumes after it — pass back unchanged. |
| `limit` | integer · 1 to 1000 | Page size; capped at 1000. |

### Returns

A cursor envelope; `balances` holds `RuneBalance` objects.

### Responses

- `200` Cursor-paginated envelope
- `400` A parameter, filter, cursor or body field was refused; `code` says which
- `401` This bind requires the instance token, and it was missing or wrong
- `429` Rate limited; retry after `Retry-After` seconds

### Example

```bash
curl -G https://api.secondlayer.tools/v1/index/runes/balances \
  -H "Authorization: Bearer $SECONDLAYER_API_KEY" \
  -d outpoint=2d2b54008790a44c9c3e630faa521a50f8ab122625c4eb8fb84705051c4fc611:0 \
  -d rune=840000:3
```

```json
{
  "balances": [
    {
      "rune": {
        "id": "840000:3",
        "name": "DOGGOTOTHEMOON",
        "spaced_name": "DOG•GO•TO•THE•MOON",
        "symbol": "🐕",
        "divisibility": 5
      },
      "address": "bc1phnp234rd5hel0h8ulqvnq3zrww2td0a8q48hjcg7mv67j97jnxfq9ayczm",
      "txid": "2d2b54008790a44c9c3e630faa521a50f8ab122625c4eb8fb84705051c4fc611",
      "vout": 0,
      "amount": "88980600"
    }
  ],
  "tip": {
    "block_height": 968925,
    "finalized_height": 968919,
    "lag_seconds": 210
  },
  "reorgs": [
    {
      "id": "7",
      "detected_at": "2026-08-11T04:22:10.000Z",
      "fork_point_height": 851203,
      "old_hash": "0000000000000000000123abc1230000000000000000000000000000000000",
      "new_hash": "0000000000000000000456def4560000000000000000000000000000000000",
      "orphaned_from": 851203,
      "orphaned_to": 851204,
      "new_tip_height": 851205
    }
  ]
}
```