Introduction

Overview

What is BEI?

The Know Your Transaction and Know Your Wallet (KYT/KYW) Blockchain Ecosystem Intelligence (BEI) API is an AI/ML powered solution that allows developers, investigators and compliance officers to manage risk in Web3 applications/projects. When a wallet comes to your application for a transaction, how do we make sure this is not a sanctioned individual, hacker, scammer, or other bad actor?

Our API enables users to quickly and easily access accurate, live risk scores, attribution data, sanctions information, and more for the purposes of screening transactions, and meeting anti-money laundering and counter finance of terrorism (AML/CFT) compliance regulatory requirements from day one.

Why does this matter?

If your project touches crypto, you will one day fall under specific and often rigorous regulatory requirements in one or more jurisdictions. See more on that here. We don’t make the rules, but AnChain.AI’s BEI integration can help in taking the necessary action to remain compliant and avoid financial and reputational harm caused by adverse actions from regulators.

Sketchy Dapps with little customer vetting are no longer considered tolerable in this phase of web3 - wallet screening and transaction monitoring secures applications, protects your brand, and thereby facilitates growth.

All developers building in blockchain ecosystems should have the ability to proactively make sure their risk tools are in the right place. Sign up for free to get started.

API Endpoint Summary

The BEI API conforms to the RESTful architecture style. Each endpoint requires a different set of parameters formatted as an HTTP GET request. See the API endpoints section for a more detailed description of each endpoint.  

The information returned by the following BEI API endpoints is based on the collection of data gathered by blockchain ecosystem communities and AnChain.AI’s threat intelligence team:

• Address Label - category and entity associated with passed address
• Address Risk Score - address label, risk score and risk level associated with passed address
• Address Risk Activity - address label, risk score, risk level, and suspicious activity history associated with passed address
• Address Risk Attribution -detailed inflow and outflow transactions aggregated by category and then by entity
• Transaction Risk Score - risk score and risk level associated with passed transaction hash
• Dark Web Wallet - dark web sites associated with passed wallet address
• Dark Web Onion Site - wallets associated with passed dark web URL

Compliance

Don’t let anyone tell you differently - compliance IS sexy. That being said, there are some important bits to be aware of:

Financial Action Task Force (FATF)

