HIP-873: Adding Decimal Information to Token Balance Calls in the Hedera REST API

Abstract

This HIP proposes an enhancement (with backwards compatibility) to the Hedera REST API to include decimal information in the token balance queries. Currently, users face challenges in accurately determining token balances due to the absence of decimal details in the /tokens, /api/v1/tokens/{tokenId}/balances, and /account/{idOrAliasOrEvmAddress}/tokens endpoints. This proposal aims to reduce the number of API calls needed and streamline the process of retrieving comprehensive token information.

Motivation

This HIP, aligned with HIP-367’s initiative to deprecate HAPI queries, seeks to ensure that mirror node APIs offer comparable functionality. Retrieving token balance information without decimal details currently necessitates multiple API calls, leading to inefficiencies and a heightened computational load. By integrating decimal details into balance queries, this proposal aims to streamline the process, significantly reducing the time, cost, and complexity involved, crucial for accurate token balance determination.

Specification

The proposed solution involves modifying the response structure of three endpoints:

Route:
/api/v1/tokens

Current Response Structure:

{
  "tokens": [
    {
      "admin_key": null,
      "symbol": "PEC_E",
      "token_id": "0.0.732556",
      "type": "NON_FUNGIBLE_UNIQUE"
    }
  ],
  "links": {
    "next": null
  }
}

Proposed Response Structure:

{
  "tokens": [
    {
      "admin_key": null,
      "symbol": "PEC_E",
      "name": "[Token Name]",
      "token_id": "0.0.732556",
      "type": "NON_FUNGIBLE_UNIQUE",
      "decimals": 3
    }
  ],
  "links": {
    "next": null
  }
}

Route:
/api/v1/tokens/{tokenId}/balances

Current Response Structure:

{
  "timestamp": "1586567700.453054000",
  "balances": [
    {
      "account": "0.15.2",
      "balance": 1000
    }
  ],
  "links": {
    "next": null
  }
}

Proposed Response Structure:

{
  "timestamp": "1586567700.453054000",
  "balances": [
    {
      "account": "0.15.2",
      "balance": 1000,
      "decimals": 3
    }
  ],
  "links": {
    "next": null
  }
}

Route:
/api/v1/accounts/{idOrAliasOrEvmAddress}/tokens

Current Response Structure:

{
  "tokens": [
    {
      "automatic_association": true,
      "balance": 0,
      "created_timestamp": "123456789.000000001",
      "freeze_status": "UNFROZEN",
      "kyc_status": "GRANTED",
      "token_id": "0.0.732556"
    },
    {
      "automatic_association": true,
      "balance": 66625030355247581,
      "created_timestamp": "123456789.000000001",
      "freeze_status": "UNFROZEN",
      "kyc_status": "GRANTED",
      "token_id": "0.0.868062"
    }
  ],
  "links": {
    "next": null
  }
}

Proposed Response Structure:

{
  "tokens": [
    {
      "automatic_association": true,
      "balance": 0,
      "created_timestamp": "123456789.000000001",
      "freeze_status": "UNFROZEN",
      "kyc_status": "GRANTED",
      "token_id": "0.0.732556",
      "decimals": 3
    },
    {
      "automatic_association": true,
      "balance": 66625030355247581,
      "created_timestamp": "123456789.000000001",
      "freeze_status": "UNFROZEN",
      "kyc_status": "GRANTED",
      "token_id": "0.0.868062",
      "decimals": 3
    }
  ],
  "links": {
    "next": null
  }
}

The addition of the decimals field will provide the necessary information to accurately determine token balances without requiring additional API calls.

Rationale

The inclusion of decimal information in token balance queries significantly reduces the number of API calls needed to accurately determine account balances. Fewer API calls should reduce the overhead costs they produce. This enhancement aligns with the principles of efficiency, scalability, and user-friendliness that are central to the design of the Hedera API. By simplifying the process of balance retrieval, this proposal aims to improve the developer experience and the performance of applications built on Hedera.

Backwards Compatibility

This change is backwards compatible as it introduces additional fields in the API response structure without altering the existing fields or the overall behavior of the endpoints. Clients not requiring decimal information can ignore the new fields, ensuring uninterrupted service for applications built on the current API version.

Security Implications

This proposal does not introduce changes that affect the security posture of the Hedera API. The addition of the decimals field is a non-interactive change that does not alter the API’s authentication, authorization, or data integrity mechanisms. The proposed change rather increases the scalability by making access to working functions easier for new developers.

How to Teach This

Reference Implementation

Rejected Ideas

Open Issues

None.

References

• HIP-367
• Mirror Node Issue #7386

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: