# Tokens

## Get ERC20-Token TotalSupply by ContractAddress

Returns the current amount of an ERC-20 token in circulation.

```
https://api.xdcscan.io/api
   ?module=stats
   &action=tokensupply
   &contractaddress=0xff7412ea7c8445c46a8254dfb557ac1e48094391
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=stats\&action=tokensupply\&contractaddress=0xff7412ea7c8445c46a8254dfb557ac1e48094391) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter       | Description                                |
| --------------- | ------------------------------------------ |
| contractaddress | the `contract address` of the ERC-20 token |
| {% endtab %}    |                                            |

{% tab title="Response" %}
Sample Response

```
{
"message": "OK",
"status": "1",
"result": "500000000000000000000000000"
}
```

{% hint style="info" %}
:chart\_with\_upwards\_trend: **Tip** : The `result` is returned in the token's **smallest decimal representation.**

Eg. a token with a balance of `215.241526476136819398` and 18 decimal places will be returned as `215241526476136819398`
{% endhint %}
{% endtab %}
{% endtabs %}

## Get ERC20-Token Account Balance for TokenContractAddress

Returns the current balance of an ERC-20 token of an address.

```
https://api.xdcscan.io/api
   ?module=account
   &action=tokenbalance
   &contractaddress=0x8b20c72f1b138a41d2193dd056e117dce915ba8b
   &address=xdcaff614f772dd4723bffd5d5cf824b7643688a923
   &tag=latest&apikey=YourApiKeyToken
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=account\&action=tokenbalance\&contractaddress=0x8b20c72f1b138a41d2193dd056e117dce915ba8b\&address=xdcaff614f772dd4723bffd5d5cf824b7643688a923\&tag=latest\&apikey=YourApiKeyToken) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter       | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| contractaddress | the `contract address` of the ERC-20 token                       |
| address         | the `string` representing the address to check for token balance |
| {% endtab %}    |                                                                  |

{% tab title="Response" %}
Sample Response

```
{
"message": "OK",
"status": "1",
"result": "78860700000000000000000000"
}
```

{% hint style="info" %}
:chart\_with\_upwards\_trend: **Tip** : The `result` is returned in the token's **smallest decimal representation.**

Eg. a token with a balance of `215.241526476136819398` and 18 decimal places will be returned as `215241526476136819398`
{% endhint %}
{% endtab %}
{% endtabs %}

## Get Historical ERC20-Token TotalSupply by ContractAddress & BlockNo <img src="https://github.com/BlocksScan/Docs/blob/api/broken-reference" alt="" data-size="line">

Returns the amount of an ERC-20 token in circulation at a certain block height.

{% hint style="warning" %}
:pencil: **Note :** This endpoint is throttled to **2 calls/second** regardless of API Pro tier.
{% endhint %}

