Skip to main content

Advanced API quickstart: Get transaction history for an Ethereum address

The Node Advanced API allows you to simplify and optimize common types of Ethereum requests. This API supplements the basic Ethereum node JSON-RPC API, available from any Ethereum node provider, so you can make fewer API calls to get the data you want, and more easily develop on the blockchain.

In this tutorial you will get the full transaction history for a user address including external, internal, token, ERC-20 and ERC-721 token transfers in a single request.

Why get address transaction history?

  • Display a user's full transaction history
  • Query an address's transactions filtered by smart contract interactions
  • Analyze a user's historical profit and loss

Prerequisites

caution

If you're using a Windows machine as your dev environment, you can run through this tutorial as-written by using Windows Subsystem for Linux

Create a project and get API keys

To get started using the Coinbase Node Advanced API, sign in to your Coinbase Cloud account:

Sign in to Coinbase Cloud Console screen

Create project

After you sign in you'll be prompted to set up your first project.

Select a plan and enter a name for your project.

Create a project screen

Get API keys

After creating a project, you will receive the following API access credentials:

  • API Access Token Username (e.g. username)

  • API Access Token Password (e.g. password)

    API token modal

Copy and save these API access credentials to a secure location. You will need them later in order to make API requests.

caution

You can return to the project dashboard to retrieve your endpoint and username, however your password is not saved.

If you lose your project password, you will need to create a new project.

Once your project is created, you can visit the dashboard to view other information, such as the endpoint (https://mainnet.ethereum.coinbasecloud.net).

Empty project

Make a request and process the response

Now, you will use the information you copied to make a request to the Advanced APIs.

Make request

Open your terminal and run the following command, replacing <username>, and <password> with the values you copied from the previous step:

curl https://mainnet.ethereum.coinbasecloud.net/ \
-u <username>:<password> \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"method": "coinbaseCloud_getTransactionsByAddress",
"params": {
"address": "0x3cd751e6b0078be393132286c442345e5dc49699",
"blockStart": "0xe6e8f1"
"addressFilter": "RECEIVER_ONLY"
},
"id": 1,
"jsonrpc": "2.0"
}'
info

username and password are provided as Basic Authentication Credentails of the request.

These credentials can also be provided as part of the URL: https://<username>:<password>mainnet.ethereum.coinbasecloud.net.

This call to getTransactionsByAddress specifies:

ParamValueDescription
address"0x3cd751e6b0078be393132286c442345e5dc49699"REQUIRED. Ethereum address of transactions you are retrieving
blockStart"0xe6e8f1"REQUIRED. Block number to start scanning for transactions
addressFilter"RECEIVER_ONLY"Filters returned transactions to sender or receiver. Defaults to "SENDER_OR_RECEIVER"

Get the response

You should get a JSON response back that looks similar to this:

{
"id": 1,
"jsonrpc": "2.0",
"result": {
"transactions": [
{
"transactionHash": "0x1ebb2662ef10073cf9425d3621ce454f12bc41253e5414d40a26aba047306127",
"transactionIndex": "0x67",
"from": "0x753a22a0e40efa91b8074e8b816f74ef4d16d7c4",
"to": "0x3cd751e6b0078be393132286c442345e5dc49699",
"value": "0x4d8e86f85988a2c",
"gasLimit": "0x5208",
"gasPrice": "0x5ba6151e7",
"gasUsed": "0x5208",
"cumulativeGasUsed": "0x79e477",
"status": "0x1",
"input": "0x",
"nonce": "0x3",
"blockHash": "0xe712aaa48fa60ae9dd34a43377e410c69400ec4af4965bedb9000753dba1a5f3",
"blockNumber": "0xf19db2",
"blockTimestamp": "0x6359940b"
},
{
"transactionHash": "0x637ea407cec3bd49b21e616639d2bb5b86ac7260a0b6a13aa24439ae599c241d",
"transactionIndex": "0x65",
"from": "0x1c8d622c3c38118ab1f907adca812796c66d7b65",
"to": "0x3cd751e6b0078be393132286c442345e5dc49699",
"value": "0x4d8d786a84da600",
"gasLimit": "0x5208",
"gasPrice": "0x5ba6151e7",
"gasUsed": "0x5208",
"cumulativeGasUsed": "0x747dcc",
"status": "0x1",
"input": "0x",
"nonce": "0x1",
"blockHash": "0xe712aaa48fa60ae9dd34a43377e410c69400ec4af4965bedb9000753dba1a5f3",
"blockNumber": "0xf19db2",
"blockTimestamp": "0x6359940b"
},
{
"...": "output truncated."
}
]
}
}

Understand the response

