⚠️Blast API (blastapi.io) ends Oct 31. Migrate to Dwellir and skip Alchemy's expensive compute units.
Switch Today →
Skip to main content

wallet/gettransactionbyid

Instant Transaction Tracking

Dwellir's TRON endpoints retrieve transaction details in under 50ms with comprehensive status information. Track payments, confirmations, and smart contract executions in real-time.

Track your transactions →

Retrieves detailed information about a specific transaction using its transaction ID (hash). Essential for tracking transaction status, confirmations, and execution results.

When to Use This Method​

wallet/gettransactionbyid is essential for:

  • Transaction Confirmation - Check if transaction was successful and confirmed
  • Payment Tracking - Monitor payment status in real-time
  • Error Debugging - Analyze failed transactions and error messages
  • Fee Analysis - Review bandwidth and energy consumption
  • Smart Contract Results - Get contract execution results and logs

Parameters​

  1. value - string (required)

    • Transaction ID (hash) to lookup
    • Example: "94eea63bb6774c8fc4f4c9d1b62c1e8c2f7c8c2e4d3a2b1c0d9e8f7a6b5c4d3e2f1"

  2. visible - boolean (optional, default: false)

    • true - Use Base58 address format in response
    • false - Use hex address format in response
{
  "value": "94eea63bb6774c8fc4f4c9d1b62c1e8c2f7c8c2e4d3a2b1c0d9e8f7a6b5c4d3e2f1",
  "visible": true
}

Returns​

Transaction Object containing:

  • ret - Execution result array with status and fees
  • signature - Array of transaction signatures
  • txID - Transaction identifier
  • raw_data - Original transaction data
  • raw_data_hex - Hex encoded transaction data

Result Status Values​

  • SUCCESS - Transaction executed successfully
  • REVERT - Smart contract execution reverted
  • UNKNOWN - Transaction not found or pending

Implementation Examples​

const TRON_API = 'https://api-tron-mainnet.n.dwellir.com/YOUR_API_KEY';

// Get transaction by ID
async function getTransactionById(txId) {
  const response = await fetch(`${TRON_API}/wallet/gettransactionbyid`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      value: txId,
      visible: true
    })
  });

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

  return await response.json();
}

// Enhanced transaction analyzer
class TronTransactionAnalyzer {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.apiUrl = `https://api-tron-mainnet.n.dwellir.com/${apiKey}`;
  }
  
  async getTransactionDetails(txId) {
    try {
      const transaction = await this.getTransactionById(txId);
      
      if (!transaction.txID) {
        return {
          found: false,
          txId: txId,
          status: 'not_found',
          message: 'Transaction not found'
        };
      }
      
      const result = transaction.ret?.[0] || {};
      const contract = transaction.raw_data?.contract?.[0] || {};
      
      return {
        found: true,
        txId: transaction.txID,
        status: result.contractRet || 'UNKNOWN',
        successful: result.contractRet === 'SUCCESS',
        blockNumber: transaction.blockNumber,
        blockTimeStamp: transaction.blockTimeStamp,
        fee: result.fee || 0,
        energyUsed: result.energy_usage || 0,
        netUsed: result.net_usage || 0,
        contractType: contract.type,
        contractDetails: this.parseContract(contract),
        confirmations: transaction.confirmations || 0,
        rawTransaction: transaction
      };
    } catch (error) {
      console.error('Error getting transaction details:', error);
      throw error;
    }
  }
  
  async getTransactionById(txId) {
    const response = await fetch(`${this.apiUrl}/wallet/gettransactionbyid`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ value: txId, visible: true })
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    return await response.json();
  }
  
  parseContract(contract) {
    if (!contract.parameter?.value) return null;
    
    const value = contract.parameter.value;
    
    switch (contract.type) {
      case 'TransferContract':
        return {
          type: 'TRX Transfer',
          from: value.owner_address,
          to: value.to_address,
          amount: value.amount,
          amountTRX: (value.amount / 1000000).toFixed(6)
        };
        
      case 'TriggerSmartContract':
        return {
          type: 'Smart Contract Call',
          caller: value.owner_address,
          contract: value.contract_address,
          data: value.data,
          callValue: value.call_value || 0
        };
        
      case 'TransferAssetContract':
        return {
          type: 'TRC10 Token Transfer',
          from: value.owner_address,
          to: value.to_address,
          asset: value.asset_name,
          amount: value.amount
        };
        
      case 'FreezeBalanceContract':
        return {
          type: 'Freeze TRX',
          owner: value.owner_address,
          amount: value.frozen_balance,
          duration: value.frozen_duration,
          resource: value.resource
        };
        
      case 'UnfreezeBalanceContract':
        return {
          type: 'Unfreeze TRX',
          owner: value.owner_address,
          resource: value.resource
        };
        
      default:
        return {
          type: contract.type,
          details: value
        };
    }
  }
  
  async trackTransactionStatus(txId, timeoutMs = 60000) {
    const startTime = Date.now();
    const checkInterval = 3000; // Check every 3 seconds
    
    while (Date.now() - startTime < timeoutMs) {
      try {
        const details = await this.getTransactionDetails(txId);
        
        if (details.found) {
          if (details.blockNumber) {
            return {
              ...details,
              trackingStatus: 'confirmed',
              trackingTime: Date.now() - startTime
            };
          } else {
            // Found but not yet in block
            console.log('Transaction found in mempool, waiting for confirmation...');
          }
        } else {
          console.log('Transaction not found, checking again...');
        }
        
        await new Promise(resolve => setTimeout(resolve, checkInterval));
        
      } catch (error) {
        console.log('Error tracking transaction:', error.message);
      }
    }
    
    return {
      found: false,
      txId: txId,
      trackingStatus: 'timeout',
      trackingTime: timeoutMs,
      message: 'Transaction tracking timeout'
    };
  }
}

