transactions_wait_by_hash

Overview

Wait for a transaction to be committed or to expire. This endpoint blocks (long-polls) until the transaction identified by its hash appears on-chain or the server-side wait window elapses. It is the recommended way to confirm transaction execution after submission.

Note: Dwellir Aptos fullnodes do expose /transactions/wait_by_hash. Keep a polling fallback only when you need custom retry behavior in your own client.

If you call this endpoint with an unknown hash, the node may return transaction_not_found immediately instead of holding the request open for the full timeout window.

Endpoint

GET /v1/transactions/wait_by_hash/{txn_hash}

Polling Behavior

If you need custom timeout control or want to avoid a single long-held request, implement client-side polling:

Submit the transaction via POST /v1/transactions
Poll GET /v1/transactions/by_hash/{hash} at regular intervals
A 200 response with type: "pending_transaction" means the hash is known but not committed yet
A committed transaction also returns 200 -- check type, success, and vm_status
Stop polling when expiration_timestamp_secs has passed and the transaction has not appeared

Recommended polling interval is 1-2 seconds. Aptos block time is approximately 4 seconds on mainnet, so polling more frequently than once per second provides no benefit.

Code Examples

Bash

# Native wait (when available)
curl -X GET "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions/wait_by_hash/0x0985b0179db0c0971bb9bf331dff7fdae6dacf73cee48a1ec6be614f41d4d383" \
  -H "Accept: application/json"

# Polling fallback (recommended for shared nodes)
curl -X GET "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions/by_hash/0x0985b0179db0c0971bb9bf331dff7fdae6dacf73cee48a1ec6be614f41d4d383" \
  -H "Accept: application/json"

Use Cases

Transaction Confirmation Flow: After submitting a transfer or smart contract call, wait for on-chain confirmation before updating your application state or notifying the user.
Sequential Transaction Pipelines: When transactions depend on each other (such as approve then swap on a DEX), wait for each to confirm before submitting the next to ensure correct sequence numbers.
Payment Processing: In commerce applications, hold the checkout flow until the payment transaction is confirmed on-chain, then release the goods or services.
Multi-Signature Coordination: After the final signer submits a multi-sig transaction, all parties can wait on the hash to confirm the collective operation succeeded.
Retry Logic: If a transaction is not confirmed within the expected window, resubmit with a higher gas price or updated expiration to handle network congestion.

Best Practices

Client Timeouts: If you wrap this endpoint with your own retry loop, set your HTTP timeout longer than the node's wait window and keep a separate client-side deadline for the overall confirmation flow.

Expiration Awareness: If expiration_timestamp_secs has passed and the transaction is not on-chain, it will never be executed. Stop polling and consider resubmitting.

Success vs Execution: A confirmed transaction (200 response) does not guarantee success. Always check the success field -- a transaction can be committed but fail at the Move VM level (for example, insufficient balance).

Idempotency: Polling by_hash is safe to repeat. The same hash always returns the same committed transaction once available.

Connection Timeouts: When using the native blocking endpoint, ensure your HTTP client timeout comfortably exceeds the server's wait window so the request is not cut off prematurely.

Performance Considerations

The native wait_by_hash endpoint uses server-side long polling, which is more efficient than client-side polling because it avoids repeated HTTP round trips. Use polling when you need custom retry control or want to multiplex many outstanding waits in your own worker.

With client-side polling at 1.5-second intervals, a typical transaction confirms after 2-3 polls (3-5 seconds). The overhead is minimal: each poll is a lightweight hash-indexed lookup completing in 50-100ms.

For applications processing many concurrent transactions, use parallel polling with a shared connection pool rather than sequential waits to maximize throughput.

/v1/transactions - Submit a signed transaction
/v1/transactions/by_hash/{txn_hash} - Get transaction by hash (non-blocking)
/v1/transactions/by_version/{txn_version} - Get transaction by version
/v1/transactions/simulate - Simulate before submitting

On this page