The FATF (https://www.fatf-gafi.org/) is a global inter-governmental money laundering and terrorist financing watchdog and international compliance standards advisory organization. They’ve been around for a while (since 1989). The FATF makes recommendations to jurisdictions it oversees (which is most of the world) as to how they need to operate their AML/CFT procedures. In the Web3 realm, these recommendations help to prevent criminal and terrorist misuse of blockchain technologies.

While FATF can only recommend regulatory reforms and have no enforcement authority over their member nations, they call the shots in the background on the world stage of anti-financial crime policy and rulemaking. Member nations are strongly committed to implementation of the FATF recommendations, and regulatory and enforcement bodies worldwide do treat FATF’s guidance as quasi-law.  So much so, that when FATF issues a negative finding or even adds a country to a “disallow” list for regulatory failures, member nations react with swift and decisive action to cut economic and sometimes even diplomatic ties with such nations.

The FATF recommends that all virtual asset service providers (VASPs) build and scale with a risk based approach from day one.

VASPs

A VASP is defined by the FATF as a business that conducts one or more of the following actions on behalf of its clients:

• Exchange between virtual assets and fiat currencies;
• Exchange between one or more forms of virtual assets;
• Transfer of virtual assets;
• Safekeeping and/or administration or virtual assets or instruments enabling control over virtual assets;
• Participating in and provisioning of financial services related to an issuer’s offer and/or sale of a virtual asset;

This definition encompasses a range of crypto businesses, including exchanges, money services businesses (MSBs), ATM operators, wallet custodians, and hedge funds.

Most VASPs fall under the given definition. A crypto exchange, for example, Coinbase, is obviously a VASP, but the definition is starting to narrow. DeFi protocols all the way down to the smart contract level are being included under this umbrella of VASPs.

AML/CFT

Criminals are very creative in developing methods to launder money and finance terrorism. FATF attempts to monitor and report on criminal trends in order to develop recommendations to specifically address evolving money laundering and terrorist financing risks.

FATF requires originating VASPs to conduct due diligence on beneficiary VASPs before allowing a transaction.

What does this mean for your business?  The onus is on digital asset businesses to implement compliance solutions that alert for potentially suspicious activity both on and off the blockchain, enable the detection and prevention of crypto-related fraud, and effectively manage risk, in order to ensure that your product or service remains compliant with the latest regulations.

KYC

KYC means "know your customer". It refers to a financial institution's obligation to carry out certain identity and background checks on its clients before allowing them to use its product or platform. It is part of a broader set of measures that regulators around the world use to fight money laundering.

In other words, it stops bad actors from hiding the illicit source of their money behind legitimate financial activity.

Risk Engine

Risk Scores

• Our risk scores reflect the live state of the blockchain, and responds within minutes of new sanctions, unusual wallet behaviors, or criminal activity in addresses multiple transactions removed from the entity/wallet of interest.
• Our risk scores utilize a combination of open-source intelligence, in-house threat intelligence, proximity to known bad actor wallets, exposure to illicitly acquired funds, and patterns of transaction behavior to create a holistic representation of a wallet/transaction’s risk.
• Our AI/ML capabilities allow the risk scores to take into consideration patterns of transaction behavior as well as illicit activity far upstream of a given transaction/wallet, allowing them to update both more quickly, and to represent a higher degree of accuracy. 

Data Sources

• Our engine is powered by a variety of data sources including but not limited to:

• Public Sanction Databases: US OFAC, United Nations, European Union, Canadian, UK, Switzerland and Australian sanctions lists
• Blockchain ledgers
• Internal research
• Work of threat intel teams
• Data partners
• Open Source Intelligence (OSINT) - the collection and analysis of data gathered from open sources to produce actionable intelligence

• Our data goes through a rigorous vetting process before being implemented into our systems.
• AnChain.AI’s threat intelligence team conducts 24/7 monitoring of on-chain, social media, and dark-web activities in order to quickly and accurately flag emerging threats.

Community and Support

Quickstart

Check out our Github for use case examples.

Social

For questions or suggestions, please reach out to us on our main site, Twitter, or LinkedIn

Other Useful Resources

Investigations or forensics team? Be sure to check out our compliance, investigations, and security and operations tool, CISO.

Are you a blockchain researcher, analyst, or vigilante? Report suspicious activity using our community reporting tool, Web3Guard. 

In addition, we provide self-paced certification courses through AnChain.AI University.

Security and Privacy

• Data privacy is of the upmost importance to us. We do not retain user information for any internal analytics. See our privacy policy for more information.
• AnChain.AI follows industry best-practices in regards to securing data and transport-level encryption.

Authorization

Authorization is the process of determining whether an authenticated user is allowed to do certain actions or access certain data - this is at the core of API security.

Usage of the BEI API requires an AnChain.AI distributed API key, which can be acquired here. Once you obtain your API key, you can make requests to the BEI API.

API Endpoints

Address Label

var request = require('request')
request('https://bei.anchainai.com/api/address_label?proto=<PROTO>&address=<ADDR>&apikey=<APIKEY>', function (error, response, body) {
})

import requests

url = 'https://bei.anchainai.com/api/address_label'
payload = {
  'proto': '<PROTO>',
  'address': '<ADDR>',
  'apikey': '<APIKEY>'
}
res = requests.get(url=url, params=payload)

curl -XGET 'https://bei.anchainai.com/api/address_label?proto=<PROTO>&address=<ADDR>&apikey=<APIKEY>'

The above command returns JSON structured like this:

{
    "data": {
        "12t9YDPgwueZ9NyMgw519p7AA8isjr6SMw": {
            "is_address_valid": true,
            "self": {
                "category": [
                    "ransomware",
                    "abuse"
                ],
                "detail": [
                    "ransomware:WannaCry"
                ]
            }
        }
    },
    "err_msg": "",
    "status": 200
}

Address Risk Score

var request = require('request')
request('https://bei.anchainai.com/api/address_risk_score?proto=<PROTO>&address=<ADDR>&apikey=<APIKEY>', function (error, response, body) {
})

import requests

url = 'https://bei.anchainai.com/api/address_risk_score'
payload = {
  'proto': '<PROTO>',
  'address': '<ADDR>',
  'apikey': '<APIKEY>'
}
res = requests.get(url=url, params=payload)

curl -XGET 'https://bei.anchainai.com/api/address_risk_score?proto=<PROTO>&address=<ADDR>&apikey=<APIKEY>' 

The above command returns JSON structured like this:

{
    "data": {
        "12t9YDPgwueZ9NyMgw519p7AA8isjr6SMw": {
            "is_address_valid": true,
            "risk": {
                "level": 4,
                "score": 100,
                "verdict_time": 1605920588
            },
            "self": {
                "category": [
                    "abuse",
                    "ransomware"
                ],
                "detail": [
                    "ransomware:WannaCry"
                ]
            }
        }
    },
    "err_msg": "",
    "status": 200
}

Address Risk Activity

var request = require('request')
request('https://bei.anchainai.com/api/address_risk_activity?proto=<PROTO>&address=<ADDR>&apikey=<APIKEY>', function (error, response, body) {
})

url = 'https://bei.anchainai.com/api/address_risk_activity'
payload = {
  'proto': '<PROTO>',
  'address': '<ADDR>',
  'apikey': '<APIKEY>'
}
res = requests.get(url=url, params=payload)

curl -XGET 'https://bei.anchainai.com/api/address_risk_activity?proto=<PROTO>&address=<ADDR>&apikey=<APIKEY>'

The above command returns JSON structured like this:

{
    "data": {
        "12t9YDPgwueZ9NyMgw519p7AA8isjr6SMw": {
            "activity": {
                "suspicious_activity": [
                    {
                        "aggr_type": "entity",
                        "category": "exchange",
                        "description": "Received money from exchange:Zaif wallet(s) 1 time",
                        "entity": "Zaif",
                        "txn_cnt": 1,
                        "txn_direct": 1,
                        "txn_hashes": [
                            "a3b15590878dc216c7c5b9b5bc109a1e07caab93928920b4bb5b82a7e98266f0"
                        ],
                        "txn_hashes_detail": [
                            {
                                "suspicious_address": "1CZV316KMt9DR9kWFNjed8s5AB6RGUPmAr",
                                "txn_hash": "a3b15590878dc216c7c5b9b5bc109a1e07caab93928920b4bb5b82a7e98266f0",
                                "txn_timestamp": 1494864282,
                                "value": 0.01290216
                            }
                        ],
                        "txn_vol": 0.01290216
                    },
                    {
                        "aggr_type": "entity",
                        "category": "unaffiliated",
                        "description": "Sent money to unaffiliated:unaffiliated wallet(s) 2 times",
                        "entity": "unaffiliated",
                        "txn_cnt": 2,
                        "txn_direct": 0,
                        "txn_hashes": [
                            "409803bb5e124fd028c0482027c7722e84ce55b78204b279d3a44aba5e7c1698",
                            "35e5d5fe8c8128cfa6884f56be5817e4138c58c91b79d78d3e78a8d365b9d8a7"
                        ],
                        "txn_hashes_detail": [
                            {
                                "suspicious_address": "16dfTuSx4f78eQ81PzTgBtBDyZ7QhNZ8Vy",
                                "txn_hash": "35e5d5fe8c8128cfa6884f56be5817e4138c58c91b79d78d3e78a8d365b9d8a7",
                                "txn_timestamp": 1501735294,
                                "value": 9.02796322
                            },
                            {
                                "suspicious_address": "1JC41YHmjKEcW1rLH6pmMWEFHkoNwSmhnC",
                                "txn_hash": "409803bb5e124fd028c0482027c7722e84ce55b78204b279d3a44aba5e7c1698",
                                "txn_timestamp": 1501734500,
                                "value": 0.01227173
                            },
                            {
                                "suspicious_address": "1FQQ86tMuvhQ4Ruyggbb8j7iaNfUZ69gpY",
                                "txn_hash": "409803bb5e124fd028c0482027c7722e84ce55b78204b279d3a44aba5e7c1698",
                                "txn_timestamp": 1501734500,
                                "value": 8.71529348
                            }
                        ],
                        "txn_vol": 9.02796322
                    }
                ],
                "suspicious_activity_declare": "Suspicious Activity is summarized based on most recent 2000 suspicious transactions",
                "verdict_time": 1509494400
            },
            "is_address_valid": true,
            "risk": {
                "level": 4,
                "score": 100,
                "verdict_time": 1509494400
            },
            "self": {
                "category": [
                    "abuse",
                    "ransomware"
                ],
                "detail": [
                    "ransomware:WannaCry"
                ]
            }
        }
    },
    "err_msg": "",
    "status": 200
}

Address Risk Attribution

var request = require('request')
request('https://bei.anchainai.com/api/address_risk_attribution?apikey=<APIKEY>&proto=<PROTO>&address=<ADDRESS>', function (error, response, body) {
})

curl -XGET 'https://bei.anchainai.com/api/address_risk_attribution?apikey=<apikey>&proto=<PROTO>&address=<ADDRESS>'

url = 'https://bei.anchainai.com/api/address_risk_attribution'
payload = {
  'apikey': '<APIKEY>',
  'proto':'<PROTO>',
  'address':'<ADDRESS>'
}
res = requests.get(url=url, params=payload)

The above command returns JSON structured like this:

{
    "status": 200,
    "err_msg": "",
    "data": {
        "attribution": {
            "txns_total": 480000,
            "inbound": {
                "value_usd": 9410766937.4572,
                "count": 369,
                "categories": {
                    "exchange": {
                        "value_usd": 9410725157.48572,
                        "count": 307,
                        "entities": {
                            "Binance": {
                                "value_usd": 9410714516.809587,
                                "count": 303,
                                "value_usd_percent": 99.999887
                            },
                            "Bitkub Hot Wallet": {
                                "value_usd": 10540.4817708306,
                                "count": 1,
                                "value_usd_percent": 0.000112
                            },
                        
                        },
                        "value_usd_percent": 99.999556
                    },
                    "unaffiliated": {
                        "value_usd": 41779.97148961006,
                        "count": 62,
                        "entities": {
                            "unaffiliated": {
                                "value_usd": 41779.97148961006,
                                "count": 62,
                                "value_usd_percent": 100.0
                            }
                        },
                        "value_usd_percent": 0.000444
                    }
                }
            },
            "outbound": {
                "value_usd": 7860663971.009165,
                "count": 10000,
                "categories": {
                    "unaffiliated": {
                        "value_usd": 5761055215.71709,
                        "count": 7738,
                        "entities": {
                            "unaffiliated": {
                                "value_usd": 5761055215.71709,
                                "count": 7738,
                                "value_usd_percent": 100.0
                            }
                        },
                        "value_usd_percent": 73.289677
                    },
                    "exchange": {
                        "value_usd": 1581349564.6829941,
                        "count": 1998,
                        "entities": {
                            "OKX": {
                                "value_usd": 278429787.53651196,
                                "count": 424,
                                "value_usd_percent": 17.607099
                            },
                            "Bitfinex": {
                                "value_usd": 207310173.97043434,
                                "count": 194,
                                "value_usd_percent": 13.109699
                            } 
                        },
                        "value_usd_percent": 20.117252
                    },
                  
                }
            }
        },
        "txns_detail": {
            "inbound": [
                {
                    "hash": "0x1ef614997610c9b8ddf7f5f5c7349cc7944b5f48a98f4300733300354e4a6618",
                    "peer": "0x28c6c06298d514db089934071355e5743bf21d60",
                    "timestamp": 1707471635,
                    "token_address": "eth",
                    "value": 36927.9817959,
                    "value_usd": 138504330.1260535
                },
                {
                    "hash": "0xbb4109ed1b5e8d2a67feac462bf0589417fa30c4f75d062b4ce065786ad4bcde",
                    "peer": "0x28c6c06298d514db089934071355e5743bf21d60",
                    "timestamp": 1709025647,
                    "token_address": "eth",
                    "value": 30668.3067817,
                    "value_usd": 115026413.04300229
                },
            
            ],
       
        },
        "labels_mapping": {
            "0x77f7b398a23ef4cab31dd5503fd8446c4480c70b": {
                "is_address_valid": true,
                "self": {
                    "category": [
                        "exchange"
                    ],
                    "detail": [
                        "exchange:Bitfinex"
                    ]
                }
            },
            "0x572c3841fc73ea24a2768c7dca3a927d6115ed83": {
                "is_address_valid": true,
                "self": {
                    "category": [
                        "exchange"
                    ],
                    "detail": [
                        "exchange:OKEx"
                    ]
                }
            },
        },
        "tokens_mapping": {
            "0x0391d2021f89dc339f60fff84546ea23e337750f": {
                "decimals": 18,
                "logo": "https://s3.us-west-2.amazonaws.com/public.anchainai/bei/logo/eth/0x0391d2021f89dc339f60fff84546ea23e337750f.png",
                "name": "BarnBridge Governance Token",
                "price_usd": 3.22,
                "symbol": "BOND",
                "top_number": 2,
                "type": "ERC-20"
            },
            "eth": {
                "decimals": 18,
                "logo": "https://s3.us-west-2.amazonaws.com/public.anchainai/bei/logo/eth/eth.png",
                "name": "Ethereum",
                "price_usd": 3750.660702,
                "symbol": "ETH",
                "top_number": 1,
                "type": ""
            }
        }
    }
}

Transaction Risk Score

var request = require('request')
request('https://bei.anchainai.com/api/kyt/<proto>/<hash>/risk_score?apikey=<APIKEY>', function (error, response, body) {
})

curl -XGET 'https://bei.anchainai.com/api/kyt/<proto>/<hash>/risk_score?apikey=<apikey>'

url = 'https://bei.anchainai.com/api/kyt/<proto>/<hash>/risk_score'
payload = {
  'apikey': '<APIKEY>'
}
res = requests.get(url=url, params=payload)

The above command returns JSON structured like this:

{
  "status": 200,
  "err_msg": "",
  "data": {
    "overview": {
      "blockno": 7146988,
      "timestamp": "2019-01-30 03:29:31 UTC",
      "fee": 0.0004
    },
    "risk": {
      "score": 100,
      "level": "Severe",
      "direction": "outputs",
      "breakdown": {
        "inputs": 50,
        "outputs": 100,
        "internals": 50
      }
    },
    "labels": {
      "inputs": {
        "0xc67813f468975099b09dd76b55ae6011a9f359ca": {
          "category": [
            "unaffiliated"
          ],
          "detail": [
            
          ]
        }
      },
      "outputs": {
        "0x4ac6307a85d83962503f86457de9c331a6926f48": {
          "category": [
            "hacker"
          ],
          "detail": [
            "hacker:fake_phishing"
          ]
        }
      },
      "internals": {
        "0x7297862b9670ff015192799cc849726c88bf1d77": {
          "category": [
            "unaffiliated"
          ],
          "detail": [
            
          ]
        }
      }
    },
    "transfers": {
      "ERC-20": 1
    }
  }
}

Dark Web Wallet

var request = require('request')
request('https://bei.anchainai.com/api/cdi/indicator?apikey=<CDI-APIKEY>&address=<ADDR>&proto=<PROTO>&type=<TYPE>', function (error, response, body) {
})

curl -XGET 'https://bei.anchainai.com/api/cdi/indicator?apikey=<CDI-APIKEY>&address=<ADDR>&proto=<PROTO>&type=<TYPE>'

url = 'https://bei.anchainai.com/api/cdi/indicator'
payload = {
  'apikey': '<CDI-APIKEY>',    
  'address': '<ADDR>',
  'proto': '<PROTO>',
  'type': '<TYPE>',
}
res = requests.get(url=url, params=payload)

The above command returns JSON structured like this:

{
  "status": 200,
  "err_msg": "",
  "data": [
    {
      "btc": [
        {
          "indicator": "3QmaJdWqQKZszSbriB3LVwLcQHF59tMbGh",
          "reference": [
            "cheenazap345z6a7.onion",
            "cheenahrz5kyrefo4s4x22yc4o5zi662o6sjsbtxwod6axybyqbldxyd.onion"
          ]
        }
      ],
      "doge": [
        {
          "indicator": "DAyLTAuMTQzLTAuMDA5LTAuMjE5LTAuMDQ",
          "reference": [
            "cheenazap345z6a7.onion",
            "cheenahrz5kyrefo4s4x22yc4o5zi662o6sjsbtxwod6axybyqbldxyd.onion"
          ]
        }       
      ],
      "email": [
        {
          "indicator": "cheena@cheena.net",
          "reference": [
            "cheenazap345z6a7.onion",
            "cheenahrz5kyrefo4s4x22yc4o5zi662o6sjsbtxwod6axybyqbldxyd.onion"
          ]
        }
      ],
      "javascript": [
        {
          "indicator": "http://cheenazap345z6a7.onion/app.js?b95fafe537c8474d9172",
          "reference": [
            "cheenazap345z6a7.onion"
          ]
        }
      ],
      "links": [
        {
          "indicator": "cheenazap345z6a7.onion",
          "reference": [
            "cheenazap345z6a7.onion",
            "cheenahrz5kyrefo4s4x22yc4o5zi662o6sjsbtxwod6axybyqbldxyd.onion"
          ]
        }
      ],
      "onion": [
        "cheenazap345z6a7.onion",
        "cheenahrz5kyrefo4s4x22yc4o5zi662o6sjsbtxwod6axybyqbldxyd.onion"
      ],
      "xmr": [
        {
          "indicator": "44C9RkTNeaFe2nJa8jnw22iQfYsKqgXuWigip4X2w3eFJEigZXNR61pi5kj2JKt7mJBu5qsvED7NGaFG8UnQPQkUDUoW9Yx",
          "reference": [
            "cheenazap345z6a7.onion",
            "cheenahrz5kyrefo4s4x22yc4o5zi662o6sjsbtxwod6axybyqbldxyd.onion"
          ]
        }
      ]
    }
  ]
}

Dark Web Onion Site

var request = require('request')
request('https://bei.anchainai.com/api/cdi/oniondetails?apikey=<CDI-APIKEY>&onion=<ONION-SITE-URL>&type=<TYPE>', function (error, response, body) {
})

curl -XGET 'https://bei.anchainai.com/api/cdi/oniondetails?apikey=<CDI-APIKEY>&onion=<ONION-SITE-URL>&type=<TYPE>'

url = 'https://bei.anchainai.com/api/cdi/oniondetails'
payload = {
  'apikey': '<CDI-APIKEY>',    
  'onion': '<ONION-SITE-URL>',   
  'type': '<TYPE>',
}
res = requests.get(url=url, params=payload)

The above command returns JSON structured like this:

{
  "status": 200,
  "err_msg": "",
  "data": [
    {
      "btc": [
        "18hBL7uiunfZmSYAgKg4zeo8nhBnBSzqAC",
        "3QmaJdWqQKZszSbriB3LVwLcQHF59tMbGh"
      ],
      "doge": [
        "DAyLTAuMTQzLTAuMDA5LTAuMjE5LTAuMDQ",
        "DAgMi45MjQtMS4zNzcgMi45MjQtMy4xMjN",
        "DAtMi4zNzUgMC4xMjgtNC43MjkgMC4zNzE",
        "DAuMTE1LTAuMzQ4LDAuMTJjLTAuMDY5LDA",
        "DUgMTAuMTgzLTE4LjkwNWgxMy44MzJ2Mjk",
        "DQuNywxMC41LDEwLjUsMTAuNWgxNTcuN2M"
      ],
      "email": [
        "cheena@cheena.net",
        "cheena@xmpp.is"
      ],
      "javascript": [
        "http://cheenazap345z6a7.onion/app.js?b95fafe537c8474d9172"
      ],
      "links": [
        "cheenazap345z6a7.onion"
      ],
      "onion": "cheenazap345z6a7.onion",
      "xmr": [
        "44C9RkTNeaFe2nJa8jnw22iQfYsKqgXuWigip4X2w3eFJEigZXNR61pi5kj2JKt7mJBu5qsvED7NGaFG8UnQPQkUDUoW9Yx",
        "40MjYsMy4zNzRjMCwwLTAuMTQ5LDAuMTE1LTAuMzQ4LDAuMTJjLTAuMDY5LDAuMDAyLTAuMTQzLTAuMDA5LTAuMjE5LTAuM"
      ]
    }
  ]
}

Errors

When an error is encountered, you will receive an HTTP status code along with a message and error code in the body of your query response. We use the following status codes for errors:

Code	Meaning
200	Information is found and returned properly
400	Invalid API key or missing parameters or rate-limited
403	Too many addresses in bulk input
404	Label not found
500	Internal server error