Balances of tokens

The endpoint provides token balances for selected addresses.
Request params allow to precisely select tokens to fetch.
And request params allow to configure the range of interested addresses,
including the filtering by prameters of blockchain addresses such as type of address, app agent ID, TA ID etc.
Response contains the list of matching token transfers.

Request

Body Params application/json

Request

optional

Any of

TokensBalancesRequest

NextPageRequest

Request params for the endpoint /tokens/balances.

Example:

{"block":"blockchain_head","owner":"ttnCSi8iaGuFXTRvdrzn17cVyUfnHeWqF91sdksdXB19V9y4j","token":[{"token_type":"nft","nft_collection_id":17},"TRAIT"]}

block

Block

optional

ID of the block for which the blockchain state will be provided.

owner

Owner

optional

Filter by token owners. This filter allows to select the addresses to fetch balances of.

token

Token

optional

Filter by token. This filter allows to select the tokens to fetch balances of.

presentation

object

TokensBalancesPresentation

optional

Configuration of output for the endpoint /tokens/balances.

Example

Responses

🟢200OK

application/json

Successful Response

Body

Response schema for the endpoint `/tokens/balances`.

metadata

object (ResponseMetadataPaged)

required

Metadata for the generated response.

request_context

object (ResponseBlockId)

required

For the endpoints with historical data: the last block, the data from which is included in the response. For the endpoints with blockchain state data: the block whose state is provided in the response. Request context remains the same for all data pages in the series for the initial request.

blockchain_head

object (ResponseBlockId)

required

The latest blockchain block currently available.

pagination

object (ResponsePaginationData)

required

Pagination info for the generated response.

data

array [anyOf]

Data

required

object (TokenBalanceNative)

optional

Balance of TRAIT token.

object (TokenBalanceFungible)

optional

Balance of fungible token.

object (TokenBalanceNft)

optional

Balance of NFT.

Example

{
  "metadata": {
    "request_context": {
      "block_hash": "0xab8006019066f080402ab43da043127b930ef0ffb3349a333222d67c0f542338",
      "block_index": 29702,
      "block_timestamp": 1727581488000
    },
    "blockchain_head": {
      "block_hash": "0xab8006019066f080402ab43da043127b930ef0ffb3349a333222d67c0f542338",
      "block_index": 29702,
      "block_timestamp": 1727581488000
    },
    "pagination": {
      "current_page": 0,
      "next_page_id": "109924cd-b827-4eb1-8901-1f45d2d753e9"
    }
  },
  "data": [
    {
      "token_type": "TRAIT",
      "owner": {
        "address": "ttodYEVA917tPqpseDdLP4NhMJUkCQHJU4T7zcT4TCYM3PKxQ",
        "account_id": "0x6d6f646c506f745374616b650000000000000000000000000000000000000000",
        "address_type": "regular",
        "app_agent_id": null,
        "ta_id": null,
        "address_name": null
      },
      "owner_balance": -28394434091
    },
    {
      "token_type": "TRAIT",
      "owner": {
        "address": "ttn8KQhZ3gsKkryZoKWFdGnEV4C5WDhpyXinEVQVu1v2HA7Xs",
        "account_id": "0x2ae9df7cc0678eb17e196ab2638689eefebfffe3c7c75b7f5bb8ccb501a25f7f",
        "address_type": "regular",
        "app_agent_id": null,
        "ta_id": null,
        "address_name": null
      },
      "owner_balance": 28394437491
    },
    {
      "token_type": "fungible",
      "fungible_token_id": 32,
      "fungible_token_manager": {
        "address": "ttmMsYRqsnrKY5DNTZY3rBCUHq7s191wKvWQXnrfb7xeADJGC",
        "account_id": "0x0904000001d5006fd044601bad51baedee11be3f4247c688310084e17d778170",
        "address_type": "app_agent",
        "app_agent_id": 1033,
        "ta_id": null,
        "address_name": null
      },
      "owner": {
        "address": "ttrENnXUfsdTDFwweKjK1dSvCXcAtVVQ9xgARy8iBisAFfc5e",
        "account_id": "0xe079a519da31f627a19daf986c30d63ea24c6ce8762a19487d88077aaf1cc033",
        "address_type": "regular",
        "app_agent_id": null,
        "ta_id": null,
        "address_name": null
      },
      "owner_balance": 45
    },
    {
      "token_type": "fungible",
      "fungible_token_id": 32,
      "fungible_token_manager": {
        "address": "ttmMsYRqsnrKY5DNTZY3rBCUHq7s191wKvWQXnrfb7xeADJGC",
        "account_id": "0x0904000001d5006fd044601bad51baedee11be3f4247c688310084e17d778170",
        "address_type": "app_agent",
        "app_agent_id": 1033,
        "ta_id": null,
        "address_name": null
      },
      "owner": {
        "address": "ttnHxmq7B2xwZnG28puQCw8kgxsXY4yKvucRzRHqJq2gftLW6",
        "account_id": "0x3244dc7318398fe43dd214d0ffdd1f8d0603a73fc286f4d758caaf5bbfddf702",
        "address_type": "regular",
        "app_agent_id": null,
        "ta_id": null,
        "address_name": null
      },
      "owner_balance": 55
    },
    {
      "token_type": "nft",
      "nft_collection_id": 17,
      "nft_collection_manager": {
        "address": "ttmMsYRqsnrKY5DNTZY3rBCUHq7s191wKvWQXnrfb7xeADJGC",
        "account_id": "0x0904000001d5006fd044601bad51baedee11be3f4247c688310084e17d778170",
        "address_type": "app_agent",
        "app_agent_id": 1033,
        "ta_id": null,
        "address_name": null
      },
      "nft_item_id": 754266,
      "owner": {
        "address": "ttnCSi8iaGuFXTRvdrzn17cVyUfnHeWqF91sdksdXB19V9y4j",
        "account_id": "0x2e0f6e39e5306a3905d31c3edff91c53059ddfbd4ec7fe93ea515b5b3bad7e29",
        "address_type": "regular",
        "app_agent_id": null,
        "ta_id": null,
        "address_name": null
      }
    }
  ]
}

🟠422Parameter Error

Request

Request samples

Responses