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

# Get finalized user balances

> Read all finalized balances or select one token.

<Info>Response JSON below is an illustrative testnet snapshot, not a live mainnet result. Use the selected server and its network-specific addresses for actual requests.</Info>

<ParamField path="userId" type="string" required>
  Unsigned decimal Kuru user ID.
</ParamField>

<ParamField query="tokenAddress" type="string">
  Optional lowercase 20-byte token address. When present, `data` contains zero
  or one matching balance.
</ParamField>

<ResponseField name="feedEpoch" type="integer | null" required>
  Feed epoch containing `globalUserSeq`.
</ResponseField>

<ResponseField name="data" type="array" required>
  Up to 2,000 balances ordered by token address, or zero to one entry when
  `tokenAddress` is supplied.
</ResponseField>

<ResponseField name="globalUserSeq" type="string | null" required>
  Finalized user sequence covered by the snapshot.
</ResponseField>

<ResponseField name="truncated" type="boolean" required>
  `true` when additional balances were omitted from an unfiltered request.
</ResponseField>

`total`, `available`, and `reserved` use the token's native decimal units, and
`total = available + reserved`. When both cursor fields are non-null, install
the snapshot and subscribe to `userBalances@f` with the same `feedEpoch` and
`globalUserSeq`.

<ResponseExample>
  ```json 200 theme={null}
  {
    "feedEpoch": 18,
    "data": [
      {
        "tokenAddress": "0xb01dc575a7ef75e58a05d2bde73ab79f8e7dd0be",
        "total": "9072874016",
        "available": "9072874016",
        "reserved": "0"
      }
    ],
    "state": "finalized",
    "servedView": "finalized",
    "globalUserSeq": null,
    "truncated": false
  }
  ```
</ResponseExample>


## OpenAPI

````yaml api/data-source/openapi.yaml GET /api/v1/users/{userId}/balances
openapi: 3.1.0
info:
  title: Kuru Data Source API
  version: 1.0.0
servers:
  - url: https://api.mainnet.kuru.io
    description: Monad mainnet (default)
  - url: https://api.testnet.kuru.io
    description: Monad testnet
security: []
paths:
  /api/v1/users/{userId}/balances:
    get:
      summary: Get user balances
      operationId: getUserBalances
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: tokenAddress
          in: query
          schema:
            type: string
      responses:
        '200':
          description: User balances

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.