NAV
bash python javascript

Introduction

AnChain.AI’s BEI API is an AI-powered, behavior-based intelligence that connects cryptocurrency wallet addresses and transactions to real-world entities, enabling your business to secure crypto assets, quantify risk, and remain KYC/AML compliant. Currently, our BEI API supports Bitcoin and Ethereum.

Below is the summary of BEI API Endpoints:

API Endpoint Description
Address Label Address category + Address entity
Address Risk Score Address category + Address entity + Risk score + Risk level
Address Risk Activity Address category + Address entity + Risk score Risk level + Suspicious activity
Transaction Risk Score Transaction Risk score + Risk level

Below is the explanation of the keys in BEI API response body:

Section Key Description Example
data is_address_valid Address verification result True
self Address attribute, including the labels
risk Address risk assessment
activity Address transaction activity summary
data.self category Address category label ransomware
detail Address category and entity label combination ransomware:WannaCry
data.risk score Address risk score 100
level Address risk level 4
data.activity suspicious_activity Summary of address suspicious transactions Sent money to exchange 1 time “ txn_hashes”: [“498719f8…”]

Authorization

To create an API key please sign up here.

Each API request should contain a valid API Key in the request query parameter in the form of

apikey=YOURAPIKEY

Rate Limiting

API rate limiting is dependent on our security configuration and your plan limit.

By signing up here, you get a 7-day free trial. Our free trials are limited to 1000 calls but include professional features.

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
}

Returns the address category and entity name. Address categories are listed below:
● hacker ● sanction ● ransomware
● scam ● blackmail ● darknet market
● malware ● bot ● abuse
● exchange ● mixer ● app wallet
● dapp ● wallet ● miner
● defi ● contract ● token
● forwarding agent ● pass-through ● whale
● unaffiliated

HTTP Request
GET /api/address_label

URL Parameters

Parameter Type Description
proto string blockchain protocol, current available options: btc, eth, xrp, egld, ltc, bch, zec, dash, bsv, bsc, tron, xvg
address string blockchain address
apikey string your BEI API key

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
}

AnChain.Ai risk scores are calculated by our patented machine learning model that comprehensively evaluates the risks associated with any addresses using our AI powered risk engine and proprietary user behavior analytics.. Our engine is powered by data from public sanction database lists, as well as the work of threat intelligence teams to identify scams and hacks. Other data sources include, but are not limited to data partners, internal research, and open source intel (OSINT). Our data goes through a rigorous vetting process before being implemented into our systems. Once updated, our machine learning engine continuously improves to provide scoring based on real time transaction behavior.

Risk score Risk level Description
0-29 1 Indicates a low risk. No unusual activity exists beyond the normal concern for known hacking activities, known viruses, or other malicious activity.
30-50 2 Indicates a general risk of illicit activity. The potential exists for malicious cyber activities, but no such activities or known exploits have been identified and no significant impact has occurred.
51-79 3 Indicates an elevated risk due to increased hacking, criminal, or other malicious cyber activity. At this level, the potential for exposure to illicit activity is elevated, but no direct exploitation has been observed.
80-100 4 Indicates an established history of past illicit activity and cybercrime engagement. At this level, addresses have been actively involved in illegal action, and are highly likely to see future involvement.

HTTP Request
GET /api/address_risk_score

URL Parameters

Parameter Type Description
proto string blockchain protocol, current available options: btc, eth, xrp, egld, ltc, bch, zec, dash, bsv, bsc, tron, xvg
address string blockchain address
apikey string your BEI API key

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
}

Returns address risk score and risk level with suspicious activity history. The suspicious activity consists of two parts, a plain and simple explanation to summarize the number of suspicious transactions the address had with a specific entity and the related evidence by transaction hash.

HTTP Request
GET /api/address_risk_activity

URL Parameters

Parameter Type Description
proto string blockchain protocol, current available options: btc, eth, xrp, egld, ltc, bch, zec, dash, bsv, bsc, tron, xvg
address string blockchain address
apikey string your BEI API key

Transaction Risk Score

var request = require('request')
request('https://staing-bei.anchainai.com/api/kyt/<proto>/<hash>/risk_score?apikey=<APIKEY>', function (error, response, body) {
})
curl -XGET 'https://staing-bei.anchainai.com/api/kyt/<proto>/<hash>/risk_score?apikey=<apikey>'
url = 'https://staing-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
    }
  }
}

Returns the risk score of the Transaction, and the label information of the associated addresses in the Transaction.

Using our AI-powered risk engine and proprietary user entity behavior analytics, our machine learning model comprehensively evaluates the risks associated with any Transaction.

HTTP Request
GET /api/kyt/<proto>/<hash>/risk_score

URL Parameters

Parameter Type Description
proto string blockchain protocol, current available options: eth
hash string transaction hash
apikey string your BEI API key

Response Fields

Fields Description
overview Overview of this transaction, including block number, timestamp, fee, etc.
risk
  • score: The risk score of this Transaction
  • level: Four risk levels: Low/Guarded/Elevated/Severe, refer to: Address-Risk-Score
  • direction: Determine the direction of the Risk Score, value scope: inputs / outputs
  • breakdown: Break down the score of various directions in this Transaction, value scope: inputs / outputs / internals
labels
  • inputs: Label information of all associated addresses in this Transaction Inputs
  • outputs: Label information of all associated addresses in this Transaction Outputs
  • internals: Label information of other addresses in this Transaction
NOTE: The Receiver address of a standard ERC20 Transfer will be labeled as outputs, and the Token address will be labeled as internals
transfers For number of all Transfers in the Transaction, the value scope varies per the protocols:
  • eth: Ethereum / ERC-20 / ERC-721 / ERC-1155

Errors

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