alchemy_getTokenBalances

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
ChainMainnetTestnet
Ethereum:white-check-mark::white-check-mark:
Polygon:white-check-mark::white-check-mark:
Optimism:white-check-mark::white-check-mark:
Arbitrum:white-check-mark::white-check-mark:

Parameters


  1. DATA, 20 Bytes - The address for which token balances will be checked
  2. One of:
    1. Array - A list of contract addresses. Suggested limit: 100 addresses.
    2. 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.
    3. 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.
  3. Options (optional) - An object that contains the following settings:
    1. pageKey: Applies only to the erc20 request type. Used to paginate through tokens that an owner has held.
    2. maxCount: Applies only to the erc20 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 checked
  • tokenBalances: Array - returns an array of token balance objects. Each object contains:
    • contractAddress
    • tokenBalance: hex encoded
    • error
    • One of tokenBalance or error will be null.
  • pageKey: String - Applies only to the erc20 request type. An address to be passed into the pageKey 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 or DEFAULT_TOKEN specifications (not an arbitrary token array). However, erc20 will return all tokens that the address has ever owned so it will be comprehensive ✅

Language
URL
Click Try It! to start a request and see the response here!