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:

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.)

Bash

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.

json

{
    "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 GET Get paginated transactions for address (v3). 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 GET Get earliest transactions for address (v3) endpoint.

Case study 2: Find all transactions within a block range or after a certain point in time

Covalent provides the bulk set of APIs to batch download transactions with the GET Get bulk time bucket transactions for address (v3) 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:

We would start by calling the API with time bucket 0.

Bash

curl "https://api.covalenthq.com/v1/eth-mainnet/bulk/transactions/0x88e6...5640/0/"

For the same Uniswap V3 WETH/USDC pool, the response is:

json

{
    "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 bucket

• links.next - the link to the next non-empty time bucket so that you don't have to crawl every single time bucket exhaustively

• complete - 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 timeBucket path parameter returns the earliest transactions from an address as documented here: GET Get earliest transactions for address (v3)

Case study 3: Find all transactions in a block

Refer to the Historical Transactions in a Block guide which makes use of the GET Get all transactions in a block (v3) 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.