Transaction History API

This API endpoint allows you to retrieve the transaction history for a user's wallet address. It supports pagination, filtering, and provides detailed transaction information.

Endpoint

GET /api/wallet/history

Authentication

This endpoint requires authentication. Ensure that the user is logged in and has a valid session.

Query Parameters

Parameter	Type	Description
page	number	The page number for pagination. Default is 1.
pageSize	number	The number of transactions per page. Default is 10.
startBlock	number	(Optional) The starting block number to fetch transactions from.
endBlock	number	(Optional) The ending block number to fetch transactions to.
type	string	(Optional) Filter by transaction type.
minAmount	string	(Optional) Filter by minimum transaction amount (in ETH).
maxAmount	string	(Optional) Filter by maximum transaction amount (in ETH).

Response

The API returns a JSON object with the following structure:

{
  history: Array<{
    hash: string;
    from: string;
    to: string | null;
    value: string;
    gasPrice: string | null;
    gasLimit: string | undefined;
    gasUsed: string | undefined;
    timestamp: number;
    status: 'Success' | 'Failed';
    type: number;
    contractInteraction: boolean;
  }>;
  pagination: {
    page: number;
    pageSize: number;
    totalPages: number;
    totalItems: number;
  };
}

Usage Example

Fetch the first page of transaction history:

const response = await fetch('/api/wallet/history');
const data = await response.json();

Pagination

Fetch the second page with 20 items per page:

const response = await fetch('/api/wallet/history?page=2&pageSize=20');
const data = await response.json();

Filtering

Fetch transactions within a specific block range:

const response = await fetch('/api/wallet/history?startBlock=1000000&endBlock=2000000');
const data = await response.json();

Filter transactions by type and amount:

const response = await fetch('/api/wallet/history?type=2&minAmount=0.1&maxAmount=1.0');
const data = await response.json();

Error Responses

Status Code	Description
401	Unauthorized - User is not authenticated
404	Not Found - User wallet not found
500	Internal Server Error - Failed to fetch transaction history

Usage Notes

1. The API caches recent transaction history for 5 minutes to reduce blockchain queries.
2. The maximum number of blocks that can be queried in a single request is limited to 1000 for performance reasons.
3. If startBlock and endBlock are not provided, the API will fetch the most recent 1000 blocks.
4. Transaction amounts are returned in ETH, not Wei.
5. The contractInteraction field indicates whether the transaction involved interaction with a smart contract.

Best Practices

1. Use pagination to improve performance and reduce load times for users.
2. Implement error handling in your client-side code to gracefully handle API errors.
3. Consider implementing client-side caching to further reduce API calls for frequently accessed data.
4. When filtering by date, use block numbers instead of timestamps for more accurate results.

Limitations

1. The API currently only supports Ethereum and Polygon networks.
2. Historical data beyond 1000 blocks may require multiple API calls.
3. The accuracy of gas prices and transaction status depends on the underlying blockchain provider.

Future Enhancements

We are planning to add the following features in future updates:

1. Support for multiple blockchain networks
2. Webhook notifications for new transactions
3. Enhanced filtering options (e.g., by token type for ERC-20 and ERC-721 transactions)
4. Aggregated statistics for wallet activity

Stay tuned for updates and feel free to provide feedback for improvements!