Understanding Transaction Status

Transaction Status Flow

TRANSACTION.NEW
    ↓
TRANSACTION.PENDING
    ↓
TRANSACTION.PROCESSING
    ↓
TRANSACTION.QUEUE (if needed)
    ↓
TRANSACTION.PRE_BROADCAST
    ↓
TRANSACTION.BROADCASTED
    ↓
TRANSACTION.AWAITING_CONFIRMATION
    ↓
TRANSACTION.CONFIRMED (Success)

OR

TRANSACTION.STUCK → TRANSACTION.DROPPED
TRANSACTION.FAILED
TRANSACTION.CANCELLED

Transaction Statuses

1. TRANSACTION.NEW

Description: Transaction has been newly created and accepted by the BitPowr system.

What it means:

Transaction request has been validated
Transaction record created in BitPowr database
Initial processing has begun

Next steps: Will automatically move to PENDING status

2. TRANSACTION.PENDING

Description: Transaction is prepared and ready for processing.

What it means:

Transaction parameters have been validated
Wallet balances have been checked
Transaction is queued for processing

Next steps: Will move to PROCESSING when picked up by transaction relayer

3. TRANSACTION.PROCESSING

Description: Transaction processing has started on the transaction relayer.

What it means:

Transaction relayer is actively working on the transaction
Blockchain-specific preparations are being made
UTXO selection, gas estimation, or fee calculation in progress

Next steps: Will move to QUEUE (if needed) or PRE_BROADCAST

4. TRANSACTION.QUEUE

Description: Transaction is queued due to pending transactions that need to be processed first.

What it means:

There are earlier transactions from the same wallet that must complete first
Prevents nonce conflicts and ensures proper transaction ordering
Common for wallets with high transaction volumes

Next steps: Will move to PRE_BROADCAST when previous transactions clear

5. TRANSACTION.PRE_BROADCAST

Description: Transaction is about to be broadcast to the blockchain network.

What it means:

Final transaction preparation is complete
Transaction is signed and ready for network submission
About to be sent to blockchain nodes

Next steps: Will move to BROADCASTED immediately

6. TRANSACTION.BROADCASTED

Description: Transaction has been successfully broadcast to the blockchain network.

What it means:

Transaction has been sent to blockchain nodes
Network has received the transaction
Transaction is now in the blockchain's mempool

Next steps: Will move to AWAITING_CONFIRMATION

7. TRANSACTION.AWAITING_CONFIRMATION

Description: Transaction is broadcast and waiting for blockchain confirmation.

What it means:

Transaction is in the blockchain's mempool
Miners/validators are processing the transaction
Waiting for inclusion in a confirmed block

Next steps: Will move to CONFIRMED when included in a block

8. TRANSACTION.STUCK

Description: Transaction has spent too much time in processing without progress.

What it means:

Transaction may have network issues
Fees might be too low for current network conditions
Blockchain congestion may be affecting processing

Next steps: May be retried or will move to DROPPED

9. TRANSACTION.DROPPED

Description: Transaction was dropped after spending too much time processing.

What it means:

Transaction exceeded maximum processing time limits
Network conditions prevented successful completion
Transaction will not be completed

Next steps: Transaction is final - may need to create a new transaction

10. TRANSACTION.FAILED / TRANSACTION.FAIL

Description: Transaction failed during processing or on the blockchain.

What it means:

An error occurred that prevented transaction completion
Could be due to insufficient funds, network issues, or blockchain rejection
Check sub-status for specific failure reason

Next steps: Transaction is final - review error and create new transaction if needed

11. TRANSACTION.CANCELLED

Description: Transaction was cancelled before completion.

What it means:

Transaction was manually cancelled by user or system
Processing was stopped before blockchain broadcast
No blockchain fees were consumed

Next steps: Transaction is final - create new transaction if needed

Transaction Sub-Statuses

Sub-statuses provide additional detail about why a transaction failed or encountered issues.

1. TRANSACTION.ERROR

Description: A general error occurred during transaction processing.

Common causes:

System errors during processing
Unexpected technical issues
Network connectivity problems

Resolution: Review transaction details and retry if appropriate

2. TRANSACTION.FAILED_ONCHAIN

Description: Transaction failed after being broadcast to the blockchain.

Common causes:

Smart contract execution failed
Gas limit too low for EVM transactions
Invalid transaction parameters

Resolution: Check blockchain explorer for failure details, adjust parameters and retry

3. TRANSACTION.INSUFFICIENT_AMOUNT / TRANSACTION.INSUFFICIENT_FUND

Description: Insufficient balance to complete the transaction.

Common causes:

Wallet balance is lower than transaction amount
Tokens have been spent in other transactions
Balance calculation error

Resolution: Check wallet balance and reduce transaction amount or add funds

4. TRANSACTION.INSUFFICIENT_FEE

