post https://{network}.g.alchemy.com/v2/
alchemy_getTokenBalances - Returns ERC20 token balances for all tokens the given address has ever transacted in with. Optionally accepts a list of contracts. This endpoint is supported on Ethereum and many L2s, including Polygon, Arbitrum, Optimism, Base, World Chain and more. See the full list of supported networks here.
Sample Request
curl https://eth-mainnet.g.alchemy.com/v2/{API_KEY} \
-X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"alchemy_getTokenBalances","params": ["0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be", "erc20"],"id":"42"}'
// 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);
});
Sample Response
{
"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:
Testing via Request Composer
- To test via below composer, click
Address
for the first param andOption 2
>Token Specification
. Alternatively, use the Alchemy Sandbox.- Due to the limitations of OpenAPI, the composer below only accepts
erc20
orDEFAULT_TOKEN
specifications.