Sunsetting Transactions v2 - Enhancing Your API Experience with Transactions v3

Covalent upgrades their historical blockchain transaction APIs to be faster, more liable, and cost efficient.

2023-09-27

TL;DR

Transactions v2 Deprecation: The Transactions v2 endpoint will be deprecated on January 31, 2024. Transition to the more efficient and scalable Transactions v3 suite to experience enhanced features.
Key v3 Advancements: Transactions v3 offers a stable pagination mechanism, bulk time bucket transactions, and cost-efficient pricing. With a fixed page size of 100 items, v3 ensures optimal performance and consistent data retrieval.
Easy Transition with SDK: Utilize the Covalent SDK for a seamless shift to v3. The SDK handles pagination changes, making the upgrade straightforward for TypeScript and Python users.

Covalent is continuously committed to providing our users with the best experience possible, and as we continue to evolve, we're always searching for ways to improve the services we offer. With the blockchain world evolving rapidly, it's crucial that our products and services evolve with it. As such, we have some important news to share.

Deprecation of Transactions v2

Firstly, to our loyal Transactions v2 users, we want to inform you that this endpoint will be deprecated on January 31, 2024. With the increasing volume and complexity of data on the blockchain, the original Transactions v2 endpoint has reached its optimal limit, and it's time for a more scalable, efficient, and versatile solution.

Note: this only applies to transactions_v2, which provides all transactions for an address. The single transaction endpoint transaction_v2 will remain available.

Why the Shift to Transactions v3?

The Transactions v3 suite is our response to the rapid changes in blockchain activity. When the original transactions APIs were launched, they were designed for a single wallet with a handful of transactions. But as blockchain activity surged, these APIs struggled to keep pace. Moreover, as the richness of blockchain data expanded, so did the range of use cases, which went beyond the average user’s wallet.

Redefining Efficiency with Transactions v3

Our Transactions v3 suite is not merely an incremental upgrade; it’s a complete overhaul, reconstructed from the ground up for lightning speed and exceptional efficiency.

Some of its features include:

Stable Pagination Mechanism: With v3, transactions are appended to the end of the list, rather than prepended as they were with v2.
Bulk Time Bucket Transactions: This feature allows developers to download all transactions in 15-minute time bucket intervals, providing a non-paginated response ideal for bulk use.
Cost Efficiency: The pricing is designed to give you the best value, with each transaction endpoint priced at a mere 0.1 credit per transaction item.

Use Cases to Illustrate the Power of Transactions v3

Exporting All Transactions from Large Contracts: With v3, you can easily export all transactions from sizable contracts like the Uniswap V3 WETH/USDC pool. The v3 response provides a meta key with links that allow you to paginate through the entire historical transaction set, giving you comprehensive access to your transaction data.
Tracing Transactions within Specific Time Ranges: Whether you're looking to trace transactions within a specific block range or after a certain point in time, our bulk set of APIs, particularly the Get bulk time bucket transactions for address (v3) API, offers you a practical solution. With this feature, you can batch-download transactions in 15-minute intervals.
Retrieving All Transactions in a Block: The Get all transactions in a block (v3) API ensures you can access all transactions within a specific block, providing a holistic view of all activities within that block.

Pagination Explained

While both v2 and v3 allow users to retrieve transaction data, the core distinction, and arguably the game-changer, lies in their approach to pagination.

In v2, pagination was flexible but could become cumbersome. Users had the liberty to set the page size, even to thousands of items, which might affect performance:

curl -X GET <https://api.covalenthq.com/v1/eth-mainnet/address/{walletAddress}/transactions_v2/>? \\
    -H 'Content-Type: application/json' \\
    -u {YOUR API KEY}: \\
     # The colon prevents curl from asking for a password

With v3, we've simplified this by fixing the page size at 100 items, ensuring optimal performance. Users only need to specify the page number:

curl -X GET <https://api.covalenthq.com/v1/eth-mainnet/address/{walletAddress}/transactions_v3/page/{page}/>? \\
    -H 'Content-Type: application/json' \\
    -u {YOUR API KEY}: \\
     # The colon prevents curl from asking for a password

This approach streamlines pagination, reducing the chances of performance hiccups, and ensures consistent data retrieval across all requests.

Making the Transition

Here’s a table comparing Transactions v2 with Transactions v3, outlining the changes required to switch:

transactions_v2	transactions_v3	Changes Required
Adjustable page-size query parameter.	No page-size parameter; fixed at 100 items per page.	Remove the use of the page-size query parameter.
Pagination object using has_more.	Pagination object with link to next page.	Use the next/prev link URLs to fetch the next or previous page.

We understand that migrating to a new version may seem like a daunting task. But here's the good news: if you're using the Covalent SDK, supported for TypeScript and Python, the transition becomes a breeze. The SDK handles the pagination for you, so you won't have to worry about the changes in pagination logic. Here's an example of how to paginate through all recent transactions on the ethereum blockchain for a demo address:

import { Client } from "@covalenthq/client-sdk";

const ApiServices = async () => {
    const client = new Client("YOUR_API_KEY"); // Replace with your Covalent API key.
    for await (const tx of client.TransactionService.getAllTransactionsForAddress("eth-mainnet", "demo.eth")) {
        console.log("tx", tx);
    }
}

For users not using the SDK, we recommend you familiarize yourself with the new pagination method and make the necessary adjustments in your code to reflect these changes. However, for a seamless, worry-free experience, consider integrating with the Covalent SDK, read more about it here.

In either case, we recommend you start by exploring our in-depth guide and consulting our API Reference for an understanding of the v3 capabilities.

In Conclusion

While change can sometimes be challenging, it often brings about new opportunities and advancements. As Covalent continues to grow, we are committed to providing solutions that not only meet but exceed the demands of today's fast-paced blockchain environment. Start your transition to v3 today and experience the cutting edge transaction API that opens up a world of scalability.

Should you have any queries or need further guidance during this transition, our support team is ever-ready to assist at [email protected].

Q3 2023 Product Update

The Covalent SDK – Your New Dev Language