Returns ERC20 token balances for all tokens the given address has ever transacted in with. Optionally accepts a list of contracts.
Note on Token Balances
alchemy_getTokenBalances
returns not just token balances for ERC20 tokens. It also includes the native chain currency as well ex: ETH for Ethereum or Matic for Polygon.
Chain | Mainnet | Testnet |
---|---|---|
Ethereum | ✅ | ✅ |
Polygon | ✅ | ✅ |
Optimism | ✅ | ✅ |
Arbitrum | ✅ | ✅ |
Base | ✅ | ✅ |
zkSync Era | ✅ | ✅ |
Arbitrum Nova | ✅ | ✅ |
Parameters
- String, 20 Bytes - The address to check token balances for.
- One of the following token specifications, defaults to
erc20
- The String
erc20
- denotes the set of erc20 tokens that the address has ever held. - Array - A list of contract addresses. Suggested limit: 100 addresses [omitted below]
- The String
DEFAULT_TOKENS
- denotes a query for the top 100 tokens by 24 hour volume - only available on Mainnet for Ethereum, Polygon, and Arbitrum. [deprecated, please useerc20
instead]The
DEFAULT_TOKENS
option is deprecated.DEFAULT_TOKENS
was used to fetch the top 100 tokens by volume and show their balances for a given address. However, we now recommend using theerc20
option, which allows you to fetch all token balances for a given address, renderingDEFAULT_TOKENS
obsolete. AlthoughDEFAULT_TOKENS
might still function, we highly recommend transitioning to theerc20
option for future-proof operations.
- The String
- Options (optional) - An object that contains the following settings [omitted below]:
pageKey
: Applies only to theerc20
request type. A string address used for pagination. If more results are available, apageKey
will be returned in the response.maxCount
: Applies only to theerc20
request type. Specifies the maximum count of token balances to return per call. This value defaults to 100 and is currently capped at 100.
Returns
Object
- An object with the following fields:
address
:DATA
, 20 Bytes - The address for which token balances were checkedtokenBalances
:Array
- returns an array of token balance objects. Each object contains:contractAddress
tokenBalance
: hex encodederror
- One of
tokenBalance
orerror
will be null.
pageKey
:String
- Applies only to theerc20
request type. An address to be passed into thepageKey
of the next request in order to paginate through all of an owner's tokens.
Request
// alchemy-token-api/alchemy-web3-script.js
import { createAlchemyWeb3 } from "@alch/alchemy-web3";
// Replace with your Alchemy api key:
const apiKey = "demo";
// Initialize an alchemy-web3 instance:
const web3 = createAlchemyWeb3(
`https://eth-mainnet.g.alchemy.com/v2/${apiKey}`,
);
// The wallet address / token we want to query for:
const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
const balances = await web3.alchemy.getTokenBalances(ownerAddr,["0x607f4c5bb672230e8672085532f7e901544a7375"])
console.log("BALANCES->");
console.log(balances);
// alchemy-token-api/fetch-script.js
import fetch from 'node-fetch';
// Replace with your Alchemy API key:
const apiKey = "demo";
const fetchURL = `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`;
// Replace with the wallet address you want to query:
const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
// Replace with the token contract address you want to query:
const tokenAddr = "0x607f4c5bb672230e8672085532f7e901544a7375";
var raw = JSON.stringify({
"jsonrpc": "2.0",
"method": "alchemy_getTokenBalances",
"headers": {
"Content-Type": "application/json"
},
"params": [
`${ownerAddr}`,
[
`${tokenAddr}`,
]
],
"id": 42
});
var requestOptions = {
method: 'POST',
body: raw,
redirect: 'follow'
};
// Make the request and print the formatted response:
fetch(fetchURL, requestOptions)
.then(response => response.json())
.then(response => JSON.stringify(response, null, 2))
.then(result => console.log(result))
.catch(error => console.log('error', error));
// alchemy-token-api/axios-script.js
import axios from 'axios';
// Replace with your Alchemy API key:
const apiKey = "demo";
const baseURL = `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`;
// Replace with the wallet address you want to query:
const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
// Replace with the token contract address you want to query:
const tokenAddr = "0x607f4c5bb672230e8672085532f7e901544a7375";
var data = JSON.stringify({
"jsonrpc": "2.0",
"method": "alchemy_getTokenBalances",
"params": [
`${ownerAddr}`,
[
`${tokenAddr}`
]
],
"id": 42
});
var config = {
method: 'post',
url: baseURL,
headers: {
'Content-Type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data, null, 2))
})
.catch(function (error) {
console.log(error);
});
curl https://eth-mainnet.g.alchemy.com/v2/demo \
-X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"alchemy_getTokenBalances","params": ["0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be", "erc20"],"id":"42"}'
Result
{
"jsonrpc": "2.0",
"id": 0,
"result": {
"address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
"tokenBalances": [
{
"contractAddress": "0x0000000000085d4780b73119b644ae5ecd22b376",
"tokenBalance": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
......
{
"contractAddress": "0x0abefb7611cb3a01ea3fad85f33c3c934f8e2cf4",
"tokenBalance": "0x00000000000000000000000000000000000000000000039e431953bcb76c0000"
},
{
"contractAddress": "0x0ad0ad3db75ee726a284cfafa118b091493938ef",
"tokenBalance": "0x0000000000000000000000000000000000000000008d00cf60e47f03a33fe6e3"
}
],
"pageKey": "0x0ad0ad3db75ee726a284cfafa118b091493938ef"
}
}
Use Cases
For guidance on how to leverage this method, check out the following tutorials:
Limited Param Selection Below
Due to the limitations of OpenAPI, the below code sample is only compatible for
erc20
orDEFAULT_TOKEN
specifications (not an arbitrary token array). However,erc20
will return all tokens that the address has ever owned so it will be comprehensive ✅