Tokens

Overview

The Tokens endpoints in the Hedera Mirror Node REST API allow developers to retrieve token details, token balances, NFT metadata, and transaction history. These endpoints are essential for tracking tokenized assets and interactions on the Hedera network.

Endpoints

The following endpoints are available for the Tokens object:

Endpoint

Description

GET /api/v1/tokens

Retrieves a list of all tokens on the network.

GET /api/v1/tokens/balances

Lists token balances across accounts.

GET /api/v1/tokens/{id}

Fetches details of a specific token by ID.

GET /api/v1/tokens/nfts

Retrieves a list of all NFTs on the network.

GET /api/v1/tokens/nfts/{id}

Fetches metadata and details for a specific NFT.

GET /api/v1/tokens/nfts/{id}/transactions

Retrieves the transaction history of a specific NFT.

GET /api/v1/network/supply

Fetches the current total supply of HBAR.

Tokens

List tokens

Returns a list of tokens on the network.

get

/api/v1/tokens

Query parameters
account.idstring

The ID of the account to return information for

Pattern: ^((gte?|lte?|eq|ne)\:)?(\d{1,10}\.\d{1,10}\.)?\d{1,10}$
limitinteger int32

The maximum number of items to return

Example: 2
namestring

Partial or full token name. Not allowed to be used with token.id or account.id parameter. Pagination is not supported with the use of this parameter and results are ordered by token.id with respect to the order parameter.

orderenum

The order in which items are listed

Example: desc
Options: asc, desc
publickeystring

The public key to compare against

Example: 3c3d546321ff6f63d701d2ec5c277095874e19f4a235bee1e6bb19258bf362be
token.idstring

The ID of the token to return information for

