🚀
Introduction
✨
Enhanced APIs
⛓
Chain APIs
📖
Documentation
💻
Tutorials
📜
Guides
📚
Resources
How to get transaction history for an address on Ethereum
Learn how to get the full transaction history for a smart contract or a user address including external, internal, token, ERC-20, ERC-721 and ERC-1155 token transfers in a single request.
A few reasons for why you'd want to get address transaction history by an address:
- Displaying your a user’s full transaction history
- Querying an address's transactions filtered by smart contract interactions
- Analyzing a user's historical profit and loss
Regardless of the different types of transaction history you want to look up, this process can be extremely burdensome for developers to stitch together without the Alchemy Transfers API.
In this tutorial, we’ll be using Alchemy’s Transfers API to fetch all transactions sent
from and sent to addresses you care about to create a complete picture of a user's transaction history.How to query transaction history
When using the Transfers API for querying a user’s full on-chain history, its important to have a few key parameters on hand.
fromAddress: the address we want to see transaction information originating fromtoAddress: the address we want to see for recipient-based transactionsfromBlock: the starting time range we want to fetch transactions over (defaults tolatest)toBlock: the ending time range we want to fetch transactions over (defaults tolatest)category: the type of transfer events we care about, in our case we want to see all transactions so we can simply let the param use its default argument of ["external", "internal", "token"]
For transaction information that originates from your target sender address, use the
fromAddress parameter within the Transfers API. For recipient-based transactions, use the toAddress parameter. If you want to get transactions that have a specific from AND to address, you can specify the
fromAddressandtoAddress in your request.Example: Getting Transactions Originating From An Address
From An AddressNo-code Example
Alchemy Web3.js (Recommended)
Node-Fetch
Axios
transfers_api_javascript_scripts/tx-history-from-alchemyweb3.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Tx History GitHub Repo
If you don't already have Alchemy Web3 installed, you can install the
alchemy-web3 module to easily interact with Alchemy APIs. We highly recommend using the alchemy-web3 sdk because you also get websocket support, retries, and other benefits without the complexity!1. Create a file.
In your current directory, create a new file called
alchemy-web3-transfers-from-script.js
Use your favorite file browser, code editor, or just directly in the terminal using the
touch command like this:1
touch tx-history-from-alchemyweb3.js
Copied!
2. Write script!
Copy and paste in the following code snippet into your new file:
tx-history-from-alchemyweb3.js
tx-history-from-alchemyweb3.js
1
import { createAlchemyWeb3 } from "@alch/alchemy-web3";
2
3
// Replace with your Alchemy api key:
4
const apiKey = "demo";
5
6
// Initialize an alchemy-web3 instance:
7
const web3 = createAlchemyWeb3(
8
`https://eth-mainnet.alchemyapi.io/v2/${apiKey}`,
9
);
10
11
const data = await web3.alchemy.getAssetTransfers({
12
fromBlock: "0x0",
13
fromAddress: "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1",
14
})
15
16
// Print response:
17
console.log(data);
Copied!
3. Run script!
Now, on your command line, you can execute the script by calling:
1
node alchemy-web3-transfers-from-script.js
Copied!
If you're using
node-fetch a lightweight, common module that brings the Fetch API to Node.js and allows us to make our HTTP requests, here's a code snipper for the request you'd make!transfers_api_javascript_scripts/tx-history-from-axios.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Tx History GitHub Repo
1. Create a file.
In your current directory, create a new file called
tx-history-from-fetch.js using your favorite file browser, code editor, or just directly in the terminal using the touch command like this:1
touch tx-history-from-fetch.js
Copied!
2. Write script!
Copy and paste in the following code snippet into your new file:
tx-history-from-fetch.jstx-history-from-fetch.js
1
import fetch from 'node-fetch';
2
3
let data = JSON.stringify({
4
"jsonrpc": "2.0",
5
"id": 0,
6
"method": "alchemy_getAssetTransfers",
7
"params": [
8
{
9
"fromBlock": "0x0",
10
"fromAddress": "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1",
11
}
12
]
13
});
14
15
16
var requestOptions = {
17
method: 'POST',
18
headers: { 'Content-Type': 'application/json' },
19
body: data,
20
redirect: 'follow'
21
};
22
23
const apiKey = "demo"
24
const baseURL = `https://eth-mainnet.alchemyapi.io/v2/${apiKey}`;
25
const fetchURL = `${baseURL}`;
26
27
fetch(fetchURL, requestOptions)
28
.then(response => response.json())
29
.then(response => JSON.stringify(response, null, 2))
30
.then(result => console.log(result))
31
.catch(error => console.log('error', error));
Copied!
3. Run script!
Now, on your command line, you can execute the script by calling:
1
node tx-history-from-fetch.js
Copied!
If you're using Javascript
axios, a promise-based HTTP client for the browser and Node.js which allows us to make a raw request to the Alchemy API, here's a code snipper for the request you'd make!transfers_api_javascript_scripts/tx-history-from-fetch.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Tx History Github Repo
1. Create a file.
In your current directory, create a new file called
tx-history-from-axios.js using your favorite file browser, code editor, or just directly in the terminal using the touch command. 1
touch tx-history-from-axios.js
Copied!
2. Write script!
Copy and paste in the following code snippet into your new file:
tx-history-from-axios.jstx-history-from-axios.js
1
import axios from 'axios';
2
3
let data = JSON.stringify({
4
"jsonrpc": "2.0",
5
"id": 0,
6
"method": "alchemy_getAssetTransfers",
7
"params": [
8
{
9
"fromBlock": "0x0",
10
"fromAddress": "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1",
11
}
12
]
13
});
14
15
var requestOptions = {
16
method: 'post',
17
headers: { 'Content-Type': 'application/json' },
18
data: data,
19
};
20
21
const apiKey = "demo"
22
const baseURL = `https://eth-mainnet.alchemyapi.io/v2/${apiKey}`;
23
const axiosURL = `${baseURL}`;
24
25
axios(axiosURL, requestOptions)
26
.then(response => console.log(JSON.stringify(response.data, null, 2)))
27
.catch(error => console.log(error));
Copied!
3. Run script!
Now, on your command line, you can execute the script by calling:
1
node tx-history-from-axios.js
Copied!
Example: Getting Recipient-based Transactions
No-code Example
Alchemy Web3.js (Recommended)
Node-Fetch
Axios
transfers_api_javascript_scripts/tx-history-to-alchemyweb3.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Tx History GitHub Repo
If you don't already have Alchemy Web3 installed, you can install the
alchemy-web3 module to easily interact with Alchemy APIs. We highly recommend using the alchemy-web3 sdk because you also get websocket support, retries, and other benefits without the complexity!
1. Create a file.
In your current directory, create a new file called
alchemy-web3-transfers-to-script.jsUse your favorite file browser, code editor, or just directly in the terminal using the
touch command like this:1
touch alchemy-web3-transfers-to-script.js
Copied!
2. Write script!
Copy and paste in the following code snippet into your new file:
alchemy-web3-transfers-to-script.js
1
import { createAlchemyWeb3 } from "@alch/alchemy-web3";
2
3
// Replace with your Alchemy api key:
4
const apiKey = "demo";
5
6
// Initialize an alchemy-web3 instance:
7
const web3 = createAlchemyWeb3(
8
`https://eth-mainnet.alchemyapi.io/v2/${apiKey}`,
9
);
10
11
const data = await web3.alchemy.getAssetTransfers({
12
fromBlock: "0x0",
13
toAddress: "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1",
14
})
15
16
// Print response:
17
console.log(data);
Copied!
3. Run script!
Now, on your command line, you can execute the script by calling:
1
node alchemy-web3-transfers-to-script.js
Copied!
If you're using
node-fetch a lightweight, common module that brings the Fetch API to Node.js and allows us to make our HTTP requests, here's a code snipper for the request you'd make!transfers_api_javascript_scripts/tx-history-to-fetch.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Tx History GitHub Repo
1. Create a file.
In your current directory, create a new file called
fetch-transfers-to-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command like this:1
touch fetch-transfers-to-script.js
Copied!
2. Write script!
Copy and paste in the following code snippet into your new file:
fetch-transfers-to-script.js
1
import fetch from 'node-fetch';
2
3
let data = JSON.stringify({
4
"jsonrpc": "2.0",
5
"id": 0,
6
"method": "alchemy_getAssetTransfers",
7
"params": [
8
{
9
"fromBlock": "0x0",
10
"toAddress": "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1",
11
}
12
]
13
});
14
15
16
var requestOptions = {
17
method: 'POST',
18
headers: { 'Content-Type': 'application/json' },
19
body: data,
20
redirect: 'follow'
21
};
22
23
const apiKey = "demo"
24
const baseURL = `https://eth-mainnet.alchemyapi.io/v2/${apiKey}`;
25
const fetchURL = `${baseURL}`;
26
27
fetch(fetchURL, requestOptions)
28
.then(response => response.json())
29
.then(response => JSON.stringify(response, null, 2))
30
.then(result => console.log(result))
31
.catch(error => console.log('error', error));
Copied!
3. Run script!
Now, on your command line, you can execute the script by calling:
1
node fetch-transfers-from-script.js
Copied!
If you're using Javascript
axios, a promise-based HTTP client for the browser and Node.js which allows us to make a raw request to the Alchemy API, here's a code snipper for the request you'd make!transfers_api_javascript_scripts/tx-history-to-axios.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Tx History GitHub Repo
1. Create a file.
In your current directory, create a new file called
axios-transfers-to-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command. 1
touch axios-transfers-to-script.js
Copied!
2. Write script!
Copy and paste in the following code snippet into your new file:
axios-transfers-to-script.js1
import axios from 'axios';
2
3
let data = JSON.stringify({
4
"jsonrpc": "2.0",
5
"id": 0,
6
"method": "alchemy_getAssetTransfers",
7
"params": [
8
{
9
"fromBlock": "0x0",
10
"toAddress": "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1",
11
}
12
]
13
});
14
15
16
var requestOptions = {
17
method: 'post',
18
headers: { 'Content-Type': 'application/json' },
19
data: data,
20
};
21
22
const apiKey = "demo"
23
const baseURL = `https://eth-mainnet.alchemyapi.io/v2/${apiKey}`;
24
const axiosURL = `${baseURL}`;
25
26
axios(axiosURL, requestOptions)
27
.then(response => console.log(JSON.stringify(response.data, null, 2)))
28
.catch(error => console.log(error));
Copied!
3. Run script!
Now, on your command line, you can execute the script by calling:
1
node axios-transfers-to-script.js
Copied!
How to process the API response
Now that we have made a query and can see the response, let's learn how to handle it.
If you feel like jumping ahead and grabbing some pre-built code, choose a repo that matches your preferred library.
Alchemy Web3 (Recommended)
Node-Fetch
Axios
Parsing with Alchemy Web3 Responses
Alchemy Web3 Responsestransfers_api_javascript_scripts/tx-history-parsed-alchemyweb3.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Parsing with Node-Fetch Responses
Node-Fetch Responsestransfers_api_javascript_scripts/tx-history-parsed-fetch.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Parsing with Axios Responses
Axios Responsestransfers_api_javascript_scripts/tx-history-parsed-axios.js at main · alchemyplatform/transfers_api_javascript_scripts
GitHub
Raw API Response:
Without parsing the response, we have a console log that looks as follows.
1
{
2
transfers: [
3
{
4
blockNum: '0xb7389b',
5
hash: '0xfde2a5157eda40b90514751f74e3c7314f452a41890b19a342ee147f5336dfd6',
6
from: '0x5c43b1ed97e52d009611d89b74fa829fe4ac56b1',
7
to: '0xe9b29ae1b4da8ba5b1de76bfe775fbc5e25bc69a',
8
value: 0.245,
9
erc721TokenId: null,
10
erc1155Metadata: null,
11
tokenId: null,
12
asset: 'ETH',
13
category: 'external',
14
rawContract: [Object]
15
},
16
17
......
18
19
{
20
blockNum: '0xcf5dea',
21
hash: '0x701f837467ae3112d787ddedf8051c4996ea82914f7a7735cb3db2d805799286',
22
from: '0x5c43b1ed97e52d009611d89b74fa829fe4ac56b1',
23
to: '0x92560c178ce069cc014138ed3c2f5221ba71f58a',
24
value: 152.89962568845024,
25
erc721TokenId: null,
26
erc1155Metadata: null,
27
tokenId: null,
28
asset: 'ENS',
29
category: 'token',
30
rawContract: [Object]
31
},
32
{
33
blockNum: '0xd14898',
34
hash: '0x2f5d93a9db65548eb43794aa43698acd653e6b2df35c6028b8599a234f2c6dc0',
35
from: '0x5c43b1ed97e52d009611d89b74fa829fe4ac56b1',
36
to: '0x83abecf7204d5afc1bea5df734f085f2535a9976',
37
value: 27579.060635486854,
38
erc721TokenId: null,
39
erc1155Metadata: null,
40
tokenId: null,
41
asset: 'PEOPLE',
42
category: 'token',
43
rawContract: [Object]
44
}
45
]
46
}
Copied!
Understanding API Response:
blockNum: the block number where a transaction event occurred, inhexhash: the transaction hash of a transactionfrom: where the transaction originated fromto: where ETH or another asset was transferred tovalue: the amount of ETH transferrederc721TokenId: the ERC721 token ID.nullif not an ERC721 token transfer.erc1155Metadata: a list of objects containing the ERC1155tokenIdandvalue.nullif not an ERC1155 transfertokenId: the token ID for ERC721 tokens or other NFT token standardsasset:ETHor the token's symbol.nullif not defined in the contract and not available from other sources.rawContractvalue: raw transfer value denominated in the relevant Ethereum tokenaddress: Ethereum token contract addressdecimal: contract decimal
Printing out the asset and value
asset and value Two of the many different response objects you may be interested in parsing are:
asset and value. Let's walk through an example that parses the returned JSON object.
Whether we're querying via
alchemy web3, axios, or node-fetch, we'll need to save the queried response object into a constant.Alchemy Web3 (Recommended)
Node-Fetch
Axios
Saving response objects with Alchemy Web3
Alchemy Web31
// Alchemy Web3
2
3
const res = await web3.alchemy.getAssetTransfers({
4
fromBlock: "0x0",
5
toAddress: "0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1",
6
})
Copied!
Saving response objects with Node-Fetch
Node-Fetch1
// Node-Fetch
2
3
fetch(fetchURL, requestOptions)
4
.then((res) => {
5
return res.json()
6
})
7
.then((jsonResponse) => {
8
//Print token name / asset value
9
for (const events of jsonResponse.result.transfers) {
10
console.log("Token Transfer: ", events.value, " ", events.asset);
11
}
12
})
13
.catch((err) => {
14
// handle error
15
console.error(err);
16
});
17
Copied!
Saving response objects with Axios
Axios1
// Axios
2
3
const res = await axios(axiosURL, requestOptions);
Copied!
With our queried response object saved as a constant, we can now index through the transfers.
In particular, the steps we take are:
- 1.Loop through all transfers in the result
- 2.Print each element's
valueandassetfield
1
// Print token asset name and its associated value
2
for (const events of res.data.result.transfers) {
3
console.log("Token Transfer: ", events.value, " ", events.asset);
4
}
5
Copied!
If you followed along, your response should look like the following:
1
Token Transfer: 0.5 ETH
2
Token Transfer: 0.27 ETH
3
Token Transfer: 9.90384 ETH
4
Token Transfer: 0.07024968 ETH
5
Token Transfer: 0.000447494250654841 ETH
6
Token Transfer: null null
7
Token Transfer: 0.075 ETH
8
Token Transfer: 0.003 ETH
9
Token Transfer: null BURN
10
Token Transfer: 54 DAI
11
Token Transfer: 12.5 GTC
12
Token Transfer: 2 GTC
13
Token Transfer: 0.42 ETH
14
........
15
Token Transfer: 0.588 WETH
16
Token Transfer: null null
17
Token Transfer: null null
18
Token Transfer: 2.3313024 ETH
19
Token Transfer: 0.0633910153108353 ETH
20
Token Transfer: 0.0335 ETH
21
Token Transfer: 2 GTC
Copied!
And that's it! You've now learned how to fetch transaction history for address on Ethereum. For more, check out the tutorial below:
If you enjoyed this tutorial for getting address transaction history on Ethereum, give us a tweet @AlchemyPlatform! (Or give the author @crypt0zeke a shoutout!)