get_wallet_balance_by_time_v4
Retrieve native wallet balances for up to 10 addresses at a specific block number, time, or Unix timestamp on supported blockchains using Tatum MCP Server’s API.
Instructions
[blockchain_data] /v4/data/wallet/balance/time 100 credits per API call Get native balances for a specific wallet addresses by time on the following blockchains: Ethereum - ethereum-mainnet Bitcoin - bitcoin-mainnet Base - base-mainnet Arbitrum - arb-one-mainnet BSC - bsc-mainnet Polygon - polygon-mainnet Optimism - optimism-mainnet Celo - celo-mainnet To get started, provide a chain name, comma-separated list of addresses and specify one of the filters listed below (combination of the filters is not allowed): block number time unix If you pass a block number that is in the future (beyond the current latest block), the system will return the balance for the latest block. If you pass a time or Unix timestamp that is in the future, the system will also return the balance for the latest block. If you pass a time or Unix timestamp in the past (dating back to or earlier than the blockchain's genesis block), the system will return the balance for the first block (genesis block).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addresses | Yes | The blockchain public wallet addresses. It is possible to enter list of up to 10 addresses as a comma separated string. | |
| blockNumber | No | Block number. | |
| chain | Yes | The blockchain to work with. | |
| time | No | Time when block is processed. | |
| unix | No | Unix timestamp when block is processed. |
Implementation Reference
- src/services/data.ts:323-334 (handler)The handler function getWalletBalanceByTime that executes the tool logic by calling the Tatum API v4 endpoint /v4/data/wallet/balance/time with the provided parameters.
async getWalletBalanceByTime(args: any): Promise<any> { const url = `/v4/data/wallet/balance/time`; const parameters: any = { chain: args.chain, addresses: args.addresses }; if (args.blockNumber) parameters.blockNumber = args.blockNumber; if (args.time) parameters.time = args.time; if (args.unix) parameters.unix = args.unix; return await this.apiClient.executeRequest('GET', url, parameters); } - src/services/data.ts:29-59 (schema)Input schema definition for the get_wallet_balance_by_time tool, including parameters like chain, addresses, blockNumber, time, unix.
{ name: 'get_wallet_balance_by_time', description: 'Get native wallet balances at specific time or block.', inputSchema: { type: 'object', properties: { chain: { type: 'string', description: 'The blockchain to work with.', example: 'ethereum-mainnet' }, addresses: { type: 'string', description: 'The blockchain public wallet addresses. It is possible to enter list of up to 10 addresses as a comma separated string.' }, blockNumber: { type: 'string', description: 'Block number.' }, time: { type: 'string', description: 'Time when block is processed.' }, unix: { type: 'number', description: 'Unix timestamp when block is processed.' } }, required: ['chain', 'addresses'] } }, - src/index.ts:121-125 (registration)Registration and dispatch of the get_wallet_balance_by_time tool in the MCP server's executeDataTool switch statement, which calls the DataService handler.
case 'get_wallet_balance_by_time': if (!args.chain || !args.addresses) { throw new McpError(ErrorCode.InvalidParams, 'Missing required parameters: chain, addresses'); } return await this.dataService.getWalletBalanceByTime(args);