# 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 %}