This response gives a list of transactions. Each transaction includes details about the transaction and it's associated block. Since we specified "RECEIVER_ONLY", the returned transactions will include only those which the specified address was the recipient.

The response returns a lot of information, we will only cover the highlights here. See the API docs for full documentation of the response values.

  • transactions: a list of relevant transactions for the specified block range
    • from: origin address
    • to: destination address
    • value: value in native blockchain currency
    • status: "0x1" (Success), "0x0" (Failure)
    • blockNumber: the corresponding block number for the transaction

Handle pagination

Note that in your API call, you requested all of the transactions starting from block number 0xe6e8f1, but the response only included 1000 transactions. This is because the API response is paginated and will return no more than 1000 transactions for the specified block range.

To get the rest of the transactions, we'll need to make additional API calls, making use of the following pagination parameters:

ParamTypeDescription
sortStringThe sorting preference, use asc to sort by ascending and desc to sort by descending. The default is desc.
pageSizeIntegerThe number of transactions displayed per page. The default and max value are 1000.
pageNumberIntegerThe integer page number, if pagination is enabled. It starts with 1.

To demonstrate pagination, we'll request the first two pages of transactions, specifying a page size of 1000 transactions per page in descending order.

info

The following examples use the CLI tool jq to format the API response before it's save it to a file.

Make an initial API call and save the response to a file named response1.json:

curl https://mainnet.ethereum.coinbasecloud.net/ \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"method": "coinbaseCloud_getTransactionsByAddress",
"params": {
"address": "0x3cd751e6b0078be393132286c442345e5dc49699",
"blockStart": "0xe6e8f1",
"addressFilter": "RECEIVER_ONLY",
"sort": "desc",
"pageSize": 1000,
"pageNumber": 1
},
"id": 1,
"jsonrpc": "2.0"
}' | jq '.' > response1.json

Next, make a second API call to get the second page of the transactions and save it into a file named response2.json

curl https://mainnet.ethereum.coinbasecloud.net/ \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"method": "coinbaseCloud_getTransactionsByAddress",
"params": {
"address": "0x3cd751e6b0078be393132286c442345e5dc49699",
"blockStart": "0xe6e8f1",
"addressFilter": "RECEIVER_ONLY",
"sort": "desc",
"pageSize": 1000,
"pageNumber": 2
},
"id": 1,
"jsonrpc": "2.0"
}' | jq '.' > response2.json

Process the response

For any given purpose, we may only be interested in a subset of information, or we may have a specific question we'd like answered. For this example, we'll find any sender addresses this address has received exactly 5 transactions from.

In this tutorial we'll be using the command line utility jq to process the JSON response returned by the API, but you can use any programming language or tools you'd like.

Combine our API call responses

To start answering our question (Which senders have sent this address exactly 5 transactions?), we'll start by combining our two files into one unified set of transactions.

Run the following command to create a new file, combined.json that merges the block data from response1.json and response2.json into one array:

jq -s '[.[].result.transactions[]]' response1.json response2.json > combined.json

The previous command finds all the objects in the transactions array inside the result object in response1.json and response2.json, combining them into one object in combined.json.

Filter down our results

Next, run this command to strip down our data to only the sender (from) and amount (value) of each top-level transaction:

cat combined.json | jq '[.[] | { from: .from, value: .value }]' > transactions-only.json

The previous command finds all objects in each transactions array and outputs only the from and value properties into new objects, combining them into one object in transactions-only.json.

Finally, we'll group the transactions by sender (from) and filter the results down to only senders that have exactly 5 transactions:

cat transactions-only.json | jq '[group_by(.from)[] | select(length == 5)]' > final.json

Output:

[
[
{
"from": "0x76c49d0e2b00ded0611862f0713c624a9bd0a432",
"value": "0x46c902971c4f5a29a8"
},
{
"from": "0x76c49d0e2b00ded0611862f0713c624a9bd0a432",
"value": "0x423867aebdf88315e8"
},
{
"from": "0x76c49d0e2b00ded0611862f0713c624a9bd0a432",
"value": "0x4272dedc13fedbd3aa"
},
{
"from": "0x76c49d0e2b00ded0611862f0713c624a9bd0a432",
"value": "0x421918b8f62c587709"
},
{
"from": "0x76c49d0e2b00ded0611862f0713c624a9bd0a432",
"value": "0x413d9bf150c0265bed"
}
]
]

There's only one address that has sent our recipient address exactly 5 transactions: 0x76c49d0e2b00ded0611862f0713c624a9bd0a432.

You did it! You now know how to get transaction history for a given Ethereum address and analyze the resulting response data. From here, you can process more information from your response or check out other Advanced API methods.

Was this helpful?