get_transaction_history_for_user

Instructions

Implementation Reference

• src/operations/transactions.ts:62-125 (handler)

  Core handler function that implements the tool logic by calling the Bankless API to fetch transaction history for a user.

  export async function getTransactionHistory(
      network: string,
      user: string,
      contract?: string | null,
      methodId?: string | null,
      startBlock?: string | null,
      includeData: boolean = true
  ): Promise<SimplifiedTransactionVO[]> {
      const token = process.env.BANKLESS_API_TOKEN;
  
      if (!token) {
          throw new BanklessAuthenticationError('BANKLESS_API_TOKEN environment variable is not set');
      }
  
      const endpoint = `${BASE_URL}/chains/${network}/transaction-history`;
  
      try {
          const response = await axios.post(
              endpoint,
              {
                  user,
                  contract,
                  methodId,
                  startBlock,
                  includeData
              },
              {
                  headers: {
                      'Content-Type': 'application/json',
                      'X-BANKLESS-TOKEN': `${token}`
                  }
              }
          );
  
          const data = Array.isArray(response.data) ? response.data : [];
  
          if (data.length > 10000) {
              throw new BanklessValidationError(`too many results, try again with a more specific query`);
          }
  
          return data;
      } catch (error) {
          if (axios.isAxiosError(error)) {
              const statusCode = error.response?.status || 'unknown';
              const errorMessage = error.response?.data?.message || error.message;
  
              if (statusCode === 401 || statusCode === 403) {
                  throw new BanklessAuthenticationError(`Authentication Failed: ${errorMessage}`);
              } else if (statusCode === 404) {
                  throw new BanklessResourceNotFoundError(`Not Found: ${errorMessage}`);
              } else if (statusCode === 422) {
                  throw new BanklessValidationError(`Validation Error: ${errorMessage}`, error.response?.data);
              } else if (statusCode === 429) {
                  // Extract reset timestamp or default to 60 seconds from now
                  const resetAt = new Date();
                  resetAt.setSeconds(resetAt.getSeconds() + 60);
                  throw new BanklessRateLimitError(`Rate Limit Exceeded: ${errorMessage}`, resetAt);
              }
  
              throw new Error(`Bankless API Error (${statusCode}): ${errorMessage}`);
          }
          throw new Error(`Failed to get transaction history: ${error instanceof Error ? error.message : String(error)}`);
      }
  }

• src/operations/transactions.ts:13-20 (schema)

  Zod schema defining the input parameters for the get_transaction_history_for_user tool.

  export const TransactionHistorySchema = z.object({
      network: z.string().describe('The blockchain network (e.g., "ethereum", "base")'),
      user: z.string().describe('The user address'),
      contract: z.string().nullable().optional().describe('The contract address (optional)'),
      methodId: z.string().nullable().optional().describe('The method ID to filter by (optional)'),
      startBlock: z.string().nullable().optional().describe('The starting block number (optional)'),
      includeData: z.boolean().default(true).describe('Whether to include transaction data')
  });

• src/index.ts:111-115 (registration)

  Tool registration in the ListTools response, including name, description, and input schema reference.

  {
      name: "get_transaction_history_for_user",
      description: "Gets transaction history for a user and optional contract",
      inputSchema: zodToJsonSchema(transactions.TransactionHistorySchema),
  },

• src/index.ts:219-232 (handler)

  Dispatch handler in the main server that parses arguments and delegates to the core implementation.

  case "get_transaction_history_for_user": {
      const args = transactions.TransactionHistorySchema.parse(request.params.arguments);
      const result = await transactions.getTransactionHistory(
          args.network,
          args.user,
          args.contract,
          args.methodId,
          args.startBlock,
          args.includeData
      );
      return {
          content: [{type: "text", text: JSON.stringify(result, null, 2)}],
      };
  }