Polkadot API: Get Transaction Details By Hash

Nov 3, 2025 by Admin 46 views

Polkadot API: How to Get Transaction Details by Hash

Hey guys! Ever found yourself needing to dig into the nitty-gritty details of a transaction on the Polkadot network? Maybe you've got a transaction hash and you're itching to find out more – like which block it landed in, the block's hash, and all the juicy transaction data. Well, you're in the right place! This guide will walk you through how to use the Polkadot API to extract all that valuable information. Let's dive in!

Understanding Transaction Hashes and Polkadot

Before we get our hands dirty with the API, let's quickly recap what a transaction hash is and why it's so important in the Polkadot ecosystem. Think of a transaction hash as a unique fingerprint for every transaction that occurs on the Polkadot network. It's a cryptographic identifier that ensures the integrity and traceability of each transaction. This hash is generated by hashing the transaction data itself, meaning any tiny change to the transaction will result in a completely different hash. This is crucial for security and verification. Now, why Polkadot? Polkadot is a sharded, multi-chain network, meaning it can process multiple transactions in parallel across different chains (called parachains). This makes it incredibly scalable and efficient. Understanding how transactions are handled within Polkadot's architecture is key to appreciating the power of its API.

Why is this important? Knowing how to retrieve transaction details using the hash allows you to:

Verify Transaction Status: Confirm whether a transaction has been successfully included in a block.
Audit Transactions: Track the flow of funds or data across the network.
Debug Issues: Investigate failed transactions and identify potential problems.
Build Applications: Integrate transaction data into your own applications, such as wallets or block explorers.

In essence, mastering this skill unlocks a deeper understanding of the Polkadot network and empowers you to build more robust and informed applications. So, let's get started and unravel the secrets hidden within those transaction hashes! By the end of this guide, you'll be equipped with the knowledge and tools to confidently query transaction details and leverage them for your own projects.

Prerequisites

Before we start querying the Polkadot API, make sure you have a few things set up. This will ensure a smooth and productive experience. Think of it like gathering your tools before starting a DIY project – having everything in place makes the job much easier!

Polkadot API Client: You'll need a Polkadot API client to interact with the network. A popular choice is the @polkadot/api JavaScript library. You can install it using npm or yarn:
```
npm install @polkadot/api
# or
yarn add @polkadot/api
```
This library provides a convenient way to connect to a Polkadot node and make API calls. It handles the underlying communication protocols, so you don't have to worry about the technical details.
Polkadot Node Endpoint: You'll need to connect to a Polkadot node. You can either run your own node (which requires some technical expertise) or use a public node provider like Subscan or Chainstack. These providers offer access to Polkadot nodes without the hassle of managing your own infrastructure. For example, you might use a Subscan endpoint like wss://polkadot.api.subscan.io/. Make sure to choose a reliable and stable endpoint for your development and production environments.
Basic JavaScript Knowledge: This guide assumes you have a basic understanding of JavaScript. You should be comfortable with concepts like variables, functions, and asynchronous programming (Promises and async/await). If you're new to JavaScript, there are tons of great resources online to get you up to speed.

With these prerequisites in place, you're ready to start querying the Polkadot API and extracting transaction details. Don't worry if you're not an expert in all of these areas – you can learn as you go! The key is to have a basic understanding and be willing to experiment.

Step-by-Step Guide to Querying Transaction Details

Alright, let's get to the fun part! Here's a step-by-step guide on how to query transaction details from the Polkadot API using a transaction hash.

Step 1: Import the necessary modules

First, you need to import the ApiPromise and WsProvider classes from the @polkadot/api library. These classes will allow you to connect to a Polkadot node and make API calls.

const { ApiPromise, WsProvider } = require('@polkadot/api');

// or, if you're using ES modules:
// import { ApiPromise, WsProvider } from '@polkadot/api';

This is like importing the necessary tools into your workshop before you start building something. Make sure you have the @polkadot/api library installed as mentioned in the prerequisites.

Step 2: Connect to a Polkadot node

Next, you need to create a WsProvider instance and pass it the endpoint of the Polkadot node you want to connect to. Then, create an ApiPromise instance, passing the WsProvider instance as an argument. This will establish a connection to the node and allow you to start making API calls.