```
https://api.xdcscan.io/api
   ?module=stats
   &action=tokensupplyhistory
   &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
   &blockno=8000000
   &apikey=YourApiKeyToken 
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=stats\&action=tokensupplyhistory\&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055\&blockno=8000000\&apikey=YourApiKeyToken) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter       | Description                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| contractaddress | the `contract address` of the ERC-20 token                                                                      |
| blockno         | the `integer` block number to check total supply for eg. [`76986383`](https://xdc.blocksscan.io/block/76986383) |
| {% endtab %}    |                                                                                                                 |

{% tab title="Response" %}
Sample Response

```
{
   "status":"1",
   "message":"OK",
   "result":"21265524714464"
}
```

{% hint style="info" %}
:chart\_with\_upwards\_trend: **Tip** : The `result` is returned in the token's **smallest decimal representation.**

Eg. a token with a balance of `215.241526476136819398` and 18 decimal places will be returned as `215241526476136819398`
{% endhint %}
{% endtab %}
{% endtabs %}

## Get Historical ERC20-Token Account Balance for TokenContractAddress by BlockNo <img src="https://github.com/BlocksScan/Docs/blob/api/broken-reference" alt="" data-size="line">

Returns the balance of an ERC-20 token of an address at a certain block height.

{% hint style="warning" %}
:pencil: **Note :** This endpoint is throttled to **2 calls/second** regardless of API Pro tier.
{% endhint %}

```
https://api.xdcscan.io/api
   ?module=account
   &action=tokenbalancehistory
   &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
   &address=0xe04f27eb70e025b78871a2ad7eabe85e61212761
   &blockno=8000000
   &apikey=YourApiKeyToken 
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=account\&action=tokenbalancehistory\&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055\&address=0xe04f27eb70e025b78871a2ad7eabe85e61212761\&blockno=8000000\&apikey=YourApiKeyToken) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter       | Description                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| contractaddress | the `contract address` of the ERC-20 token                                                                      |
| address         | the `string` representing the address to check for balance                                                      |
| blockno         | the `integer` block number to check total supply for eg. [`76986383`](https://xdc.blocksscan.io/block/76986383) |
| {% endtab %}    |                                                                                                                 |

{% tab title="Response" %}
Sample Response

```
{
   "status":"1",
   "message":"OK",
   "result":"135499"
}
```

{% hint style="info" %}
:chart\_with\_upwards\_trend: **Tip** : The `result` is returned in the token's **smallest decimal representation.**

Eg. a token with a balance of `215.241526476136819398` and 18 decimal places will be returned as `215241526476136819398`
{% endhint %}
{% endtab %}
{% endtabs %}

## Get Token Holder List by Contract Address <img src="https://github.com/BlocksScan/Docs/blob/api/broken-reference" alt="" data-size="line">

Return the current ERC20 token holders and number of tokens held.

```
https://api.xdcscan.io/api
   ?module=token
   &action=tokenholderlist
   &contractaddress=0x5d5f074837f5d4618b3916ba74de1bf9662a3fed
   &page=1
   &offset=10
   &apikey=YourApiKeyToken 
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=token\&action=tokenholderlist\&contractaddress=0x5d5f074837f5d4618b3916ba74de1bf9662a3fed\&page=1\&offset=10\&apikey=YourApiKeyToken) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter       | Description                                         |
| --------------- | --------------------------------------------------- |
| contractaddress | the `contract address` of the ERC-20 token          |
| page            | the `integer` page number, if pagination is enabled |
| offset          | the number of transactions displayed per page       |
| {% endtab %}    |                                                     |

{% tab title="Response" %}
Sample Response

```
{
"message": "OK",
"status": "1",
"result": [
{
"TokenHolderAddress": "0x478a72f7424b7be55a48ed51714cfebba561ee3a",
"TokenHolderQuantity": "87500000000000000000000000"
},
{
"TokenHolderAddress": "0x9223fc00642c3020b4b2525619e798636560a0ea",
"TokenHolderQuantity": "60196381000000000000000000"
},
{
"TokenHolderAddress": "0x02fe7b136f5dbff8d00546cb5af45afd1e1d350c",
"TokenHolderQuantity": "28708172094690000000000000"
},
{
"TokenHolderAddress": "0xc1b519019639c7e684c6626440b448582cbe0a75",
"TokenHolderQuantity": "22907106095177981285268107"
},
{
"TokenHolderAddress": "0x07787fa0108d4188c6f58d99058c3967b2f05e6a",
"TokenHolderQuantity": "20719833292342250000000000"
}
    ]
}
```

{% endtab %}
{% endtabs %}

## Get Token Info by ContractAddress <img src="https://github.com/BlocksScan/Docs/blob/api/broken-reference" alt="" data-size="line">

Returns project information and social media links of an ERC20/ERC721/ERC1155 token.

```
https://api.xdcscan.io/api
   ?module=token
   &action=tokeninfo
   &contractaddress=0x5d5f074837f5d4618b3916ba74de1bf9662a3fed
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=token\&action=tokeninfo\&contractaddress=0x5d5f074837f5d4618b3916ba74de1bf9662a3fed) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter       | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| contractaddress | the `contract address` of the ERC-20/ERC-721 token to retrieve token info |
| {% endtab %}    |                                                                           |

{% tab title="Response" %}
Sample Response

```
{
"message": "OK",
"status": "1",
"result": {
"contractAddress": "0x5d5f074837f5d4618b3916ba74de1bf9662a3fed",
"tokenName": "STORX",
"symbol": "SRX",
"divisor": null,
"tokenType": "ERC-20",
"totalSupply": "596893424.652282",
"blueCheckmark": null,
"description": "StorX helps you securely encrypt, fragment and then distribute important data across multiple hosting nodes spread worldwide. StorX provides a democratic marketplace for hosting data, replacing the centralized intermediaries with a decentralized blockchain network. Exercise complete control and grant access over your data sets without any centralized intermediary.",
"website": "https://storx.tech/",
"email": null,
"blog": null,
"reddit": null,
"slack": null,
"facebook": "https://www.facebook.com/StorXNetwork",
"twitter": "https://twitter.com/StorXNetwork",
"bitcointalk": null,
"github": null,
"telegram": "StorXNetwork",
"webchat": null,
"discord": "https://discord.gg/ha4Jufj2Nm",
"whitepaper": null,
"tokenPriceUSD": "N/A"
}
}
```

{% endtab %}
{% endtabs %}

## Get Address ERC20 Token Holding <img src="https://github.com/BlocksScan/Docs/blob/api/broken-reference" alt="" data-size="line">

Returns the ERC-20 tokens and amount held by an address.

{% hint style="warning" %}
**Note :** This endpoint is throttled to **2 calls/second** regardless of API Pro tier.
{% endhint %}