// Transaction monitor for multiple transactions
class TronTransactionMonitor {
  constructor(apiKey) {
    this.analyzer = new TronTransactionAnalyzer(apiKey);
    this.monitoredTxs = new Map();
    this.callbacks = new Map();
  }
  
  async monitor(txId, callback = null, timeoutMs = 300000) {
    if (this.monitoredTxs.has(txId)) {
      console.log(`Already monitoring transaction ${txId}`);
      return;
    }
    
    this.monitoredTxs.set(txId, {
      startTime: Date.now(),
      timeout: timeoutMs,
      status: 'monitoring'
    });
    
    if (callback) {
      this.callbacks.set(txId, callback);
    }
    
    // Start monitoring in background
    this.startMonitoring(txId);
  }
  
  async startMonitoring(txId) {
    const monitorInfo = this.monitoredTxs.get(txId);
    const callback = this.callbacks.get(txId);
    
    while (this.monitoredTxs.has(txId)) {
      try {
        const details = await this.analyzer.getTransactionDetails(txId);
        
        if (details.found && details.blockNumber) {
          // Transaction confirmed
          monitorInfo.status = 'confirmed';
          monitorInfo.details = details;
          
          if (callback) callback(details);
          
          console.log(`✅ Transaction ${txId} confirmed in block ${details.blockNumber}`);
          this.stopMonitoring(txId);
          break;
        }
        
        // Check timeout
        if (Date.now() - monitorInfo.startTime > monitorInfo.timeout) {
          monitorInfo.status = 'timeout';
          
          if (callback) {
            callback({
              found: false,
              txId: txId,
              status: 'timeout',
              message: 'Monitoring timeout'
            });
          }
          
          console.log(`⏰ Transaction ${txId} monitoring timeout`);
          this.stopMonitoring(txId);
          break;
        }
        
        await new Promise(resolve => setTimeout(resolve, 3000));
        
      } catch (error) {
        console.error(`Error monitoring transaction ${txId}:`, error);
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }
  }
  
  stopMonitoring(txId) {
    this.monitoredTxs.delete(txId);
    this.callbacks.delete(txId);
  }
  
  getMonitoredTransactions() {
    return Array.from(this.monitoredTxs.entries()).map(([txId, info]) => ({
      txId,
      ...info
    }));
  }
}

// Payment verification system
class TronPaymentVerifier {
  constructor(apiKey) {
    this.analyzer = new TronTransactionAnalyzer(apiKey);
  }
  
