Response Overview

This section defines all parts of the API response

The Webacy APIs return detailed, powerful responses, enabling you to build your own functionalities if desired, or leverage our pre-built interpretations.

📘

Risk Dictionary

Webacy APIs return all risk flags enabling you to build your own risk systems and functionalities. You can access all potential returns here.

Consider this example response for the address: 0x8589427373D6D84E98730D7795D8f6f8731FDA16

{
  "count": 1,
  "medium": 0,
  "high": 1,
  "overallRisk": 100,
  "issues": [
    {
      "score": 28,
      "tags": [
        {
          "name": "Sanctioned",
          "description": "This is a Sanctioned Activity that has been found and reported by world authorities.",
          "type": "addressRisk",
          "severity": 10,
          "key": "sanctioned"
        },
        {
          "name": "Interacted with Sanctioned",
          "description": "This address has interacted with sanctioned activity.",
          "type": "addressRisk",
          "severity": 1,
          "key": "associated_sanctioned"
        },
        {
          "name": "Possible Blacklist",
          "description": "This address has been reported numerous times as dangerous. Proceed with caution.",
          "type": "addressRisk",
          "severity": 3,
          "key": "blacklist_doubt"
        },
        {
          "name": "Blackmail",
          "description": "This address has potentially been involved in illegal blackmail activity.",
          "type": "addressRisk",
          "severity": 6,
          "key": "blackmail_activities"
        },
        {
          "name": "Malicious Miner",
          "description": "This address belongs to a miner that has performed malicious mining and AMM activity.",
          "type": "addressRisk",
          "severity": 8,
          "key": "malicious_mining_activities"
        },
        {
          "name": "Insufficient Balance",
          "description": "This balance in this wallet or contract is below what is deemed necessary to pass Webacy's KYW (Know Your Wallet) criteria. This might indicate it is a new wallet.",
          "type": "noHistoryRisk",
          "severity": 0,
          "key": "insufficient_wallet_balance"
        }
      ],
      "categories": {
        "fraudulent_malicious": {
          "key": "fraudulent_malicious",
          "name": "Fraudulent/Malicious",
          "gradedDescription": {
            "high": "The smart contract/address in this transaction has been used in and is associated with confirmed fraud and malicious activity, or the asset is a known malicious token. Interacting with it may also cause your address to be marked as fraudulent.",
            "medium": "Elements of the smart contract in this transaction can be used a fraudulent and malicious fashion, or the address in this transaction has been involved in some risk activity.",
            "low": "Properties of this transaction indicate the possibility of nefarious activity, but we have not detected anything that would constitute elevated risk"
          },
          "tags": {
            "sanctioned": true,
            "blacklist_doubt": true,
            "blackmail_activities": true,
            "malicious_mining_activities": true
          }
        },
        "address_characteristics": {
          "key": "address_characteristics",
          "name": "Spam",
          "description": "This address may have risk factors related to address age, number of transactions, or balance. It may be newly created, or doesn't sufficiently pass Webacy's KYW (Know Your Wallet) criteria.",
          "tags": {
            "insufficient_wallet_balance": true
          }
        }
      },
      "riskScore": "High Risk"
    }
  ],
  "details": {},
  "isContract": false
}

count

count returns the total number of issues found in the return. It aggregates all low, medium, and high category issues.

👍

"low" issues

low risk issues are not typically shown in the return, and include flags in the "spam/sybil" category.

You can display "low" risk issues by passing a query param by setting show_low_risk to true

overallRisk

This field is a value 0 to 100. The value is non-linear, and is interpreted by Webacy systems based on all returned risk flags and factors. 0 is lowest risk, 100 is highest risk.

score

score is the sum of each severity value listed in the issues object in the response. The higher the score, the worse the risk.

name, description, type, severity, key

name: the name of the tagged issue. can be mapped to the dictionary.

description : the description of the tagged issue. can be found in the dictionary.

type : category of the issue

severity: A scale from 0 to 10. This is Webacy's interpretation based on a dynamic weighting algorithm. This visually depicts how much the risk of a particular tag affects the overall risk of that address.

• Example 1: vitalik.eth has two flags. The interacted with sanctioned and interacted with mixer tags are only a 1/10 severity. This is enough to give this address a threat risk score of "medium", since there is a slight risk that you interacting with him could land you on a watchlist, but tag weightings and overall threat risk are not linearly correlated.
• Example 2: Consider an actual sanctioned soviet contract. It will have a sanctioned tag with a severity of 10. Very high risk.

key: This maps to the risk category of each issue.

categories

This section provides another organization of the returned data based on tag categories and associated risks as booleans.

riskScore

This returns the Webacy interpretation of the risk level of the address. Possible values are Low Risk, Medium Risk, and High Risk. For more detailed mappings, check the "Risk Levels" page.

isContract

boolean returns true if the address is a contract and false if the address is not a contract.

error

If the incomplete-results flag is returned by our API in the error field, the endpoint should be hit again until the flag is no longer returned.

details

The details section may contain important information about an address.

Take this response for example:

{
    "count": 1,
    "medium": 0,
    "high": 0,
    "overallRisk": 0,
    "issues": [],
    "details": {
        "address_info": {
            "has_no_balance": false,
            "has_no_transactions": false,
            "time_verified": 1733847170893,
            "time_1st_tx": "2024-11-27T03:07:27.000Z",
            "transaction_count": 2,
            "balance": 0.004295,
            "is_spam_sns": false,
            "cex_info": {
                "is_cex": true,
                "cex_name": "okx",
                "cex_address_type": "cex",
                "cex_address_subtype": "deposit_wallet"
            }
        },
        "token_metadata_risk": {},
        "marketData": {}
    },
    "isContract": false
}

The "details" contains important and useful information about the address such as current balance, transaction history, centralized exchange attributions and much more.

📘

Did You Know

Our response provides enough flexibility for the data to be leveraged in all kinds of use cases. You can adjust how to use the information in the most valuable way for your platform and users.

❗️

Incomplete Results

Sometimes, the endpoint may return incomplete results (due to timeout issues, latency, throttling, etc.).

Be sure to check if the error field appears in the return. If the incomplete-results flag is returned in the error field, the results may only include partial or incomplete information. You'll need to re-ping the endpoint until the incomplete-results flag is no longer returned.