AgentPay-mcp

Instructions

Implementation Reference

• src/tools/history.ts:84-153 (handler)

  The handler function that executes the 'get_transaction_history' tool logic, including fetching and filtering transaction events.

  export async function handleGetTransactionHistory(
    input: GetTransactionHistoryInput
  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
    try {
      const wallet = getWallet();
      const config = getConfig();
  
      // Default: look back ~1000 blocks if no range specified
      let fromBlock: bigint | undefined;
      let toBlock: bigint | undefined;
  
      if (input.from_block) {
        fromBlock = BigInt(input.from_block);
      } else {
        // Get current block and look back ~1000 blocks
        const latest = await wallet.publicClient.getBlockNumber();
        fromBlock = latest > 1000n ? latest - 1000n : 0n;
      }
  
      if (input.to_block) {
        toBlock = BigInt(input.to_block);
      }
  
      const allEntries = await getActivityHistory(wallet, {
        fromBlock,
        toBlock,
      });
  
      // Filter by event type
      const eventType = input.event_type ?? 'all';
      const filtered = eventType === 'all'
        ? allEntries
        : allEntries.filter((e) => e.type === eventType);
  
      // Apply limit (most recent first after sort)
      const limit = input.limit ?? 20;
      const recent = filtered.slice(-limit).reverse();
  
      if (recent.length === 0) {
        return {
          content: [
            textContent(
              `📜 **Transaction History**\n\n` +
              `No transactions found in the queried range.\n\n` +
              `  Block range: ${fromBlock?.toString() ?? '0'} → ${toBlock?.toString() ?? 'latest'}\n` +
              `  Event type:  ${eventType}\n\n` +
              `Try expanding the from_block range for older history.`
            ),
          ],
        };
      }
  
      let out = `📜 **Transaction History** (${recent.length} entries)\n`;
      out += `  Chain:       ${chainName(config.chainId)}\n`;
      out += `  Block range: ${fromBlock?.toString() ?? '0'} → ${toBlock?.toString() ?? 'latest'}\n`;
      out += `  Filter:      ${eventType}\n\n`;
  
      for (const entry of recent) {
        out += formatActivityEntry(entry, config.chainId);
        out += '\n';
      }
  
      return { content: [textContent(out)] };
    } catch (error: unknown) {
      return {
        content: [textContent(formatError(error, 'get_transaction_history'))],
        isError: true,
      };
    }
  }

• src/tools/history.ts:20-42 (schema)

  Input validation schema for the 'get_transaction_history' tool.

  export const GetTransactionHistorySchema = z.object({
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .default(20)
      .describe('Maximum number of entries to return (default: 20, max: 100)'),
    from_block: z
      .string()
      .optional()
      .describe('Start block number (hex or decimal string). Defaults to recent history.'),
    to_block: z
      .string()
      .optional()
      .describe('End block number. Defaults to latest.'),
    event_type: z
      .enum(['all', 'execution', 'queued', 'approved', 'cancelled', 'policy_update', 'operator_update'])
      .optional()
      .default('all')
      .describe('Filter by event type (default: all)'),
  });

• src/tools/history.ts:48-80 (registration)

  Tool definition and registration object for 'get_transaction_history'.

  export const getTransactionHistoryTool = {
    name: 'get_transaction_history',
    description:
      'Retrieve the wallet\'s recent on-chain transaction history from event logs. ' +
      'Shows executions, queued transactions, approvals, cancellations, ' +
      'spend policy updates, and operator changes. ' +
      'Filter by event type or block range for targeted queries.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        limit: {
          type: 'number',
          description: 'Max entries to return (default: 20, max: 100)',
          default: 20,
        },
        from_block: {
          type: 'string',
          description: 'Start block (decimal string). Defaults to 1000 blocks ago.',
        },
        to_block: {
          type: 'string',
          description: 'End block (decimal string). Defaults to latest.',
        },
        event_type: {
          type: 'string',
          enum: ['all', 'execution', 'queued', 'approved', 'cancelled', 'policy_update', 'operator_update'],
          description: 'Filter by event type (default: all)',
          default: 'all',
        },
      },
      required: [],
    },
  };