post https://eth-mainnet.g.alchemy.com/v2/
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
only returns token balances for ERC20 tokens (this does not include the native chain currency ex: ETH for Ethereum or Matic for Polygon, nor any other non-ERC20 token balance for the given address)- To get token balances for the native chain currency please use eth_getBalance
Chain | Mainnet | Testnet |
---|---|---|
Ethereum | ![]() | ![]() |
Polygon | ![]() | ![]() |
Optimism | ![]() | ![]() |
Arbitrum | ![]() | ![]() |
Parameters
DATA
, 20 Bytes - The address for which token balances will be checked- One of:
Array
- A list of contract addresses. Suggested limit:100
addresses.- 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. - The
String
"erc20" - denotes the set of erc20 tokens that the address has ever held. This list is produced by an address's historical transfer activity and includes all tokens that the address has ever received.
- Options (optional) - An object that contains the following settings:
pageKey
: Applies only to theerc20
request type. Used to paginate through tokens that an owner has held.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 ✅