  async verifyPayment(txId, expectedAmount, expectedRecipient, tokenContract = null) {
    try {
      const details = await this.analyzer.getTransactionDetails(txId);
      
      if (!details.found) {
        return {
          verified: false,
          reason: 'Transaction not found',
          details: null
        };
      }
      
      if (!details.successful) {
        return {
          verified: false,
          reason: `Transaction failed: ${details.status}`,
          details: details
        };
      }
      
      const contract = details.contractDetails;
      
      if (tokenContract) {
        // Verify TRC20 token payment
        if (contract.type !== 'Smart Contract Call') {
          return {
            verified: false,
            reason: 'Not a smart contract transaction',
            details: details
          };
        }
        
        // Would need to decode contract call data to verify TRC20 transfer
        // This is simplified for example
        return {
          verified: true,
          reason: 'TRC20 payment verification requires log analysis',
          details: details,
          note: 'Full TRC20 verification needs contract log parsing'
        };
        
      } else {
        // Verify TRX payment
        if (contract.type !== 'TRX Transfer') {
          return {
            verified: false,
            reason: 'Not a TRX transfer',
            details: details
          };
        }
        
        const amountMatch = contract.amount === expectedAmount;
        const recipientMatch = contract.to === expectedRecipient;
        
        return {
          verified: amountMatch && recipientMatch,
          reason: !amountMatch ? 'Amount mismatch' : 
                  !recipientMatch ? 'Recipient mismatch' : 
                  'Payment verified successfully',
          details: details,
          verification: {
            amountExpected: expectedAmount,
            amountReceived: contract.amount,
            recipientExpected: expectedRecipient,
            recipientActual: contract.to
          }
        };
      }
      
    } catch (error) {
      return {
        verified: false,
        reason: `Verification error: ${error.message}`,
        details: null
      };
    }
  }
}

// Usage examples
(async () => {
  try {
    const analyzer = new TronTransactionAnalyzer('YOUR_API_KEY');
    const txId = '94eea63bb6774c8fc4f4c9d1b62c1e8c2f7c8c2e4d3a2b1c0d9e8f7a6b5c4d3e2f1';
    
    // Get transaction details
    const details = await analyzer.getTransactionDetails(txId);
    console.log('Transaction details:', details);
    
    // Track transaction status
    const monitor = new TronTransactionMonitor('YOUR_API_KEY');
    
    monitor.monitor(txId, (result) => {
      if (result.found && result.successful) {
        console.log(`Payment confirmed: ${result.contractDetails.amountTRX} TRX`);
      } else {
        console.log(`Transaction issue: ${result.message || result.status}`);
      }
    });
    
    // Verify a payment
    const verifier = new TronPaymentVerifier('YOUR_API_KEY');
    const verification = await verifier.verifyPayment(
      txId,
      1000000, // 1 TRX in SUN
      'TRX6Q82wMqWNbCCmJPLz9mR8AZwqvUU2pN'
    );
    console.log('Payment verification:', verification);
    
  } catch (error) {
    console.error('Error:', error);
  }
})();

Response Examples​

Successful TRX Transfer​

{
  "ret": [
    {
      "contractRet": "SUCCESS",
      "fee": 1100
    }
  ],
  "signature": [
    "c8f8f8e8d8c8b8a898887878686858484838281807060504030201..."
  ],
  "txID": "94eea63bb6774c8fc4f4c9d1b62c1e8c2f7c8c2e4d3a2b1c0d9e8f7a6b5c4d3e2f1",
  "raw_data": {
    "contract": [
      {
        "parameter": {
          "value": {
            "amount": 1000000,
            "owner_address": "TJmmqjb1DK9TTZbQXzRQ2AuA94z4gKAPFh",
            "to_address": "TRX6Q82wMqWNbCCmJPLz9mR8AZwqvUU2pN"
          },
          "type_url": "type.googleapis.com/protocol.TransferContract"
        },
        "type": "TransferContract"
      }
    ],
    "ref_block_bytes": "4a7b",
    "ref_block_hash": "e15e44aa73bd9e15",
    "expiration": 1734567890000,
    "timestamp": 1734567830000
  },
  "blockNumber": 52895819,
  "blockTimeStamp": 1734567893000
}

Failed Smart Contract Call​

{
  "ret": [
    {
      "contractRet": "REVERT",
      "fee": 5000
    }
  ],
  "signature": ["..."],
  "txID": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890",
  "raw_data": {
    "contract": [
      {
        "parameter": {
          "value": {
            "data": "a9059cbb0000000000000000000000004142b5e01c8c59a25d78acdbec2bfc7e89e5e86300000000000000000000000000000000000000000000000000000000000f4240",
            "owner_address": "TJmmqjb1DK9TTZbQXzRQ2AuA94z4gKAPFh",
            "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
          },
          "type_url": "type.googleapis.com/protocol.TriggerSmartContract"
        },
        "type": "TriggerSmartContract"
      }
    ],
    "ref_block_bytes": "4a7b",
    "ref_block_hash": "e15e44aa73bd9e15",
    "expiration": 1734567890000,
    "timestamp": 1734567830000
  },
  "blockNumber": 52895820,
  "blockTimeStamp": 1734567896000
}

Transaction Not Found​

{}

Common Use Cases​

1. E-commerce Payment Tracking​

class EcommercePaymentTracker {
  constructor(apiKey) {
    this.analyzer = new TronTransactionAnalyzer(apiKey);
    this.paymentDatabase = new Map(); // Replace with real database
  }
  