Description: Insufficient balance to pay transaction fees.

Common causes:

Not enough ETH for gas fees on Ethereum
Insufficient SOL for fees on Solana
Not enough BTC for mining fees

Resolution: Add native tokens for fees or reduce transaction amount

5. TRANSACTION.CAN_NOT_BROADCAST

Description: Transaction could not be broadcast to the blockchain network.

Common causes:

Network connectivity issues
Invalid transaction format
Blockchain node rejection

Resolution: Check network status and retry, or contact support

6. TRANSACTION.CANCELLED

Description: Transaction was cancelled (same as primary status).

Common causes:

Manual cancellation by user
System cancellation due to timeout
Automated cancellation due to conditions

Resolution: Create new transaction if still needed

7. TRANSACTION.FAIL / TRANSACTION.FAIL

Description: General transaction failure (same as primary status).

Common causes:

Various failure conditions
Check other sub-statuses for specifics
System or network errors

Resolution: Review failure details and retry with corrected parameters

Approval Related Status

TRANSACTION.PENDING_APPROVAL

Description: Transaction requires manual approval before processing can continue.
What it means:

Transaction requires approval from authorized personnel
Common for high-value transactions or sensitive operation
Compliance or security policies require manual reviewTransaction is on hold pending approval decision

Next steps: Will move to APPROVED or REJECTED based on approval decision

TRANSACTION.APPROVED

Description: Transaction has been approved and can proceed with processing.

What it means:

Manual approval has been granted by authorized personnel
Transaction has passed compliance and security checks
Processing will resume automatically
Transaction will continue to PENDING status

Next steps: Will move to PENDING for continued processing

TRANSACTION.REJECTED

Description: Transaction has been rejected during the approval process.

What it means:

Manual approval was denied by authorized personnel
Transaction failed compliance or security review
Transaction will not be processed further
Rejection reason should be available in transaction details

Next steps: Transaction is final - review rejection reason and create new transaction if appropriate

Status Monitoring Best Practices

1. Polling Strategy

// Example polling implementation
const checkTransactionStatus = async (transactionId) => {
  const response = await fetch(`/api/v1/transactions/${transactionId}`, {
    headers: { 'Authorization': 'Bearer <token>' }
  });
  const transaction = await response.json();
  return transaction.status;
};

// Poll every 5 seconds for non-final statuses
const finalStatuses = [
  'TRANSACTION.CONFIRMED',
  'TRANSACTION.FAILED',
  'TRANSACTION.DROPPED',
  'TRANSACTION.CANCELLED'
];

2. Error Handling

const handleTransactionStatus = (status, subStatus) => {
  switch (status) {
    case 'TRANSACTION.FAILED':
      if (subStatus === 'TRANSACTION.INSUFFICIENT_FEE') {
        // Prompt user to add funds for fees
      } else if (subStatus === 'TRANSACTION.INSUFFICIENT_FUND') {
        // Prompt user to add funds or reduce amount
      }
      break;
    case 'TRANSACTION.STUCK':
      // Consider showing speed up options for Bitcoin RBF
      break;
    case 'TRANSACTION.DROPPED':
      // Offer to retry the transaction
      break;
  }
};

Status Timelines by Blockchain

Ethereum/EVM Chains

NEW → BROADCASTED: 1-30 seconds
AWAITING_CONFIRMATION: 15 seconds - 10+ minutes (depends on gas price)
Total time: 30 seconds - 15 minutes

Bitcoin

NEW → BROADCASTED: 1-60 seconds
AWAITING_CONFIRMATION: 10 minutes - 6+ hours (depends on fee rate)
Total time: 10 minutes - 6+ hours

Solana

NEW → BROADCASTED: 1-10 seconds
AWAITING_CONFIRMATION: 1-30 seconds
Total time: 2-40 seconds

TRON

NEW → BROADCASTED: 1-15 seconds
AWAITING_CONFIRMATION: 1-3 minutes
Total time: 1-5 minutes

Troubleshooting Common Status Issues

Transaction Stuck in PROCESSING

Possible causes:

High network congestion
Wallet has many pending transactions
System processing delays

Solutions:

Wait for natural progression
Check for earlier pending transactions
Contact support if stuck for >30 minutes

Transaction Stuck in AWAITING_CONFIRMATION

Possible causes:

Low fees (Bitcoin/Ethereum)
Network congestion
Blockchain issues

Solutions:

For Bitcoin: Use RBF to increase fees
For Ethereum: Wait or use transaction acceleration services
Monitor blockchain network status

Frequent INSUFFICIENT_FEE Errors

Solutions:

Use fee estimation endpoints before transactions
Maintain adequate native token balances
Monitor network congestion for fee planning
Use gas station to ensure you have enough fees

This comprehensive status guide helps developers understand the complete transaction lifecycle and implement robust transaction monitoring in their applications.