Skip to content

Scam Detector Docs

Overview

The Scam Detector is an ideal source of threat intelligence for Web3 wallets and dashboard tools, as well as for security and compliance solutions serving retail or institutional audiences. Use the Scam Detector to build or supplement a blacklist, or as a transaction risk signal by querying it at approval/signing time to determine whether an entity is potentially malicious.

The Scam Detector provides threat intelligence about malicious smart contracts, EOAs, and URLs engaging in scams and other end-user attacks. It relies on a bundle of underlying Forta bots, each monitoring for specific scam behaviors.

The Scam Detector and its underlying bots are collectively maintained by the Forta community, including the Forta Foundation, Nethermind, and individual security researchers and developers.

How it works

Forta bots are monitoring on-chain activity 24/7/365. Some bots leverage a heuristic-based approach, others leverage machine learning to identify malicious activity. When bots identify an attack or scam on-chain, they create two types of threat intelligence:

Labels. A persistent tag placed on an entity (smart contract, EOA, URL) responsible for a scam or attack. Today, the Scam Detector assigns one label: “scammer” (additional labels, like "victim" and "stolen asset" may follow). The label will contain the following information:

  • label/entity - the address (either EOA or contract address) or URL
  • label/entityType - EntityType.ADDRESS or EntityType.Url
  • label/confidence - a confidence score from 0-1.0 with 1.0 being the most confident the label is correct
  • label/remove - a flag indicating whether the label is being added or removed
  • label/label - a string denoting the label that was placed on the entity. It currently is set to 'scammer'
  • label/metadata/bot_version - version of the bot when the label was added
  • label/metadata/threat_category - (see below)
  • label/metadata/address_type - EOA or contract (addresses only)
  • label/metadata/logic - (passthrough, ml, manual)
  • label/metadata/threat_description_url - URL that describes the threat_category in more detail

Supported threat categories (current)

The Scam Detector currently labels onchain activity for the following categories:

  • phishing — Fired when alert combinations indicate phishing/drainer-style scam activity.
  • address-poisoning — Fired when alert combinations indicate address poisoning behavior.
  • impersonating-token — Fired when a token contract is identified as impersonating an established token (e.g., USDC/USDT/ETH-branded impersonation patterns).

Using the Scam Detector

The Scam Detector labels are each available via Forta's GraphQL API. For accessing threat intel from the Scam Detector, we recommend querying labels generated by this bot (sourceIds parameter needs to be set to ["0x1d646c4045189991fdfd24a66b192a294158b839a6ec121d740474bdacb3ab23"].) The primary label is 'scammer'.

Labels

Labels allow a contributor to tag an entity (like an address) with a label. Labels are available via our GraphQL API. This API allows one to search by date range and page over results.

A recent one month sample of the labels can be downloaded here (prod, V1 label format) and here (beta, V2 label format).

Note:

To request entries that are currently accurate (and not later removed), pass state: true as part of the input. Otherwise, the response will contain point-in-time events (which may contain removal (remove:true) events).

At least one of: labels, sourceIds, or entities is required.

Example Query 

query Labels($input: LabelsInput) {
  labels(input: $input) {
    labels {
      label {
        label
        entity
        metadata
      }
      createdAt
    }
    pageInfo {
      endCursor {
        pageToken
      }
      hasNextPage
    }
  }
}

Example Input 

{
  "input": {
    "sourceIds": [
      "0x1d646c4045189991fdfd24a66b192a294158b839a6ec121d740474bdacb3ab23"
    ],
    "labels": [
      "scammer"
    ],
    "state": true,
    "first": 5,
    "metadata": {
      "chain_id": 56
    },
    "afterCreatedAtDate": "2023-04-03T15:01:33Z",
    "beforeCreatedAtDate": "2023-04-03T15:10:45Z",
    "after": {
      "pageToken": "29427820"
    }
  }
}

For a complete list of options, see the LabelsInput specification

Example Response 

{
 "data": {
   "labels": {
     "pageInfo": {
       "hasNextPage": true,
       "endCursor": {
         "pageToken": "21193"
       }
     },
     "labels": [
       {
          "createdAt": "2023-07-04T23:09:35.614989763Z",
          "id": "0x97555444ff87aa9a56431571c906c6ef7ab25a24165fed6b72969964d455dadb",
          "label": {
            "label": "scammer",
            "metadata": [
              "address_type=contract",
              "base_bot_alert_hashes=0x8f5e07151a1666d387a163bf91efdb346bc65c53c260e9e043125e762437ea84",
              "base_bot_alert_ids=SOFT-RUG-PULL-SUS-POOL-REMOVAL",
              "bot_version=2.15.3",
              "chain_id=1",
              "deployer_info=Deployer 0x02caf8b1e4b59529c9c100e8f0f90a3faeeeb2e4 involved in SCAM-DETECTOR-SOFT-RUG-PULL scam; this contract has been associated with this scam.",
              "feature_vector=",
              "label_version=2.1.0",
              "logic=passthrough",
              "model_name=v3_scammer_model.joblib",
              "threat_category=soft-rug-pull",
              "threat_description_url=https://forta.org/attacks#rug-pull"
            ],
            "remove": false,
            "entityType": "ADDRESS",
            "entity": "0x9bc388edeeb94c8017e0a6e178a8e7cb40f3d1f3",
            "confidence": 0.477
          },
          "source": {
            "chainId": 1,
            "alertId": "SCAM-DETECTOR-SOFT-RUG-PULL",
            "bot": {
              "id": "0x47c45816807d2eac30ba88745bf2778b61bc106bc76411b520a5289495c76db8"
            },
            "alertHash": "0x1b11901bfca2873e83a1cba50ee937a35279b873eff56214eaaefbe068c3582a"
          }
        }
     ]
   }
  }
}

Example as curl 

curl --request POST \
    --header 'content-type: application/json' \
    --url 'https://api.forta.network/graphql' \
    --data '{"query":"query Labels($input: LabelsInput) {\n  labels(input: $input) {\n    labels {\n      label {\n        label\n        entity\n        metadata\n      }\n      createdAt\n    }\n    pageInfo {\n      endCursor {\n        pageToken\n      }\n      hasNextPage\n    }\n  }\n}","variables":{"input":{"sourceIds":["0x1d646c4045189991fdfd24a66b192a294158b839a6ec121d740474bdacb3ab23"],"labels":["scammer"],"state":true,"first":5,"metadata":{"chain_id":56},"afterCreatedAtDate":"2023-04-03T15:01:33Z","beforeCreatedAtDate":"2023-04-03T15:10:45Z","after":{"pageToken":"29427820"}}}}'

More details on querying labels can be found in our Forta GraphQL API documentation.

What chains are supported?

  • Ethereum
  • BNB Chain
  • Polygon
  • Arbitrum
  • Optimism

False Positives

While the Scam Detector maintains high precision, it’s possible that it identifies a false positive. To address this risk, the Forta community manually verifies certain Scam Detector alerts within one business day. If a false positive is identified during the manual verification process, an FP alert will be emitted by the Scam Detector and the label will be removed. If you’re accessing the Labels API via the state endpoint, all labels are up to date and take into account the latest FP information.

Confidence Scores

The confidence score associated with a label is hard coded and based on the precision analysis performed by the Forta community or derived from the machine learning score. The hard coded score is updated on a monthly basis, and reflects the precision of the Scam Detector for a particular threat-category before manual verification.