Pattern: ^((gte?|lte?|eq|ne)\:)?(\d{1,10}\.\d{1,10}\.)?\d{1,10}$
typestring[]
Example: ["ALL","FUNGIBLE_COMMON","NON_FUNGIBLE_UNIQUE"]
Responses
curl -L \
  --url '/api/v1/tokens'
{
  "tokens": [
    {
      "admin_key": null,
      "decimals": 3,
      "metadata": "VGhpcyBpcyBhIHRlc3QgTkZU",
      "name": "First Mover",
      "symbol": "FIRSTMOVERLPDJH",
      "token_id": "0.0.1",
      "type": "FUNGIBLE_COMMON"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Response Details

Response Item
Description

token_Id

The ID of the token in x.y.z format

symbol

The symbol of the token

admin_key

The admin key for the token

type

The type of token (fungible or non-fungible)

Additional Examples

Example Request
Description

/api/v1/tokens?publickey=3c3d546321ff6f63d70 1d2ec5c277095874e19f4a235bee1e6bb19258bf362be

All tokens with matching admin key

/api/v1/tokens?account.id=0.0.8

All tokens for matching account

/api/v1/tokens?token.id=gt:0.0.1001

All tokens in range

/api/v1/tokens?order=desc

All tokens in descending order of token.id

/api/v1/tokens?limit=x

All tokens taking the first x number of tokens

List token balances

Returns a list of token balances given the id. This represents the Token supply distribution across the network

get

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

Path parameters
tokenIdnullable stringrequired

Network entity ID in the format of shard.realm.num

Example: 0.0.2
Pattern: ^\d{1,10}\.\d{1,10}\.\d{1,10}$
Query parameters
account.balancestring

The optional balance value to compare against

Pattern: ^((gte?|lte?|eq|ne)\:)?\d{1,10}$
account.idstring

The ID of the account to return information for

Pattern: ^((gte?|lte?|eq|ne)\:)?(\d{1,10}\.\d{1,10}\.)?\d{1,10}$
account.publickeystring

The account's public key to compare against

Example: 3c3d546321ff6f63d701d2ec5c277095874e19f4a235bee1e6bb19258bf362be
limitinteger int32

The maximum number of items to return

Example: 2
orderenum

The order in which items are listed

Example: asc
Options: asc, desc
timestampstring[]

The consensus timestamp as a Unix timestamp in seconds.nanoseconds format with an optional comparison operator. See unixtimestamp.com for a simple way to convert a date to the 'seconds' part of the Unix time.

Responses
curl -L \
  --url '/api/v1/tokens/{tokenId}/balances'
{
  "timestamp": "1586567700.453054000",
  "balances": [
    {
      "account": "0.15.2",
      "balance": 1000,
      "decimals": 3
    }
  ],
  "links": {
    "next": null
  }
}

OK

Response Details

Response Item
Description

timestamp

The timestamp of the recorded balances in seconds.nanoseconds

balances

The balance of the tokens in those accounts

account

The ID of the account that has the token balance

balance

The balance of the token associated with the account

Additional Examples

Example Request
Description

/api/v1/tokens/<token_id>/balances?order=asc

The balance of the token in ascending order

/api/v1/tokens/<token_id>/balances?account.id=0.0.1000

The balance of the token for account ID 0.0.1000

/api/v1/tokens/<token_id>/balances?account.balance=gt:1000

The balance for the token greater than 1000

/api/v1/tokens/<token_id>/balances?timestamp=1566562500.040961001

The token balances for the specified timestamp

Get token by id

Returns token entity information given the id

get

/api/v1/tokens/{tokenId}

Path parameters
tokenIdnullable stringrequired

Network entity ID in the format of shard.realm.num

Example: 0.0.2
Pattern: ^\d{1,10}\.\d{1,10}\.\d{1,10}$
Query parameters
timestampstring

The Unix timestamp in seconds.nanoseconds format. See unixtimestamp.com for a simple way to convert a date to the 'seconds' part of the Unix time.

Pattern: ^((eq|lt|lte):)?\d{1,10}(.\d{1,9})?$
Responses
curl -L \
  --url '/api/v1/tokens/{tokenId}'
{
  "auto_renew_account": "0.1.2",
  "auto_renew_period": null,
  "created_timestamp": "1234567890.000000001",
  "deleted": false,
  "decimals": 1000,
  "expiry_timestamp": null,
  "freeze_default": false,
  "initial_supply": 1000000,
  "max_supply": 9223372036854776000,
  "memo": "token memo",
  "modified_timestamp": "1234567890.000000001",
  "name": "Token name",
  "pause_status": "UNPAUSED",
  "supply_type": "INFINITE",
  "symbol": "ORIGINALRDKSE",
  "token_id": "0.10.1",
  "total_supply": 1000000,
  "treasury_account_id": "0.1.2",
  "type": "FUNGIBLE_COMMON",
  "admin_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "freeze_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "kyc_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "pause_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "supply_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "wipe_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "custom_fees": {
    "created_timestamp": "1234567890.000000001",
    "fixed_fees": [
      {
        "amount": 100,
        "collector_account_id": "0.1.5",
        "denominating_token_id": "0.10.8"
      }
    ],
    "fractional_fees": [
      {
        "collector_account_id": "0.1.6",
        "denominating_token_id": "0.10.9",
        "maximum": 120,
        "minimum": 30,
        "net_of_transfers": true,
        "amount": {
          "numerator": 12,
          "denominator": 29
        }
      }
    ]
  }
}

OK

Response Details

Response Item
Description

admin_key

The token's admin key, if specified

auto_renew_account

The auto renew account ID

auto_renew_period

The period at which the auto renew account will be charged a renewal fee

created_timestamp

The timestamp of when the token was created

decimals

The number of decimal places a token is divisible by

expiry_timestamp

The epoch second at which the token should expire

freeze_default

Whether or not accounts created

fee_schedule_key

The fee schedule key, if any

freeze_key

The freeze key for the token, if specified

initial_supply

The initial supply of the token

kyc_key

The KYC key for the token, if specified

modified_timestamp

The last time the token properties were modified

name

The name of the token

supply_key

The supply key for the token, if specified

symbol

The token symbol

token_id

The token ID

total_supply

The total supply of the token

treasury_account_id

The treasury account of the token

type

whether a token is a fungible or non-fungible token

wipe_key

The wipe key for the token, if specified

custom_fees

The custom fee schedule for the token, if any

pause_key

The pause key for a token, if specified

pause_status

Whether or not the token is paused

List nfts

Returns a list of non-fungible tokens

get

/api/v1/tokens/{tokenId}/nfts

Path parameters
tokenIdnullable stringrequired

Network entity ID in the format of shard.realm.num

Example: 0.0.2
Pattern: ^\d{1,10}\.\d{1,10}\.\d{1,10}$
Query parameters
account.idstring

The ID of the account to return information for

Pattern: ^((gte?|lte?|eq|ne)\:)?(\d{1,10}\.\d{1,10}\.)?\d{1,10}$
limitinteger int32

The maximum number of items to return

Example: 2
orderenum

The order in which items are listed

Example: asc
Options: asc, desc
serialnumberstring

The nft serial number (64 bit type). Requires a tokenId value also be populated.

Pattern: ^((eq|gt|gte|lt|lte):)?\d{1,19}?$
Responses
curl -L \
  --url '/api/v1/tokens/{tokenId}/nfts'
{
  "links": {
    "next": null
  },
  "nfts": [
    {
      "account_id": "0.1.2",
      "created_timestamp": "1234567890.000000001",
      "delegating_spender": "0.0.400",
      "deleted": false,
      "metadata": "VGhpcyBpcyBhIHRlc3QgTkZU",
      "modified_timestamp": "1610682445.003266001",
      "serial_number": 124,
      "spender_id": "0.0.500",
      "token_id": "0.0.222"
    }
  ]
}

OK

Response Details

Response Item
Description

account_id

The account ID of the account associated with the NFT

created_timestamp

The timestamp of when the NFT was created

deleted

Whether the token was deleted or not

metadata

The meta data of the NFT

modified_timestamp

The last time the token properties were modified

serial_number

The serial number of the NFT

token_id

The token ID of the NFT

Get nft info

Returns information for a non-fungible token

get

/api/v1/tokens/{tokenId}/nfts/{serialNumber}

Path parameters
tokenIdnullable stringrequired

Network entity ID in the format of shard.realm.num

Example: 0.0.2
Pattern: ^\d{1,10}\.\d{1,10}\.\d{1,10}$
serialNumberinteger int64required

The nft serial number

Example: 1
Responses
curl -L \
  --url '/api/v1/tokens/{tokenId}/nfts/{serialNumber}'
{
  "account_id": "0.1.2",
  "created_timestamp": "1234567890.000000001",
  "delegating_spender": "0.0.400",
  "deleted": false,
  "metadata": "VGhpcyBpcyBhIHRlc3QgTkZU",
  "modified_timestamp": "1610682445.003266001",
  "serial_number": 124,
  "spender_id": "0.0.500",
  "token_id": "0.0.222"
}

OK

Response Details

Response Item
Description

account_id

The account ID of the account associated with the NFT

created_timestamp

The timestamp of when the NFT was created

deleted

Whether the token was deleted or not

metadata

The meta data of the NFT

modified_timestamp

The last time the token properties were modified

serial_number

The serial number of the NFT

token_id

The token ID of the NFT

Get an nfts transction history

Returns a list of transactions for a given non-fungible token

get

/api/v1/tokens/{tokenId}/nfts/{serialNumber}/transactions

Path parameters
tokenIdnullable stringrequired

Network entity ID in the format of shard.realm.num

Example: 0.0.2
Pattern: ^\d{1,10}\.\d{1,10}\.\d{1,10}$
serialNumberinteger int64required

The nft serial number

Example: 1
Query parameters
limitinteger int32

The maximum number of items to return

Example: 2
orderenum

The order in which items are listed

Example: asc
Options: asc, desc
timestampstring[]

The consensus timestamp as a Unix timestamp in seconds.nanoseconds format with an optional comparison operator. See unixtimestamp.com for a simple way to convert a date to the 'seconds' part of the Unix time.

Responses
curl -L \
  --url '/api/v1/tokens/{tokenId}/nfts/{serialNumber}/transactions'
{
  "links": {
    "next": null
  },
  "transactions": [
    {
      "consensus_timestamp": "1618591023.997420021",
      "is_approval": false,
      "nonce": 0,
      "receiver_account_id": "0.0.11",
      "sender_account_id": "0.0.10",
      "transaction_id": "0.0.19789-1618591023-997420021",
      "type": "CRYPTOTRANSFER"
    }
  ]
}

OK

Response Details

Response Item
Description

created_timestamp

The timestamp of the transaction

id

The timestamp of the transaction

receiver_account_id

The account that received the NFT

sender_account_id

The account that sent the NFT

type

The type of transaction

token_id

The token ID of the NFT

Get the network supply

Returns the network's released supply of hbars

get

/api/v1/network/supply

Query parameters
timestampstring[]

The consensus timestamp as a Unix timestamp in seconds.nanoseconds format with an optional comparison operator. See unixtimestamp.com for a simple way to convert a date to the 'seconds' part of the Unix time.

Responses
curl -L \
  --url '/api/v1/network/supply'
{
  "released_supply": "3999999999999999949",
  "total_supply": "5000000000000000000",
  "timestamp": null
}

OK

PreviousSmart ContractsNextTopics

Last updated

Was this helpful?