```
https://api.xdcscan.io/api
   ?module=account
   &action=addresstokenbalance
   &address=xdcd77875dF9C9dE07a5a701F4431743e3A0e9Fe03a
   &page=1
   &offset=100
   &apikey=YourApiKeyToken
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=account\&action=addresstokenbalance\&address=xdcd77875dF9C9dE07a5a701F4431743e3A0e9Fe03a\&page=1\&offset=100\&apikey=YourApiKeyToken) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter    | Description                                                |
| ------------ | ---------------------------------------------------------- |
| address      | the `string` representing the address to check for balance |
| page         | the `integer` page number, if pagination is enabled        |
| offset       | the number of transactions displayed per page              |
| {% endtab %} |                                                            |

{% tab title="Response" %}
Sample Response

```
{
"message": "OK",
"status": "1",
"result": [
{
"TokenAddress": "0x4e3037297830c8023d1646937a3d44c018d1a5c3",
"TokenName": "RIPPLERICH",
"TokenSymbol": "RR",
"TokenQuantity": "1000000000000000000",
"TokenDivisor": "18"
},
{
"TokenAddress": "0x834a6cd4cc361e4b9b1694d2e9df3eeb0cb45c5a",
"TokenName": "Xinu",
"TokenSymbol": "XINU",
"TokenQuantity": "5000000000000000000000000",
"TokenDivisor": "18"
},
{
"TokenAddress": "0x9af596a20c94415bf87be8a0a9643c8b76e88dc9",
"TokenName": "BitcoinXTreasury",
"TokenSymbol": "BTCxT",
"TokenQuantity": "1",
"TokenDivisor": "18"
}
]
}
```

{% endtab %}
{% endtabs %}

## Get Address ERC721 Token Holding <img src="https://github.com/BlocksScan/Docs/blob/api/broken-reference" alt="" data-size="line">

Returns the ERC-721 tokens and amount held by an address.

{% hint style="warning" %}
**Note :** This endpoint is throttled to **2 calls/second** regardless of API Pro tier.
{% endhint %}

```
https://api.xdcscan.io/api
   ?module=account
   &action=addresstokennftbalance
   &address=xdcb6191f07e66a81ea6b0827cbe2e073ff2a8f5047
   &page=1
   &offset=100
   &apikey=YourApiKeyToken 
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=account\&action=addresstokennftbalance\&address=xdcb6191f07e66a81ea6b0827cbe2e073ff2a8f5047\&page=1\&offset=100\&apikey=YourApiKeyToken) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter    | Description                                                |
| ------------ | ---------------------------------------------------------- |
| address      | the `string` representing the address to check for balance |
| page         | the `integer` page number, if pagination is enabled        |
| offset       | the number of transactions displayed per page              |
| {% endtab %} |                                                            |

{% tab title="Response" %}
Sample Response

```
{
"message": "OK",
"status": "1",
"result": [
{
"TokenAddress": "0x134279d46ce98cca734d9a43cc3dda63a1ac755d",
"TokenName": "Prime Numbers PRNT NFT V3",
"TokenSymbol": "PRNTNFTv3",
"TokenQuantity": "14"
},
{
"TokenAddress": "0x9d458330e458f11fd1ce7e44b3a66568af8076a0",
"TokenName": "Prime Numbers XDC NFT V2",
"TokenSymbol": "XDCNFTv2",
"TokenQuantity": "106"
}
]
}
```

{% endtab %}
{% endtabs %}

## Get Address ERC721 Token Inventory By Contract Address <img src="https://github.com/BlocksScan/Docs/blob/api/broken-reference" alt="" data-size="line"> <a href="#get-address-erc721-token-inventory-by-contract-address" id="get-address-erc721-token-inventory-by-contract-address"></a>

Returns the ERC-721 token inventory of an address, filtered by contract address.

{% hint style="warning" %}
:pencil: **Note :** This endpoint is throttled to **2 calls/second** regardless of API Pro tier.
{% endhint %}

```
https://api.xdcscan.io/api
   ?module=account
   &action=addresstokennftinventory
   &address=xdcc2f3b189095e3931241b61ce584331dcec146cb9
   &contractaddress=0x134279d46ce98cca734d9a43cc3dda63a1ac755d
   &page=1
   &offset=100
   &apikey=YourApiKeyToken
```

> Try this endpoint in your [**browser**](https://api.xdcscan.io/api?module=account\&action=addresstokennftinventory\&address=xdcc2f3b189095e3931241b61ce584331dcec146cb9\&contractaddress=0x134279d46ce98cca734d9a43cc3dda63a1ac755d\&page=1\&offset=100\&apikey=YourApiKeyToken) :link:

{% tabs %}
{% tab title="Request" %}
Query Parameters

| Parameter       | Description                                                                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address         | the `string` representing the address to check for inventory                                                                                                          |
| contractaddress | the `string` representing the ERC-721 token contractaddress to check for inventory                                                                                    |
| page            | the `integer` page number, if pagination is enabled                                                                                                                   |
| offset          | <p>the number of records displayed per page<br><br>limited to <strong>1000 records</strong> per query, use the <code>page</code> parameter for subsequent records</p> |
| {% endtab %}    |                                                                                                                                                                       |

{% tab title="Response" %}
Sample Response

```
{
"message": "OK",
"status": "1",
"result": [
{
"TokenAddress": "0x134279d46ce98cca734d9a43cc3dda63a1ac755d",
"TokenId": "30"
}
]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blocksscan.io/api-endpoints/tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.