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
Polygon
Optimism
Arbitrum
Base
zkSync Era

Parameters


  1. String, 20 Bytes - The address to check token balances for.
  2. One of the following token specifications, defaults to erc20
    1. The String erc20 - denotes the set of erc20 tokens that the address has ever held.
    2. Array - A list of contract addresses. Suggested limit: 100 addresses [omitted below]
    3. 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 use erc20 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 the erc20 option, which allows you to fetch all token balances for a given address, rendering DEFAULT_TOKENS obsolete. Although DEFAULT_TOKENS might still function, we highly recommend transitioning to the erc20 option for future-proof operations.

  3. Options (optional) - An object that contains the following settings [omitted below]:
    1. pageKey: Applies only to the erc20 request type. A string address used for pagination. If more results are available, a pageKey will be returned in the response.
    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!