alchemy_getTokenBalances
Returns token balances for a specific address given a list of contracts.
This method returns hex encoded values in the tokenBalance fields.

Parameters

  1. 1.
    DATA, 20 Bytes - The address for which token balances will be checked
  2. 2.
    One of:
    1. 1.
      Array - A list of contract addresses. Suggested limit: 100 addresses
    2. 2.
      The String"DEFAULT_TOKENS" - denotes a query for the top 100 tokens by 24 hour volume

Returns

Object - An object with the following fields:
  • address: DATA, 20 Bytes - The address for which token balances were checked
  • tokenBalances: Array - returns an array of token balance objects. Each object contains:
    • contractAddress
    • tokenBalance
    • error
    • One of tokenBalance or error will be null.

Example

Request

Alchemy Web3
Fetch (JS)
Axios (JS)
Curl
Postman
1
// alchemy-token-api/alchemy-web3-script.js
2
import { createAlchemyWeb3 } from "@alch/alchemy-web3";
3
4
// Replace with your Alchemy api key:
5
const apiKey = "demo";
6
7
// Initialize an alchemy-web3 instance:
8
const web3 = createAlchemyWeb3(
9
`https://eth-mainnet.g.alchemy.com/v2/${apiKey}`,
10
);
11
12
// The wallet address / token we want to query for:
13
const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
14
const balances = await web3.alchemy.getTokenBalances(ownerAddr,["0x607f4c5bb672230e8672085532f7e901544a7375"])
15
16
console.log("BALANCES->");
17
console.log(balances);
Copied!
1
// alchemy-token-api/fetch-script.js
2
import fetch from 'node-fetch';
3
4
// Replace with your Alchemy API key:
5
const apiKey = "demo";
6
const fetchURL = `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`;
7
8
// Replace with the wallet address you want to query:
9
const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
10
// Replace with the token contract address you want to query:
11
const tokenAddr = "0x607f4c5bb672230e8672085532f7e901544a7375";
12
13
var raw = JSON.stringify({
14
"jsonrpc": "2.0",
15
"method": "alchemy_getTokenBalances",
16
"headers": {
17
"Content-Type": "application/json"
18
},
19
"params": [
20
`${ownerAddr}`,
21
[
22
`${tokenAddr}`,
23
]
24
],
25
"id": 42
26
});
27
28
var requestOptions = {
29
method: 'POST',
30
body: raw,
31
redirect: 'follow'
32
};
33
34
// Make the request and print the formatted response:
35
fetch(fetchURL, requestOptions)
36
.then(response => response.json())
37
.then(response => JSON.stringify(response, null, 2))
38
.then(result => console.log(result))
39
.catch(error => console.log('error', error));
Copied!
1
// alchemy-token-api/axios-script.js
2
import axios from 'axios';
3
4
// Replace with your Alchemy API key:
5
const apiKey = "demo";
6
const baseURL = `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`;
7
// Replace with the wallet address you want to query:
8
const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
9
// Replace with the token contract address you want to query:
10
const tokenAddr = "0x607f4c5bb672230e8672085532f7e901544a7375";
11
12
var data = JSON.stringify({
13
"jsonrpc": "2.0",
14
"method": "alchemy_getTokenBalances",
15
"params": [
16
`${ownerAddr}`,
17
[
18
`${tokenAddr}`
19
]
20
],
21
"id": 42
22
});
23
24
var config = {
25
method: 'post',
26
url: baseURL,
27
headers: {
28
'Content-Type': 'application/json'
29
},
30
data : data
31
};
32
33
axios(config)
34
.then(function (response) {
35
console.log(JSON.stringify(response.data, null, 2))
36
})
37
.catch(function (error) {
38
console.log(error);
39
});
Copied!
1
curl https://eth-mainnet.alchemyapi.io/v2/your-api-key \
2
-X POST \
3
-H "Content-Type: application/json" \
4
-d '{"jsonrpc":"2.0","method":"alchemy_getTokenBalances","params": ["0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be", ["0x607f4c5bb672230e8672085532f7e901544a7375", "0x618e75ac90b12c6049ba3b27f5d5f8651b0037f6", "0x63b992e6246d88f07fc35a056d2c365e6d441a3d", "0x6467882316dc6e206feef05fba6deaa69277f155", "0x647f274b3a7248d6cf51b35f08e7e7fd6edfb271"]],"id":"42"}'
Copied!
1
URL: https://eth-mainnet.alchemyapi.io/v2/your-api-key
2
RequestType: POST
3
Body:
4
{
5
"jsonrpc":"2.0",
6
"method":"alchemy_getTokenBalances",
7
"params":["0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be", ["0x607f4c5bb672230e8672085532f7e901544a7375", "0x618e75ac90b12c6049ba3b27f5d5f8651b0037f6", "0x63b992e6246d88f07fc35a056d2c365e6d441a3d", "0x6467882316dc6e206feef05fba6deaa69277f155", "0x647f274b3a7248d6cf51b35f08e7e7fd6edfb271"]],
8
"id":42
9
}
Copied!

Result

1
{
2
"jsonrpc": "2.0",
3
"id": 42,
4
"result": {
5
"address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
6
"tokenBalances": [
7
{
8
"contractAddress": "0x607f4c5bb672230e8672085532f7e901544a7375",
9
"tokenBalance": "0x00000000000000000000000000000000000000000000000000003c005f81ab00",
10
"error": null
11
}
12
]
13
}
14
}
Copied!

Use Cases

For guidance on how to leverage this method, check out the following tutorials: