transactions_list

Endpoint

GET /v1/transactions

Query Parameters

Name	Type	Required	Description
start	string	No	Starting version
limit	integer	No	Page size

Response

Success Response (200)

Returns an array of transaction objects ordered by version:

[
  {
    "version": "123456789",
    "hash": "0x...",
    "sender": "0x...",
    "success": true,
    "vm_status": "Executed successfully",
    "gas_used": "8",
    "payload": {...},
    "events": [...],
    "timestamp": "1234567890"
  }
]

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid start version or limit value

Code Examples

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

Python pagination example:

from aptos_sdk.client import RestClient

client = RestClient("https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1")
start_version = 0
limit = 100

while True:
    txns = client.transactions(start=start_version, limit=limit)
    if not txns:
        break
    for txn in txns:
        process_transaction(txn)
    start_version = int(txns[-1]['version']) + 1

TypeScript example:

const txns = await aptos.getTransactions({
  options: { offset: 0, limit: 25 }
});
console.log(`Fetched ${txns.length} transactions`);

Use Cases

Transaction listing serves multiple critical purposes:

1. Blockchain Explorers: Display recent transactions on the homepage or activity feed, showing latest network activity to users.

2. Indexing Pipelines: Sequentially process all transactions from a starting point to build custom indexes, analytics, or application-specific databases.

3. Activity Monitoring: Poll recent transactions to monitor network activity, detect specific transaction patterns, or trigger alerts.

4. Historical Analysis: Retrieve historical transaction ranges for data analysis, research, or regulatory compliance requirements.

5. State Reconstruction: Replay transactions in order to reconstruct account or contract state at any point in history.

6. Testing and Debugging: Fetch recent transactions to understand network behavior during development and troubleshooting.

Best Practices

Optimal Limit Values: Use limit=100-1000 for efficient bulk retrieval. Smaller limits require more API calls, larger limits may hit response size constraints.

Pagination Pattern: Use the last transaction's version + 1 as the next start parameter. Never rely on limit*page calculations as they miss concurrent transactions.

Rate Limiting: When processing historical data, implement rate limiting (10-20 requests/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.

Empty Response Handling: An empty array means you've reached the current head of the chain. Wait 5-10 seconds before polling again to allow new transactions to be processed.

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

Performance Considerations

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

Total response size depends on transaction complexity:

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

For high-throughput processing, consider using the transaction streaming API which provides better performance than REST pagination for sequential access to large ranges.

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

Comparison with Streaming API

For processing large ranges of transactions:

• REST pagination: Simpler integration, works with any HTTP client, better for sporadic queries
• Streaming API: Higher throughput (10-100x), lower latency, better for continuous synchronization

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