Ethereum Phishing Domain Detector

1.2.0 · active · verified Sun Apr 19

The `eth-phishing-detect` utility is a JavaScript library designed to identify and block domains known for targeting Ethereum users with phishing attacks. Maintained by MetaMask, it provides an up-to-date list of malicious websites, actively evolving its blocking policy to include sites that impersonate established services or attempt to collect cryptocurrency keys. The package is currently at version `1.2.0` and was last published about 4 years ago (as of April 2026), with prior versions indicating a more active cadence for configuration updates. It differentiates itself through its direct integration and maintenance by a major wallet provider, offering a robust and proactive defense mechanism against specific web3-related threats. Developers can use it to integrate real-time phishing detection into their applications, enhancing user security by preventing access to known harmful sites.

Common errors

```
TypeError: checkForPhishing is not a function
```
cause Attempting to import `checkForPhishing` as a named export in CommonJS, or incorrectly destructuring the default ESM import.

fix For CommonJS: `const checkForPhishing = require('eth-phishing-detect')`. For ESM: `import checkForPhishing from 'eth-phishing-detect'`.
```
Cannot find module 'eth-phishing-detect/src/detector'
```
cause This error can occur in ESM environments or with certain bundler configurations if the `src/` path is not correctly resolved as a subpath export, or if the `detector` module has been refactored.

fix For ESM, try `import { PhishingDetector } from 'eth-phishing-detect/detector'`. If using CJS and facing this issue, ensure your build system supports direct `src/` imports or check for an alternative, stable path in the package's `package.json` `exports` field.

Warnings

breaking Version 1.2.0 changed the configuration object and return value if an array of configuration values is passed to the PhishingDetector constructor. While backward compatible for single configuration objects, new usage with arrays will have a different API shape and return type.
Fix: Review the documentation for `PhishingDetector` constructor when passing an array of configurations. Adjust code to handle the new return value structure (e.g., an array of results instead of a single object).
gotcha The README's advanced usage example for CommonJS directly imports from `eth-phishing-detect/src/detector`. Directly importing from `src/` paths is generally discouraged as they are often internal, unstable, and may change in minor or patch releases, potentially breaking your application.
Fix: For CommonJS, use the documented `require('eth-phishing-detect/src/detector')` if you must, but be aware of potential instability. For ESM, prefer `import { PhishingDetector } from 'eth-phishing-detect/detector'` for potentially better stability and compatibility.
gotcha The blocking policy for phishing domains is constantly evolving and updated by MetaMask. While this ensures up-to-date protection, it means the exact list of blocked domains can change without a new package version, only through configuration updates.
Fix: Integrators should be aware that the underlying blocklist is dynamic. Avoid hardcoding assumptions about specific blocked or whitelisted domains. Regularly check the interactive page or library updates for policy changes.

Install

npm install eth-phishing-detect npm
yarn add eth-phishing-detect yarn
pnpm add eth-phishing-detect pnpm

Imports

checkForPhishing
wrong:
```
const { checkForPhishing } = require('eth-phishing-detect')
```
correct:
```
import checkForPhishing from 'eth-phishing-detect'
```
The main entry point is a default export in ESM, and a direct module export in CJS. Avoid destructuring for CJS.
PhishingDetector
wrong:
```
const PhishingDetector = require('eth-phishing-detect/src/detector')
```
correct:
```
import { PhishingDetector } from 'eth-phishing-detect/detector'
```
The README's CJS example uses `require('eth-phishing-detect/src/detector')`. For ESM and stability, import from `eth-phishing-detect/detector`.
PhishingDetector (CommonJS)
```
const PhishingDetector = require('eth-phishing-detect/src/detector')
```
This specific path is provided in the README for CommonJS advanced usage. While it uses `src/`, it's the documented CJS path for this class.

Quickstart

Demonstrates initializing the `PhishingDetector` with custom lists and checking various domains for phishing status, including legitimate, blacklisted, and fuzzy-matched examples.

import { PhishingDetector } from 'eth-phishing-detect/detector';

// Example configuration (these are just illustrative values)
const whitelist = ['mylegitwallet.com'];
const blacklist = ['fakephishingsite.net'];
const fuzzylist = ['fuzzyphishing.io'];
const tolerance = 2;

const detector = new PhishingDetector({
  whitelist,
  blacklist,
  fuzzylist,
  tolerance
});

// Check a known phishing domain
const resultPhishing = detector.check('fakephishingsite.net');
console.log('Is fakephishingsite.net phishing?', resultPhishing); 
// Expected: { type: 'blacklist', result: true, url: 'fakephishingsite.net' }

// Check a legitimate domain
const resultLegit = detector.check('google.com');
console.log('Is google.com phishing?', resultLegit);
// Expected: { result: false, url: 'google.com' }

// Check a fuzzy match
const resultFuzzy = detector.check('fuzzyphising.io'); // typo 'phising'
console.log('Is fuzzyphising.io phishing?', resultFuzzy);
// Expected: { type: 'fuzzylist', result: true, url: 'fuzzyphising.io', ... }

view raw JSON →