  async trackOrderPayment(orderId, txId, expectedAmount, expectedRecipient) {
    try {
      // Store payment attempt
      this.paymentDatabase.set(orderId, {
        txId,
        expectedAmount,
        expectedRecipient,
        status: 'tracking',
        createdAt: Date.now()
      });
      
      // Track transaction
      const result = await this.analyzer.trackTransactionStatus(txId, 300000); // 5 min timeout
      
      if (result.trackingStatus === 'confirmed' && result.successful) {
        // Verify payment details
        const verification = await this.verifyOrderPayment(orderId, result);
        
        if (verification.verified) {
          await this.fulfillOrder(orderId);
          return { success: true, message: 'Payment confirmed and order fulfilled' };
        } else {
          await this.flagPaymentIssue(orderId, verification.reason);
          return { success: false, message: verification.reason };
        }
      } else {
        await this.handlePaymentFailure(orderId, result);
        return { success: false, message: 'Payment failed or timeout' };
      }
      
    } catch (error) {
      console.error(`Payment tracking error for order ${orderId}:`, error);
      throw error;
    }
  }
  
  async verifyOrderPayment(orderId, transactionResult) {
    const payment = this.paymentDatabase.get(orderId);
    const contract = transactionResult.contractDetails;
    
    if (contract.type !== 'TRX Transfer') {
      return { verified: false, reason: 'Not a TRX transfer' };
    }
    
    const amountMatch = contract.amount === payment.expectedAmount;
    const recipientMatch = contract.to === payment.expectedRecipient;
    
    return {
      verified: amountMatch && recipientMatch,
      reason: !amountMatch ? 'Payment amount mismatch' :
              !recipientMatch ? 'Payment recipient mismatch' :
              'Payment verified successfully'
    };
  }
  
  async fulfillOrder(orderId) {
    console.log(`✅ Fulfilling order ${orderId}`);
    // Implement order fulfillment logic
  }
  
  async flagPaymentIssue(orderId, reason) {
    console.log(`⚠️ Payment issue for order ${orderId}: ${reason}`);
    // Implement payment issue handling
  }
  
  async handlePaymentFailure(orderId, result) {
    console.log(`❌ Payment failed for order ${orderId}: ${result.message}`);
    // Implement payment failure handling
  }
}

2. Smart Contract Execution Monitor​

class SmartContractMonitor {
  constructor(apiKey) {
    this.analyzer = new TronTransactionAnalyzer(apiKey);
    this.contractAddresses = new Set();
  }
  
  addContract(address) {
    this.contractAddresses.add(address);
  }
  
  async monitorContractTransaction(txId) {
    try {
      const details = await this.analyzer.getTransactionDetails(txId);
      
      if (!details.found) {
        return { status: 'not_found', message: 'Transaction not found' };
      }
      
      if (details.contractDetails?.type !== 'Smart Contract Call') {
        return { status: 'not_contract', message: 'Not a smart contract transaction' };
      }
      
      const contractAddress = details.contractDetails.contract;
      
      if (!this.contractAddresses.has(contractAddress)) {
        return { status: 'not_monitored', message: 'Contract not in monitoring list' };
      }
      
      return {
        status: 'monitored',
        successful: details.successful,
        contractAddress,
        caller: details.contractDetails.caller,
        energyUsed: details.energyUsed,
        fee: details.fee,
        blockNumber: details.blockNumber,
        executionResult: details.status
      };
      
    } catch (error) {
      return { status: 'error', message: error.message };
    }
  }
}

Need help? Contact our support team or check the TRON documentation.