Introducing Transactions V3 APIs
What are Transactions V3?
The Transactions V3 suite of APIs are the newest edition of the ever beloved Transactions APIs re-built from the ground up for speed and efficiency. When the original transactions APIs were conceived a few years, the data on the blockchain was very small and even the biggest wallets only had a few thousand transactions. But with time as activity on the blockchain had picked up, data has significantly grown and the old APIs could no longer keep up.
Secondly, the original transactions APIs were built for a narrow use-case: show the last 10 transactions of a wallet to a user. As data on the blockchains has gotten richer, newer use-cases started to emerge -- specially around the offline crunching of transaction data to provide recommendations, AI/ML use-cases and of-course advanced tax calculations that go beyond simple token transfers.
It was time for a rebuild.
Summary of Transactions V3 APIs
There are a new set of APIs that can be mixed and matched for various use-cases:
Get recent transactions for address (v3)
Commonly used to fetch and render the most recent transactions involving an address. Frequently seen in wallet applications.Get earliest transactions for address (v3)
Commonly used to fetch and render the earliest transactions involving an address. Frequently seen in wallet applications.Get paginated transactions for address (v3)
Commonly used to fetch the transactions involving an address including the decoded log events in a paginated fashion.Get bulk time bucket transactions for address (v3)
Commonly used to fetch all transactions including their decoded log events in a 15-minute time bucket interval.Get all transactions in a block (v3)
Commonly used to fetch all transactions including their decoded log events in a block and further flag interesting wallets or transactions.Case study 1: Exporting all transactions from a big contract
Suppose we want to export all transactions from a big contract like Uniswap V3 WETH/USDC pool (Etherscan shows millions of transactions for this contract at the time of writing.)
curl "https://api.covalenthq.com/v1/eth-mainnet/address/0x88e6...5640/transactions_v3/"Besides the actual transactions, the response returns an important meta key: links.
{
"links": {
"prev": "https://api.covalenthq.com/v1/eth-mainnet/address/0x88e6...5640/transactions_v3/page/41711/",
"next": null
}
}Within the links object, there are two more keys: prev and next. These keys allow you to paginate through the entire set of historical transactions. Pages are zero-indexed. When you omit a page number, the default behavior is to return the last page of results, which contains up to 100 most recent transactions.
For example:
if your address has 335 transactions, then we would have 4 pages with the last page only returning 35 transactions.
if you called the API without a page number, it would return the last page with 35 transactions.
Transactions V3 implements a stable pagination mechanism - which means that transactions are appended to the end of the list rather than prepended. When prepending new transactions, the entire transaction list shifts by an entry, thereby invalidating your pagination logic. This is no longer an issue with Transactions V3.
You'll be able to retrieve the entire list of transactions by crawling through the pages with . Moreover, as new transactions are appended to the end of the list, you must remember the most recent page as a cursor to implement incremental crawls. In the afore-mentioned example with 335 transactions, you can in fact, make 4 concurrent calls to the API (subject to your rate limits) to download all of the transactions in parallel.
To retrieve transactions sorted by the earliest first, use the endpoint.
Case study 2: Find all transactions within a block range or after a certain point in time
GoldRush provides the bulk set of APIs to batch download transactions with the API. The API breaks down time into 15-minute time buckets and the developer can traverse through the non-empty time buckets to download all of the transactions. The response from a time bucket is not paginated and is meant for bulk use.
This API takes three path parameters: chainName, address and timeBucket:
Get bulk time bucket transactions for address (v3)
Commonly used to fetch all transactions including their decoded log events in a 15-minute time bucket interval.We would start by calling the API with time bucket 0.
curl "https://api.covalenthq.com/v1/eth-mainnet/bulk/transactions/0x88e6...5640/0/"For the same Uniswap V3 WETH/USDC pool, the response is:
{
"address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"updated_at": "2023-01-31T07:25:44.171098150Z",
"next_update_at": "2023-01-31T07:30:44.171102620Z",
"quote_currency": "USD",
"chain_id": 1,
"chain_name": "eth-mainnet",
"complete": true,
"links": {
"prev": null,
"next": "https://api.covalenthq.com/v1/1/bulk/transactions/0x88e6...5640/1800278/"
},
"items": []
}The most important keys in the response are:
links.prev- the link to the previous non-empty time bucketlinks.next- the link to the next non-empty time bucket so that you don't have to crawl every single time bucket exhaustivelycomplete- boolean if the time bucket is in the past and you can be sure that the bucket has been fully filled. If complete is false, it means that the bucket is still being filled and you can fetch this bucket again to get the latest transactions (if any.)
Notes
Time buckets are in epoch time. Here's a handy guide to calculate time buckets.
In this example, time bucket 1839333 corresponds to 1655399700 in unix time which is 2022-06-16 05:15:00 GMT.
Omitting the
timeBucketpath parameter returns the earliest transactions from an address as documented here:
Case study 3: Find all transactions in a block
Refer to the Historical Transactions in a Block guide which makes use of the API.
Pricing
All transaction endpoints are priced at 0.1 credits per transaction item in the response. If there are 100 transactions, it would be 10 credits. If you omit logs with no-logs, the price per transaction item is 0.05 credits per transaction item.
