Token Balances By Wallet

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 and Option 2 > Token Specification. Alternatively, use the Alchemy Sandbox.
  • Due to the limitations of OpenAPI, the composer below only accepts erc20 or DEFAULT_TOKEN specifications.
Language
URL
Click Try It! to start a request and see the response here!
ReadMe