transactions_list

Overview

List transactions from the Aptos blockchain ordered by ledger version. Supports cursor-based pagination via the start parameter, making it suitable for sequential processing, indexing pipelines, and building block explorers. Returns transactions across all accounts, not filtered by sender.

Endpoint

GET /v1/transactions

Code Examples

Bash

# Get the 25 most recent transactions
curl -X GET "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions?limit=25" \
  -H "Accept: application/json"

# Get transactions starting from a specific version
curl -X GET "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions?start=100000000&limit=100" \
  -H "Accept: application/json"

Pagination Guide

This endpoint uses version-based cursor pagination:

First page: Omit start to get the most recent transactions, or specify a version to start from a specific point.
Next page: Take the version of the last transaction in the response, add 1, and use it as start.
End detection: An empty array or fewer results than limit means you have reached the current chain head.

Python

# Complete pagination pattern
start_version = 0
while True:
    txns = client.transactions(start=start_version, limit=100)
    if not txns:
        # Reached chain head - wait and retry for real-time tailing
        time.sleep(5)
        continue
    for txn in txns:
        process(txn)
    start_version = int(txns[-1]["version"]) + 1

Transactions are contiguous with no version gaps. If you encounter missing versions, it indicates a processing error that needs investigation.

Use Cases

Blockchain Explorers: Display recent transactions on the homepage or activity feed, showing the latest network activity with filtering and search.
Indexing Pipelines: Sequentially process all transactions from a starting point to build custom indexes, analytics databases, or application-specific data stores.
Activity Monitoring: Poll recent transactions to monitor network activity, detect specific transaction patterns (large transfers, contract deployments), or trigger alerts.
Historical Analysis: Retrieve historical transaction ranges for data analysis, research, or regulatory compliance requirements.
State Reconstruction: Replay transactions in order to reconstruct account or contract state at any point in history.
Testing and Debugging: Fetch recent transactions to understand current network behavior during development and troubleshooting.

Best Practices

Optimal Limit Values: Use limit=100 for efficient bulk retrieval. Smaller limits require more API calls; larger values hit the 100-transaction maximum.

Pagination Pattern: Always use the last transaction's version + 1 as the next start parameter. Never rely on limit * page calculations, as system transactions and version numbers are sequential.

Rate Limiting: When processing historical data, implement rate limiting (10-20 requests per second) to avoid overwhelming the API and hitting quota limits.

Cursor Persistence: Save your current position (start version) frequently. If processing stops, resume from the last successfully processed version rather than restarting from the beginning.

Empty Response Handling: An empty array means you have reached the current chain head. Wait 4-5 seconds (one block time) before polling again.

System Transactions: The response includes system transactions (block_metadata, state_checkpoint) alongside user transactions. Filter by type if you only need user transactions.

Performance Considerations

Transaction list queries are optimized for sequential access patterns. Fetching 100 transactions typically completes in 100-200ms. Response times scale linearly with the limit value.

Total response size depends on transaction complexity:

Simple transfers: approximately 2KB per transaction
Smart contract calls: approximately 5-15KB per transaction
Complex multi-agent transactions: approximately 20-50KB per transaction

For high-throughput processing, consider using the Aptos gRPC streaming API which provides 10-100x better throughput than REST pagination for sequential access to large ranges of transactions.

The default limit when not specified is 25 transactions. Always specify explicit limits for production code to ensure consistent behavior across API versions.

Comparison with Streaming API

For processing large ranges of transactions:

Feature	REST Pagination	gRPC Streaming
Integration complexity	Simple HTTP client	gRPC client required
Throughput	100-500 txns/sec	10,000-50,000 txns/sec
Latency	Per-request round trip	Continuous stream
Best for	Ad-hoc queries, small ranges	Real-time tailing, bulk historical
Protocol	HTTP/JSON	gRPC/protobuf

Choose REST for ad-hoc queries and small ranges. Choose gRPC streaming for real-time tailing or bulk historical processing.

/v1/transactions/by_hash/{hash} - Look up a specific transaction by hash
/v1/transactions/by_version/{version} - Look up by version (faster for known versions)
/v1/accounts/{address}/transactions - List transactions for a specific account
/v1 - Get current ledger version to determine the latest available data

On this page