const provider = new WsProvider('wss://rpc.polkadot.io'); // Replace with your node endpoint

const api = await ApiPromise.create({ provider });

Remember to replace 'wss://rpc.polkadot.io' with your actual Polkadot node endpoint. You can use a public endpoint or run your own node. The await keyword is used because ApiPromise.create() returns a Promise, which represents an asynchronous operation. We need to wait for the connection to be established before proceeding.

Step 3: Define the transaction hash

Now, you need to define the transaction hash you want to query. This is the unique identifier of the transaction you're interested in.

const transactionHash = '0x1234567890abcdef...'; // Replace with your transaction hash

Make sure to replace '0x1234567890abcdef...' with the actual transaction hash you want to query. Transaction hashes are typically represented as hexadecimal strings.

Step 4: Retrieve the block hash

Unfortunately, the Polkadot API doesn't directly provide transaction details from the transaction hash. Instead, you need to first retrieve the block hash that contains the transaction. You can do this using the api.rpc.chain.getBlock() method. However, this method requires the block hash, not the transaction hash. Therefore, we need to find another way. One potential solution is to use a block explorer API (like Subscan's API) to find the block hash associated with the transaction hash. This typically involves making an HTTP request to the block explorer API with the transaction hash as a parameter.

Example using Subscan API (you'll need an API key):

const apiKey = 'YOUR_SUBSCAN_API_KEY'; // Replace with your Subscan API key
const subscanEndpoint = `https://polkadot.api.subscan.io/api/scan/transaction?hash=${transactionHash}`;

const response = await fetch(subscanEndpoint, {
  headers: {
    'X-API-Key': apiKey
  }
});

const data = await response.json();

const blockNumber = data.data.block_num;

//Get the block hash from the block number
const blockHash = await api.rpc.chain.getBlockHash(blockNumber);

Remember to replace 'YOUR_SUBSCAN_API_KEY' with your actual Subscan API key. You'll need to sign up for a Subscan account and obtain an API key to use their API. This code snippet makes an HTTP request to the Subscan API, retrieves the block number associated with the transaction hash, and then uses the api.rpc.chain.getBlockHash() method to retrieve the block hash.

Step 5: Retrieve the block details

Once you have the block hash, you can retrieve the block details using the api.rpc.chain.getBlock() method. This method returns a SignedBlock object, which contains information about the block, including its header and extrinsics (transactions).

const signedBlock = await api.rpc.chain.getBlock(blockHash);
const block = signedBlock.block;

The signedBlock object contains both the block and its justification (proof of validity). We're primarily interested in the block property, which contains the actual block data.

Step 6: Find the transaction within the block

Now that you have the block details, you need to find the specific transaction you're looking for within the block's extrinsics. You can iterate over the block's extrinsics and compare their hashes to the transaction hash you defined earlier.

block.extrinsics.forEach((extrinsic, index) => {
  if (extrinsic.hash.toString() === transactionHash) {
    console.log(`Transaction found at index ${index}`);
    console.log(`Transaction details: ${extrinsic.toHuman()}`);
  }
});

This code snippet iterates over the block's extrinsics and compares the hash of each extrinsic to the transaction hash you're looking for. If a match is found, it prints the index of the transaction within the block and the transaction details in a human-readable format using the toHuman() method.

Step 7: Extract relevant transaction data

Finally, you can extract the relevant transaction data from the extrinsic object. This object contains information about the transaction, such as its method, arguments, and signer.

block.extrinsics.forEach((extrinsic, index) => {
    if (extrinsic.hash.toString() === transactionHash) {
      console.log(`Transaction found at index ${index}`);
      console.log(`Transaction details: ${extrinsic.toHuman()}`);

      const method = extrinsic.method.method;
      const section = extrinsic.method.section;
      const args = extrinsic.method.args;
      const signer = extrinsic.signer.toString();

      console.log(`Method: ${method}`);
      console.log(`Section: ${section}`);
      console.log(`Arguments: ${JSON.stringify(args)}`);
      console.log(`Signer: ${signer}`);
    }
  });

This code snippet extracts the method, section, arguments, and signer from the extrinsic object and prints them to the console. You can customize this code to extract any other relevant data you're interested in.

Complete Code Example

Here's the complete code example that combines all the steps above:

const { ApiPromise, WsProvider } = require('@polkadot/api');
const fetch = require('node-fetch'); // Import node-fetch for making HTTP requests

async function getTransactionDetails(transactionHash) {
  const provider = new WsProvider('wss://rpc.polkadot.io'); // Replace with your node endpoint

  const api = await ApiPromise.create({ provider });

  const apiKey = 'YOUR_SUBSCAN_API_KEY'; // Replace with your Subscan API key
  const subscanEndpoint = `https://polkadot.api.subscan.io/api/scan/transaction?hash=${transactionHash}`;

  const response = await fetch(subscanEndpoint, {
    headers: {
      'X-API-Key': apiKey
    }
  });

  const data = await response.json();

  const blockNumber = data.data.block_num;

  //Get the block hash from the block number
  const blockHash = await api.rpc.chain.getBlockHash(blockNumber);
  const signedBlock = await api.rpc.chain.getBlock(blockHash);
  const block = signedBlock.block;

  block.extrinsics.forEach((extrinsic, index) => {
    if (extrinsic.hash.toString() === transactionHash) {
      console.log(`Transaction found at index ${index}`);
      console.log(`Transaction details: ${extrinsic.toHuman()}`);

      const method = extrinsic.method.method;
      const section = extrinsic.method.section;
      const args = extrinsic.method.args;
      const signer = extrinsic.signer.toString();

      console.log(`Method: ${method}`);
      console.log(`Section: ${section}`);
      console.log(`Arguments: ${JSON.stringify(args)}`);
      console.log(`Signer: ${signer}`);
    }
  });
}

const transactionHash = '0x...'; // Replace with your transaction hash

getTransactionDetails(transactionHash).catch(console.error);

Remember to replace the placeholder values for the node endpoint, Subscan API key, and transaction hash with your actual values. This code example uses the node-fetch library to make HTTP requests to the Subscan API. You'll need to install this library using npm install node-fetch or yarn add node-fetch.

Error Handling and Best Practices

When working with APIs, it's crucial to implement proper error handling to ensure your application is robust and reliable. Here are some best practices to keep in mind:

Handle API Errors: The Subscan API might return errors if the transaction hash is invalid or if there are issues with the API itself. Make sure to check the response status code and handle any errors accordingly. For example:
```
const response = await fetch(subscanEndpoint, {
  headers: {
    'X-API-Key': apiKey
  }
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const data = await response.json();

if (data.code !== 0) {
  throw new Error(`Subscan API error: ${data.message}`);
}
```
This code snippet checks the response status code and the code property in the response data to handle API errors. If an error is detected, it throws an error with a descriptive message.

Handle Missing Transactions: The transaction might not be found in the block. Add a check to handle this scenario gracefully.

let transactionFound = false;
block.extrinsics.forEach((extrinsic, index) => {
  if (extrinsic.hash.toString() === transactionHash) {
    transactionFound = true;
    // ... (rest of the code)
  }
});

if (!transactionFound) {
  console.log(`Transaction with hash ${transactionHash} not found in block`);
}

This code snippet adds a transactionFound variable to track whether the transaction was found in the block. If the transaction is not found, it prints a message to the console.

Rate Limiting: Be mindful of rate limits imposed by the Subscan API. If you make too many requests in a short period, you might be temporarily blocked. Implement a mechanism to limit the number of requests you make to the API.
Error Logging: Log any errors that occur so you can investigate and fix them. Use a logging library like Winston or Bunyan to write error messages to a file or a logging service.
Use Environment Variables: Store sensitive information like API keys in environment variables instead of hardcoding them in your code. This improves security and makes it easier to manage your application in different environments.

By following these error handling and best practices, you can ensure your application is robust, reliable, and secure.

Conclusion

So there you have it! You've successfully learned how to query transaction details from the Polkadot API using a transaction hash. It might seem a bit roundabout, needing to go through a block explorer API to get the block hash first, but that's the current landscape. Remember to handle errors gracefully and be mindful of API rate limits. With this knowledge, you're well-equipped to build powerful applications that leverage the rich data available on the Polkadot network. Now go forth and explore! You can now confidently retrieve transaction details, including the block number, block hash, and other relevant information. Happy coding!