Bankless Onchain MCP Server

Instructions

Implementation Reference

• src/operations/transactions.ts:130-176 (handler)

  The core handler function that retrieves detailed transaction information from the Bankless API, including error handling for authentication, rate limits, and not found cases.

  export async function getTransactionInfo(
      network: string,
      txHash: string
  ): Promise<TransactionInfoVO> {
      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}/tx/${txHash}`;
  
      try {
          const response = await axios.get(
              endpoint,
              {
                  headers: {
                      'Content-Type': 'application/json',
                      'X-BANKLESS-TOKEN': `${token}`
                  }
              }
          );
  
          return response.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(`Transaction not found: ${txHash}`);
              } 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 info: ${error instanceof Error ? error.message : String(error)}`);
      }
  }

• src/operations/transactions.ts:23-26 (schema)

  Zod schema defining the input parameters for the get_transaction_info tool: network and txHash.

  export const TransactionInfoSchema = z.object({
      network: z.string().describe('The blockchain network (e.g., "ethereum", "polygon")'),
      txHash: z.string().describe('The transaction hash to fetch details for')
  });

• src/index.ts:116-120 (registration)

  Tool registration in the listTools handler, specifying name, description, and input schema.

  {
      name: "get_transaction_info",
      description: "Gets detailed information about a specific transaction",
      inputSchema: zodToJsonSchema(transactions.TransactionInfoSchema),
  },

• src/index.ts:233-242 (handler)

  Dispatch handler in the CallToolRequestSchema that parses input, calls the transaction handler, and formats the response.

  case "get_transaction_info": {
      const args = transactions.TransactionInfoSchema.parse(request.params.arguments);
      const result = await transactions.getTransactionInfo(
          args.network,
          args.txHash
      );
      return {
          content: [{type: "text", text: JSON.stringify(result, null, 2)}],
      };
  }