Token API Quickstart

A new developer’s guide to using the Token API and getting token information. Query Token data using alchemy-web3 (recommended) or fetch.

New CU Costs

Build and scale apps with lower CU costs on key APIs

How CU costs work

With the Token API, you can retrieve token balances, metadata, and more.

Alchemy currently supports the following Token API Endpoints:

  • alchemy_getTokenAllowance: Returns the amount which the sender is allowed to withdraw from the owner.
  • alchemy_getTokenBalances : Returns ERC20 token balances for all tokens the given address has ever transacted in with. Optionally accepts a list of contracts.
  • alchemy_getTokenMetadata: Returns metadata (name, symbol, decimals, logo) for a given token contract address.

Interested in token prices? Check out the Prices API.

Unless otherwise specified, Alchemy methods will return decoded values in their responses (e.g., for token decimals, 18 will be returned instead of “0x12”) to save you the extra step of decoding the value yourself ✅


How to Query the Token API

Install the alchemy-sdk module to easily interact with Alchemy APIs. We highly recommend the alchemy-sdk for WebSocket support, retries, and more.

Check the Github repo here: https://github.com/alchemyplatform/alchemy-sdk-js

Installation

Run the following command to install alchemy-sdk with npm or yarn

$npm install alchemy-sdk

Usage

token-api-javascript-scripts/alchemy-web3-script.js at main · alchemyplatform/token-api-javascript-scripts

github.comgithub.com

token-api-javascript-scripts/alchemy-web3-script.js at main · alchemyplatform/token-api-javascript-scripts

shell
$touch alchemy-sdk-script.js

And then paste the following code snippet into the file:

alchemy-sdk-script.js
1import { Alchemy, Network } from "alchemy-sdk";
2
3const settings = {
4 apiKey: "demo", // Replace with your Alchemy API Key.
5 network: Network.ETH_MAINNET, // Replace with your network.
6};
7const alchemy = new Alchemy(settings);
8
9// The wallet address / token we want to query for:
10const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
11const balances = await alchemy.core.getTokenBalances(ownerAddr, [
12 "0x607f4c5bb672230e8672085532f7e901544a7375",
13]);
14
15// The token address we want to query for metadata:
16const metadata = await alchemy.core.getTokenMetadata(
17 "0x607f4c5bb672230e8672085532f7e901544a7375"
18);
19
20console.log("Token Balances:");
21console.log(balances);
22console.log("Token Metadata: ");
23console.log(metadata);

From your command line, you can execute the script with:

shell
$node alchemy-sdk-script.js

You should see output like this:

shell
$Token Balances:
>{
> address: '0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be',
> tokenBalances: [
> {
> contractAddress: '0x607f4c5bb672230e8672085532f7e901544a7375',
> tokenBalance: '0x0000000000000000000000000000000000000000000000000000000000000000',
> error: null
> }
> ]
>}
>Token Metadata:
>{
> decimals: 9,
> logo: 'https://static.alchemyapi.com/images/assets/1637.png',
> name: 'iExec RLC',
> symbol: 'RLC'
>}

Node Fetch

node-fetch is a lightweight, common module for making HTTP requests.

See the documentation for more info: https://www.npmjs.com/package/node-fetch

Installation

Run the following command to install node-fetch with npm or yarn

$npm install node-fetch

Usage

token-api-javascript-scripts/fetch-script.js at main · alchemyplatform/token-api-javascript-scripts

github.comgithub.com

token-api-javascript-scripts/fetch-script.js at main · alchemyplatform/token-api-javascript-scripts

shell
$touch fetch-script.js

and then paste the following code snippet into the file to explore the getNFTs method:=

fetch-script.js
1// alchemy-token-api/fetch-script.js
2import fetch from 'node-fetch';
3
4// Replace with your Alchemy API key:
5const apiKey = "demo";
6const fetchURL = `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`;
7
8// Replace with the wallet address you want to query:
9const ownerAddr = "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be";
10// Replace with the token contract address you want to query:
11const tokenAddr = "0x607f4c5bb672230e8672085532f7e901544a7375";
12
13var 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
28var requestOptions = {
29 method: 'POST',
30 body: raw,
31 redirect: 'follow'
32};
33
34// Make the request and print the formatted response:
35fetch(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));

From your command line, you can execute the script with:

shell
$node fetch-script.js

Your output should look like the following:

json
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}

API Reference

For more details on the available Token API methods, check out the docs:

Token API Endpoints

docs.alchemy.com

Token API Endpoints