HIP-968: Enhance mirror node rest API to query by token name

Abstract

This HIP provides the capability of querying tokens by token name in mirror node REST API and getting the corresponding token ID information.

Motivation

To enhance user experience and allow blockchain explorers such as Hashscan to enable the capability of searching by token name, we want to add this functionality to the mirror node to support querying tokens by token name. This is a very common use case across other explorers in the larger ecosystem, and will allow retail users and developers to be able to search for a token by token name instead of token ID.

Rationale

Many times a user may not know the exact token ID when searching for a token, but they know the name. This capability allow users to search by the name and will return results when there is a partial match or exact match. Community members from bridges, Dexes, etc. have been requesting for this for a while.

User stories

• As a user of mirror node, I want to be able to query with a token name (e.g Sauce) and get the corresponding token ID and information.
• As a user of mirror node, I want to be able to see full match and partial match to my search. (e.g when querying for Sauce, I want to see result for $sauce and $xsauce)
• As a user of a Hedera explorer, I want to look up a token by searching for token name.

Specification

The proposed enhancement involves adding query parameters name to the existing route /api/v1/tokens to return information about a token. This new capability only supports HTS tokens at this point and will not include ERC 20/721 tokens, further improvements will be introduced later to support ERC 20/721.

Multiple Query Results

Names assigned to tokens when tokens are created on the network are not unique. Therefore, many tokens with the same name can exist. Querying a token by a given name will return all the tokens that have the specified name defined in the token name.

Name Query Parameter

A new name query parameter will be added to search for tokens by their name. This query parameter will perform a case insensitive sub-string match. That is, it will search for token names that start with, contain, or end with the given value. The usual operators like eq, gt, gte, lt, lte, and ne` will not be supported.

/api/v1/tokens?name={value}

Request

/api/v1/tokens?name=exampleToken

Example Request

GET /api/v1/tokens?limit=2&name=sauce

Note: if limit is not specified in the request, response will be limited to 25 by default

Response Note: Most fields omitted for brevity

{
  "tokens": [{
      "name": "SAUCE",
      "symbol": "SAUCE",
      "token_id": "0.0.731861"
    }, {
      "name": "xSAUCE",
      "symbol": "XSAUCE",
      "token_id": "0.0.1460200"
    }
  ],
  "links": {
    "next": "/api/v1/tokens?limit=2&name=sauce&token.id=gt:0.0.1460200"
  }
}

Backwards Compatibility

The change is backwards compatible as it is simply adding two query parameters to an existing route. The data required to filter by name is already stored in the mirror node.

Security Implications

Full text search indices can slow down ingest performance if the same lexeme shows up in many token names.

Rejected Ideas

• Searching token by symbol.

References

https://mainnet-public.mirrornode.hedera.com/api/v1/docs/#/tokens/listTokens

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: