Accounts

Overview

The Account endpoints in the Hedera Mirror Node REST API provides endpoints to retrieve account details, crypto allowances, token relationships, NFTs owned by accounts, and staking reward payouts. These endpoints are crucial for tracking account balances, permissions, and historical activity.

Endpoints

The following endpoints are available for the Accounts object:

Endpoint	Description
GET /api/v1/accounts	Retrieves a list of accounts on the network.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}	Fetches details of a specific account by ID, alias, or EVM address.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/crypto	Retrieves hbar allowances granted by an account.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}/rewards	Gets past staking reward payouts for an account.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}/airdrops/outstanding	Fetches the outstanding token airdrops for a given account.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}/airdrops/pending	Fetech the pending token airdrops for a given account.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/tokens	Retrieves token allowances granted by an account.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/nfts	Retrieves nft allowances granted by an account.
GET /api/v1/accounts/{idOrAliasOrEvmAddress}/nfts	Fetches the nfts for an account.

Accounts

The accounts object represents the information associated with an account and returns a list of account information.‌

Account IDs take the following format: 0.0.<account number>.‌

Example: 0.0.1000‌

Account IDs can also take the account number as an input value. For example, for account ID 0.0.1000, the number 1000 can be specified in the request.

List account entities on network

get

Returns a list of all account entity items on the network.

Query parameters

account.balancestring

The optional balance value to compare against

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

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

account.idstring

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

The account's public key to compare against

Example: 3c3d546321ff6f63d701d2ec5c277095874e19f4a235bee1e6bb19258bf362be

balanceboolean · default: true

Whether to include balance information or not. If included, token balances are limited to at most 50 per account as outlined in HIP-367. If multiple values are provided the last value will be the only value used.

Example: true

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: asc

The order in which items are listed

Example: desc

Options: asc, desc

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

400

200

{
  "accounts": [
    {
      "account": "0.0.8",
      "alias": "HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA",
      "auto_renew_period": null,
      "balance": {
        "timestamp": "0.000002345",
        "balance": 80,
        "tokens": [
          {
            "token_id": "0.0.200001",
            "balance": 8
          }
        ]
      },
      "created_timestamp": "1562591528.000123456",
      "decline_reward": false,
      "deleted": false,
      "ethereum_nonce": 10,
      "evm_address": "0xac384c53f03855fa1b3616052f8ba32c6c2a2fec",
      "expiry_timestamp": null,
      "key": null,
      "max_automatic_token_associations": 200,
      "memo": "entity memo",
      "pending_reward": 100,
      "receiver_sig_required": false,
      "staked_account_id": null,
      "staked_node_id": 3,
      "stake_period_start": "172800000.000000000"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Response Details

Response Item	Description
account	The ID of the account
alias	RFC4648 no-padding base32 encoded account alias
auto_renew_period	The period in which the account will auto renew
balance	The timestamp and account balance of the account
created_timestamp	The timestamp for the creation of that account
decline_reward	Whether or not the account has opted to decline a staking reward
deleted	Whether the account was deleted or not
ethereum_nonce	The ethereum transaction nonce associated with this account
evm_address	A network entity encoded as an EVM encoded hex
expiry_timestamp	The expiry date for the entity as set by a create or update transaction
key	The public key associated with the account
links.next	Hyperlink to the next page of results
max_automatic_token_associations	The number of automatic token associations, if any
memo	The account memo, if any
nfts	List of nfts informations belonging to this account
pending_reward	The account's pending staking reward that has not been transferred to the account
receiver_sig_required	Whether or not the account requires a signature to receive a transfer into the account
rewards	List of rewards which of the account
staked_account_id	The account ID the account is staked to, if set
staked_node_id	The node ID the account is staked to, if set
stake_period_start	The start of the staking period
tokens	The tokens and their balances associated to the specified account

Optional Filtering

Operator	Example	Description
lt (less than)	/api/v1/accounts?account.id=lt:0.0.1000	Returns account IDs less then 1000
lte (less than or equal to)	/api/v1/accounts?account.id=lte:0.0.1000	Returns account IDs less than or equal to 1000
gt (greater than)	/api/v1/accounts?account.id=gt:0.0.1000	Returns account IDs greater than 1000
gte (greater than or equal to)	/api/v1/accounts?account.id=gte:0.0.1000	Returns account IDs greater than or equal to 1000
order (order asc or desc values)	/api/v1/accounts?order=asc ​ /api/v1/accounts?order=desc	Returns account information in ascending order Returns account information in descending order

Additional Examples

Example Requests	Description
/api/v1/accounts?account.id=0.0.1001	Returns the account information of account 1001
/api/v1/accounts?account.balance=gt:1000	Returns all account information that have a balance greater than 1000 tinybars
/api/v1/accounts?account.publickey=2b60955bcbf0cf5e9ea880b52e5b63f664b08edf6ed 15e301049517438d61864	Returns all account information for 2b60955bcbf0cf5e9ea880b52e5b63f664b08edf6ed15e301049517438d61864 public key
/api/v1/accounts/2?transactionType=cryptotransfer	Returns the crypto transfer transactions for account 2.

Get account by alias, id, or evm address

get

Return the account transactions and balance information given an account alias, an account id, or an evm address. The information will be limited to at most 1000 token balances for the account as outlined in HIP-367. When the timestamp parameter is supplied, we will return transactions and account state for the relevant timestamp query. Balance information will be accurate to within 15 minutes of the provided timestamp query. Historical ethereum nonce information is currently not available and may not be the exact value at a provided timestamp.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: desc

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.

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

transactiontypestring · enum

Example: cryptotransfer

Options: CONSENSUSCREATETOPIC, CONSENSUSDELETETOPIC, CONSENSUSSUBMITMESSAGE, CONSENSUSUPDATETOPIC, CONTRACTCALL, CONTRACTCREATEINSTANCE, CONTRACTDELETEINSTANCE, CONTRACTUPDATEINSTANCE, CRYPTOADDLIVEHASH, CRYPTOAPPROVEALLOWANCE, CRYPTOCREATEACCOUNT, CRYPTODELETE, CRYPTODELETEALLOWANCE, CRYPTODELETELIVEHASH, CRYPTOTRANSFER, CRYPTOUPDATEACCOUNT, ETHEREUMTRANSACTION, FILEAPPEND, FILECREATE, FILEDELETE, FILEUPDATE, FREEZE, NODE, NODECREATE, NODEDELETE, NODESTAKEUPDATE, NODEUPDATE, SCHEDULECREATE, SCHEDULEDELETE, SCHEDULESIGN, SYSTEMDELETE, SYSTEMUNDELETE, TOKENAIRDROP, TOKENASSOCIATE, TOKENBURN, TOKENCANCELAIRDROP, TOKENCLAIMAIRDROP, TOKENCREATION, TOKENDELETION, TOKENDISSOCIATE, TOKENFEESCHEDULEUPDATE, TOKENFREEZE, TOKENGRANTKYC, TOKENMINT, TOKENPAUSE, TOKENREJECT, TOKENREVOKEKYC, TOKENUNFREEZE, TOKENUNPAUSE, TOKENUPDATE, TOKENUPDATENFTS, TOKENWIPE, UNCHECKEDSUBMIT, UNKNOWN, UTILPRNG

transactionsboolean · default: true

If provided and set to false transactions will not be included in the response

Example: true

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}'

200

400

404

200

{
  "account": "0.0.8",
  "alias": "HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA",
  "auto_renew_period": null,
  "balance": {
    "timestamp": "0.000002345",
    "balance": 80,
    "tokens": [
      {
        "token_id": "0.0.200001",
        "balance": 8
      }
    ]
  },
  "created_timestamp": "1562591528.000123456",
  "decline_reward": false,
  "deleted": false,
  "ethereum_nonce": 10,
  "evm_address": "0xac384c53f03855fa1b3616052f8ba32c6c2a2fec",
  "expiry_timestamp": null,
  "key": null,
  "max_automatic_token_associations": 200,
  "memo": "entity memo",
  "pending_reward": 100,
  "receiver_sig_required": false,
  "staked_account_id": null,
  "staked_node_id": 3,
  "stake_period_start": "172800000.000000000",
  "transactions": [
    {
      "bytes": null,
      "charged_tx_fee": 7,
      "consensus_timestamp": "1234567890.000000007",
      "entity_id": "0.0.2281979",
      "max_custom_fees": [
        {
          "account_id": "0.0.8",
          "amount": 1000,
          "denominating_token_id": "0.0.2000"
        },
        {
          "account_id": "0.0.8",
          "amount": 1500,
          "denominating_token_id": null
        }
      ],
      "max_fee": 33,
      "memo_base64": null,
      "name": "CRYPTOTRANSFER",
      "nft_transfers": [
        {
          "is_approval": true,
          "receiver_account_id": "0.0.121",
          "sender_account_id": "0.0.122",
          "serial_number": 1,
          "token_id": "0.0.123"
        },
        {
          "is_approval": true,
          "receiver_account_id": "0.0.321",
          "sender_account_id": "0.0.422",
          "serial_number": 2,
          "token_id": "0.0.123"
        }
      ],
      "node": "0.0.3",
      "nonce": 0,
      "parent_consensus_timestamp": "1234567890.000000007",
      "result": "SUCCESS",
      "scheduled": false,
      "staking_reward_transfers": [
        {
          "account": 3,
          "amount": 150
        },
        {
          "account": 9,
          "amount": 200
        }
      ],
      "transaction_hash": "vigzKe2J7fv4ktHBbNTSzQmKq7Lzdq1/lJMmHT+a2KgvdhAuadlvS4eKeqKjIRmW",
      "transaction_id": "0.0.8-1234567890-000000006",
      "token_transfers": [
        {
          "token_id": "0.0.90000",
          "account": "0.0.9",
          "amount": 1200,
          "is_approval": false
        },
        {
          "token_id": "0.0.90000",
          "account": "0.0.8",
          "amount": -1200,
          "is_approval": false
        }
      ],
      "transfers": [
        {
          "account": "0.0.3",
          "amount": 2,
          "is_approval": false
        },
        {
          "account": "0.0.8",
          "amount": -3,
          "is_approval": false
        },
        {
          "account": "0.0.98",
          "amount": 1,
          "is_approval": false
        },
        {
          "account": "0.0.800",
          "amount": 150,
          "is_approval": false
        },
        {
          "account": "0.0.800",
          "amount": 200,
          "is_approval": false
        }
      ],
      "valid_duration_seconds": 11,
      "valid_start_timestamp": "1234567890.000000006"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get crypto allowances for an account info

get

Returns information for all crypto allowances for an account.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: desc

The order in which items are listed

Example: asc

Options: asc, desc

spender.idstring

The ID of the spender to return information for

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

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

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/crypto'

200

400

404

200

{
  "allowances": [
    {
      "amount": 1,
      "amount_granted": 1,
      "owner": "0.0.2",
      "spender": "0.0.2",
      "timestamp": {
        "from": null,
        "to": null
      }
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get past staking reward payouts for an account

get

Returns information for all past staking reward payouts for an account.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: desc

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.

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

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}/rewards'

200

400

404

200

{
  "rewards": [
    {
      "account_id": "0.0.1000",
      "amount": 10,
      "timestamp": "1234567890.000000001"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get token relationships info for an account

get

Returns information for all token relationships for an account.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: asc

The order in which items are listed

Example: desc

Options: asc, desc

token.idstring

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}$

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

400

404

200

{
  "tokens": [
    {
      "automatic_association": true,
      "balance": 5,
      "created_timestamp": "123456789.000000001",
      "decimals": 3,
      "freeze_status": "UNFROZEN",
      "kyc_status": "GRANTED",
      "token_id": "0.0.27335"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get outstanding token airdrops sent by an account

get

Returns outstanding token airdrops that have been sent by an account.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: asc

The order in which items are listed

Example: desc

Options: asc, desc

receiver.idstring

The ID of the receiver to return information for

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

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

serialnumberstring

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}?$

token.idstring

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}$

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}/airdrops/outstanding'

200

400

404

200

{
  "airdrops": [
    {
      "amount": 10,
      "receiver_id": "0.0.15",
      "sender_id": "0.0.10",
      "serial_number": null,
      "timestamp": {
        "from": "1651560386.060890949",
        "to": "1651560386.661997287"
      },
      "token_id": "0.0.99"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get pending token airdrops received by an account

get

Returns pending token airdrops that have been received by an account.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: asc

The order in which items are listed

Example: desc

Options: asc, desc

sender.idstring

The ID of the sender to return information for

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

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

serialnumberstring

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}?$

token.idstring

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}$

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}/airdrops/pending'

200

400

404

200

{
  "airdrops": [
    {
      "amount": 10,
      "receiver_id": "0.0.15",
      "sender_id": "0.0.10",
      "serial_number": null,
      "timestamp": {
        "from": "1651560386.060890949",
        "to": "1651560386.661997287"
      },
      "token_id": "0.0.99"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get fungible token allowances for an account

get

Returns information for fungible token allowances for an account.

Ordering

The order is governed by a combination of the spender id and the token id values, with spender id being the parent column. The token id value governs its order within the given spender id.

Note: The default order for this API is currently ASC

Filtering

When filtering there are some restrictions enforced to ensure correctness and scalability.

The table below defines the restrictions and support for the endpoint

Query Param	Comparison Operator	Support	Description	Example
spender.id	eq	Y	Single occurrence only.	?spender.id=X
	ne	N
	lt(e)	Y	Single occurrence only.	?spender.id=lte:X
	gt(e)	Y	Single occurrence only.	?spender.id=gte:X
token.id	eq	Y	Single occurrence only. Requires the presence of a spender.id query	?token.id=lt:Y
	ne	N
	lt(e)	Y	Single occurrence only. Requires the presence of an lte or eq spender.id query	?spender.id=lte:X&token.id=lt:Y
	gt(e)	Y	Single occurrence only. Requires the presence of an gte or eq spender.id query	?spender.id=gte:X&token.id=gt:Y

Both filters must be a single occurrence of gt(e) or lt(e) which provide a lower and or upper boundary for search.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: asc

The order in which items are listed

Example: desc

Options: asc, desc

spender.idstring

The ID of the spender to return information for

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

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

token.idstring

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}$

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/tokens'

200

400

404

200

{
  "allowances": [
    {
      "amount": 75,
      "amount_granted": 100,
      "owner": "0.0.2",
      "spender": "0.0.2",
      "timestamp": {
        "from": null,
        "to": null
      },
      "token_id": "0.0.2"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get non fungible token allowances for an account

get

Returns an account's non-fungible token allowances.

Ordering

The order is governed by a combination of the account ID and the token ID values, with account ID being the parent column. The token ID value governs its order within the given account ID.

Note: The default order for this API is currently ascending. The account ID can be the owner or the spender ID depending upon the owner flag.

Filtering

When filtering there are some restrictions enforced to ensure correctness and scalability.

The table below defines the restrictions and support for the endpoint

Query Param	Comparison Operator	Support	Description	Example
account.id	eq	Y	Single occurrence only.	?account.id=X
	ne	N
	lt(e)	Y	Single occurrence only.	?account.id=lte:X
	gt(e)	Y	Single occurrence only.	?account.id=gte:X
token.id	eq	Y	Single occurrence only. Requires the presence of an account.id parameter	?account.id=X&token.id=eq:Y
	ne	N
	lt(e)	Y	Single occurrence only. Requires the presence of an lte or eq account.id parameter	?account.id=lte:X&token.id=lt:Y
	gt(e)	Y	Single occurrence only. Requires the presence of an gte or eq account.id parameter	?account.id=gte:X&token.id=gt:Y

Both filters must be a single occurrence of gt(e) or lt(e) which provide a lower and or upper boundary for search.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: asc

The order in which items are listed

Example: desc

Options: asc, desc

account.idstring

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}$

token.idstring

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}$

ownerboolean · default: true

When the owner value is true or omitted, the accountId path parameter will specify the ID of the owner, and the API will retrieve the allowances that the owner has granted to different spenders. Conversely, when the owner value is false, the accountId path parameter will indicate the ID of the spender who has an allowance, and the API will instead provide the allowances granted to the spender by different owners of those tokens.

Example: true

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/nfts'

200

400

404

200

{
  "allowances": [
    {
      "approved_for_all": false,
      "owner": "0.0.11",
      "payer_account_id": "0.0.10",
      "spender": "0.0.15",
      "timestamp": {
        "from": "1651560386.060890949",
        "to": "1651560386.661997287"
      },
      "token_id": "0.0.99"
    }
  ],
  "links": {
    "next": null
  }
}

OK

Get nfts for an account info

get

Returns information for all non-fungible tokens for an account.

Ordering

When considering NFTs, their order is governed by a combination of their numerical token.Id and serialnumber values, with token.id being the parent column. A serialnumbers value governs its order within the given token.id

In that regard, if a user acquired a set of NFTs in the order (2-2, 2-4 1-5, 1-1, 1-3, 3-3, 3-4), the following layouts illustrate the ordering expectations for ownership listing

1. All NFTs in ASC order: 1-1, 1-3, 1-5, 2-2, 2-4, 3-3, 3-4
2. All NFTs in DESC order: 3-4, 3-3, 2-4, 2-2, 1-5, 1-3, 1-1
3. NFTs above 1-1 in ASC order: 1-3, 1-5, 2-2, 2-4, 3-3, 3-4
4. NFTs below 3-3 in ASC order: 1-1, 1-3, 1-5, 2-2, 2-4
5. NFTs between 1-3 and 3-3 inclusive in DESC order: 3-4, 3-3, 2-4, 2-2, 1-5, 1-3

Note: The default order for this API is currently DESC

Filtering

When filtering there are some restrictions enforced to ensure correctness and scalability.

The table below defines the restrictions and support for the NFT ownership endpoint

Query Param	Comparison Operator	Support	Description	Example
token.id	eq	Y	Single occurrence only.	?token.id=X
	ne	N
	lt(e)	Y	Single occurrence only.	?token.id=lte:X
	gt(e)	Y	Single occurrence only.	?token.id=gte:X
serialnumber	eq	Y	Single occurrence only. Requires the presence of a token.id query	?serialnumber=Y
	ne	N
	lt(e)	Y	Single occurrence only. Requires the presence of an lte or eq token.id query	?token.id=lte:X&serialnumber=lt:Y
	gt(e)	Y	Single occurrence only. Requires the presence of an gte or eq token.id query	?token.id=gte:X&serialnumber=gt:Y
spender.id	eq	Y		?spender.id=Z
	ne	N
	lt(e)	Y		?spender.id=lt:Z
	gt(e)	Y		?spender.id=gt:Z

Note: When searching across a range for individual NFTs a serialnumber with an additional token.id query filter must be provided. Both filters must be a single occurrence of gt(e) or lt(e) which provide a lower and or upper boundary for search.

Path parameters

idOrAliasOrEvmAddressstringrequired

Account alias or account id or evm address

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}

Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

Query parameters

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

The maximum number of items to return

Example: 2

orderundefined · enum · default: desc

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.

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

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

spender.idstring

The ID of the spender to return information for

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

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

token.idstring

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}$

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/accounts/{idOrAliasOrEvmAddress}/nfts'

200

400

404

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