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/{serialNumber}	Fetches metadata and details for a specific NFT.
GET /api/v1/tokens/nfts/{id}/transactions	Retrieves the transaction history of a specific NFT.

Tokens

List tokens

get

Returns a list of tokens on the network.

Query parameters

account.idstringoptional

The ID of the account to return information for

Example: {"summary":"--","value":""}

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

limitinteger · int32 · min: 1 · max: 100 · default: 25optional

The maximum number of items to return

Example: 2

namestring · min: 3 · max: 100optional

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.

orderundefined · enum · default: "asc"optional

The order in which items are listed

Example: desc

Options: asc, desc

publickeystringoptional

The public key to compare against

Example: 3c3d546321ff6f63d701d2ec5c277095874e19f4a235bee1e6bb19258bf362be

token.idstringoptional

The ID of the token to return information for

Example: {"summary":"--","value":""}

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

typestring[]optional

Example: ["ALL","FUNGIBLE_COMMON","NON_FUNGIBLE_UNIQUE"]

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/tokens'

200

400

200

{
  "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)
decimals	The decimal numbers of the token
metadata	The metadata of the token

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

get

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

Path parameters

tokenIdstring | nullablerequired

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.balancestringoptional

The optional balance value to compare against

Example: {"summary":"--","value":""}

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

account.idstringoptional

The ID of the account to return information for

Example: {"summary":"--","value":""}

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

account.publickeystringoptional

The account's public key to compare against

Example: 3c3d546321ff6f63d701d2ec5c277095874e19f4a235bee1e6bb19258bf362be

limitinteger · int32 · min: 1 · max: 100 · default: 25optional

The maximum number of items to return

Example: 2

orderundefined · enum · default: "desc"optional

The order in which items are listed

Example: asc

Options: asc, desc

timestampstring[]optional

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.

Example: {"summary":"--","value":""}

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/tokens/{tokenId}/balances'

200

400

200

{
  "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
balances.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

get

Returns token entity information given the id

Path parameters

tokenIdstring | nullablerequired

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

timestampstringoptional

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.

Example: {"summary":"--","value":""}

Pattern: ^((eq|lt|lte):)?\d{1,10}(.\d{1,9})?$

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/tokens/{tokenId}'

200

400

404

200

FungibleToken

NonFungibleToken

FungibleToken

{
  "admin_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "auto_renew_account": "0.1.2",
  "auto_renew_period": null,
  "created_timestamp": "1234567890.000000001",
  "deleted": false,
  "decimals": 1000,
  "expiry_timestamp": null,
  "freeze_default": false,
  "freeze_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "initial_supply": 1000000,
  "kyc_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "max_supply": 9223372036854776000,
  "memo": "token memo",
  "modified_timestamp": "1234567890.000000001",
  "name": "Token name",
  "pause_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "pause_status": "UNPAUSED",
  "supply_key": {
    "_type": "ProtobufEncoded",
    "key": 10101
  },
  "supply_type": "INFINITE",
  "symbol": "ORIGINALRDKSE",
  "token_id": "0.10.1",
  "total_supply": 1000000,
  "treasury_account_id": "0.1.2",
  "type": "FUNGIBLE_COMMON",
  "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": [
      {
        "amount": {
          "numerator": 12,
          "denominator": 29
        },
        "collector_account_id": "0.1.6",
        "denominating_token_id": "0.10.9",
        "maximum": 120,
        "minimum": 30,
        "net_of_transfers": true
      }
    ]
  }
}

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

get

Returns a list of non-fungible tokens

Path parameters

tokenIdstring | nullablerequired

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.idstringoptional

The ID of the account to return information for

Example: {"summary":"--","value":""}

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

limitinteger · int32 · min: 1 · max: 100 · default: 25optional

The maximum number of items to return

Example: 2

orderundefined · enum · default: "desc"optional

The order in which items are listed

Example: asc

Options: asc, desc

serialnumberstringoptional

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

Example: {"summary":"--","value":""}

Pattern: ^((eq|gt|gte|lt|lte):)?\d{1,19}?$

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/tokens/{tokenId}/nfts'

200

400

200

{
  "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"
    }
  ],
  "links": {
    "next": null
  }
}

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

get

Returns information for a non-fungible token

Path parameters

tokenIdstring | nullablerequired

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 · int64 · min: 1 · max: 9223372036854776000 · default: 1required

The nft serial number

Example: 1

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/tokens/{tokenId}/nfts/{serialNumber}'

200

400

404

200

{
  "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

get

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

Path parameters

tokenIdstring | nullablerequired

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 · int64 · min: 1 · max: 9223372036854776000 · default: 1required

The nft serial number

Example: 1

Query parameters

limitinteger · int32 · min: 1 · max: 100 · default: 25optional

The maximum number of items to return

Example: 2

orderundefined · enum · default: "desc"optional

The order in which items are listed

Example: asc

Options: asc, desc

timestampstring[]optional

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.

Example: {"summary":"--","value":""}

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/tokens/{tokenId}/nfts/{serialNumber}/transactions'

200

206

400

200

{
  "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"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Response Details

Response Item	Description
consensus_timestamp	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
transaction_id	The ID of the transaction
token_id	The token ID of the NFT