NAV
cURL NodeJS Python Go PHP Ruby

Introduction

Welcome to the Bitrace API! You can use our API to access Bitrace AML API endpoints, which comprise a comprehensive suite of blockchain and crypto compliance tools to help you equip you with real-time risk detection capabilities, enabling scrutiny of crypto transactions, wallet addresses, and crypto tokens with precision and efficiency.

Quickstart Guide

Getting Started

  1. Sign in to the Bitrace AML.
  2. Click the menu API > Settings, it will require to verify your identigy by email at first time.
  3. If an API Key is present, copy it. Alternatively, click Generate API Key and copy it. Use the API Key to authenticate the Entities endpoints
  4. Configure the IP whitelist before access APIs

Base URL

The base URL of the API is:

Authentication

# With shell, you can just pass the correct header with each request
curl -X GET ${API_URL} \
    --header "X-Access-Key: ${YOUR_API_KEY}" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json"

import axios from 'axios';

const response = await axios.get('${API_URL}', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

import requests

url = "${API_URL}"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "${API_URL}", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-Access-Key", "${YOUR_API_KEY}")
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('${API_URL}', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'         => 'application/json',
        'Content-Type' => 'application/json'
    ]
]);

require 'net/http'

uri = URI('${API_URL}')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

Your API key is the unique identifier used for accessing Bitrace AML API endpoints.

Detrust expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-Access-Key: ${YOUR_API_KEY}

Rate Limit

We have implemented rate limits on API calls to prevent overloading. This is to ensure the best possible processing speed, response time, and provide additional security to Bitrace AML APIs products and the fetched data.

Different access limits apply to users:

Playground

You can access the APIs via Postman Collection

Know Your Address（KYA)

KYA Quickstart

The KYA (Know Your Address) API is a risk assessment tool that allows crypto businesses and financial institutions to comprehensively assess risks associated with on-chain all addresses - wallets, tokens, smart contracts and more.

KYA Supported Chains

Chains are supported in all KYA APIs,

Chain Name Currency Chain ID Code
Ethereum ETH 1 ethereum
BNB Smart Chain BSC 56 bsc
TRON TRON N/A tron
Bitcoin BTC N/A btc

Chains are supported in the entity and risk KYA APIs only,

Chain Name Currency Chain ID Code
Polygon POL 137 polygon
Arbitrum One ARB 42161 arbitrum
OP Mainnet OP 10 optimism
Avalanche AVAX 43114 avalanche

KYA Risk Detection Model

Detrust leverages advanced machine learning and multi-model algorithms to precisely detect different address labels. This enables a thorough scanning of on-chain EOA addresses across five key dimensions, namely suspicious transactions, blocklist addresses, associated blocklist entities, high-risk identities, and entity risks.

How risk is determined

Risk assessments are categorized as Severe, High, Medium, or Low scores. The scoring process for an address involves two factors:

Each entity category has an initial risk assessment and an initial exposure threshold expressed as a percentage of total exposure to that category. If an address meets two or more criteria, the score assigned to the address is determined by the higher of the two scores.

For example, address 0x123abc may have an entity category of Darknet Market (constituting a score of High) and have 20% direct exposure to a sanctioned entity (constituting a risk score of Severe). Since the exposure score is the greater of the two, the address 0x123abc will have a Severe score. We calculate exposure values using both directions (sent and received).

KYA Risk Score

Risk scoring provides an overall assessment of the risk level associated with an address, with higher scores indicating higher risk.

The main factors influencing the score include:

These factors are combined with the credibility of data sources and calculated through a model to produce an overall risk assessment value.

Severity Score
Severe 80 and above
High 50 to 80
Medium 20 to 50
Low 0 to 20

The risk score is primarily based on the relevance of risk intelligence, with address transaction behavior characteristics serving as secondary factors.

In some cases, the score may exhibit a certain delay.

The score may not be applicable to addresses of certain institutions.

KYA API

Retrieve Entity

getAddressEntity - This endpoint retrieves entity by given address.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/entities?address=TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc&network=tron' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

const response = await axios.get('/api/v1/tracker/kya/entities', {
  params: {
    'address': 'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc',
    'network': 'tron'
  },
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

import requests

url = "${API_BASE_URL}/api/v1/tracker/kya/entities"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

params = {
    'address': 'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc',
    'network': 'tron',
}

response = requests.get(url, params=params, headers=headers)

print(response.text)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "${API_BASE_URL}/api/v1/tracker/kya/entities?address=TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc&network=tron", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-Access-Key", "${YOUR_API_KEY}")
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('${API_BASE_URL}' . '/api/v1/tracker/kya/entities', [
    'query' => [
        'address' => 'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc',
        'network' => 'tron'
    ],
    'headers' => [
        'X-Access-Key'  => '${YOUR_API_KEY}',
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
]);

require 'net/http'

uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/entities')
params = {
  :address => 'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc',
  :network => 'tron',
}
uri.query = URI.encode_www_form(params)

req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

GET /api/v1/tracker/kya/entities

Query Parameters
Parameter Type Required Description
address string true The address that you want to retrieve a entity for.
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1714052957650,
    "address":"TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
    "network":"tron",
    "whitelist": false,
    "contract": false,
    "entity":{
      "entityName":"Bybit User",
      "entityCode":"bybit-user",
      "entityCategory":"Exchange",
      "entityCategoryCode":"exchange"
    }
  }
}

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "time":1745078888084,
    "address":"0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "network":"ethereum",
    "whitelist":false,
    "intelligenceEntities":[
      {
        "entityName":"Gitcoin Grantee",
        "entityCode":"gitcoin-grantee",
        "entityCategory":"Community",
        "entityCategoryCode":"community"
      },
      {
        "entityName":"Tornado.cash Deposit",
        "entityCode":"tornado-cash-from",
        "entityCategory":"Mixer",
        "entityCategoryCode":"mix"
      },
      {
        "entityName":"Tornado.cash Withdrawal",
        "entityCode":"tornado-cash-to",
        "entityCategory":"Mixer",
        "entityCategoryCode":"mix"
      }
    ],
    "contract":false
  },
  "msg":"SUCCESS"
}
Property Type Description
time number the response timestamp from server
address string The address that you want to retrieve a entity for.
network string The supported chainns short name. Values can be,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains
whitelist boolean The whitelisted addresses are intended to represent official addresses such as exchanges, which are not suitable for risk assessment due to the complex composition of their revenue funds.
contract boolean Whether is a contract address or not.
entity object An object that contains any available entity information for the provided address. If the object returns null, the address has not any entity information. More detail at Schema - Entity
entity.entityName string The name of the identified entity.
entity.entityCode string The code of the identified entity.
entity.entityCategory string The category of the identified entity
entity.entityCategoryCode string The category code of the identified entity
intelligenceEntities array or null An object arrya that contains any available intelligence entities. Same schema as Schema - Entity
intelligenceEntities[].entityName string The name of the identified entity.
intelligenceEntities[].entityCode string The code of the identified entity.
intelligenceEntities[].entityCategory string The category of the identified entity
intelligenceEntities[].entityCategoryCode string The category code of the identified entity

Retrieve Bulk Entities

listAddressEntities - This endpoint retrieves bulk entities by given addresses.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/entities" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "addresses": [
          "TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc"
      ],
      "network": "tron"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

var payload = {
  "addresses": [
    "TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc"
  ],
  "network": "tron"
}

const response = await axios.post('/api/v1/tracker/kya/entities', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = baseUrl + "/api/v1/tracker/kya/entities"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'addresses': [
      'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc'
    ],
    'network': 'tron',
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kya/entities"
  method := "POST"

  payload := strings.NewReader(`{
    "addresses": [
        "TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc"
    ],
    "network": "tron"
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kya/entities', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'addresses' => [
            'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc'
        ],
        'network' => 'tron'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/entities')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'addresses' => [
    'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc'
  ],
  'network' => 'tron'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kya/entities

Request Body Schame
Parameter Type Required Description
addresses string[] true The address array that you want to retrieve entities for.
And the array limit size is 100
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":[
    {
      "time":1714053026890,
      "address":"TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
      "network":"tron",
      "whitelist": false,
      "contract": false,
      "entity":{
        "entityName":"Bybit User",
        "entityCode":"bybit-user",
        "entityCategory":"Exchange",
        "entityCategoryCode":"exchange"
      }
    }
  ]
}
Property Type Description
time number the response timestamp from server
address string The address that you want to retrieve a entity for.
network string The supported chainns short name. Values can be,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains
whitelist boolean The whitelisted addresses are intended to represent official addresses such as exchanges, which are not suitable for risk assessment due to the complex composition of their revenue funds.
contract boolean Whether is a contract address or not.
entity object An object that contains any available entity information for the provided address. If the object returns null, the address has not any entity information. More detail at Schema - Entity
entity.entityName string The name of the identified entity.
entity.entityCode string The code of the identified entity.
entity.entityCategory string The category of the identified entity
entity.entityCategoryCode string The category code of the identified entity
intelligenceEntities array or null An object arrya that contains any available intelligence entities. Same schema as Schema - Entity
intelligenceEntities[].entityName string The name of the identified entity.
intelligenceEntities[].entityCode string The code of the identified entity.
intelligenceEntities[].entityCategory string The category of the identified entity
intelligenceEntities[].entityCategoryCode string The category code of the identified entity

Retrieve Risk Assessment

getAddressRisk - This endpoint retrieves risk by given address.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/risks?address=TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n&network=tron' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

const response = await axios.get('/api/v1/tracker/kya/risks', {
  params: {
    'address': 'TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n',
    'network': 'tron'
  },
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

import requests

url = "${API_BASE_URL}/api/v1/tracker/kya/risks"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

params = {
    'address': 'TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n',
    'network': 'tron',
}

response = requests.get(url, params=params, headers=headers)

print(response.text)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "${API_BASE_URL}/api/v1/tracker/kya/risks?address=TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n&network=tron", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-Access-Key", "${YOUR_API_KEY}")
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('${API_BASE_URL}' . '/api/v1/tracker/kya/risks', [
    'query' => [
        'address' => 'TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n',
        'network' => 'tron'
    ],
    'headers' => [
        'X-Access-Key'  => '${YOUR_API_KEY}',
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
]);

require 'net/http'

uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/risks')
params = {
  :address => 'TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n',
  :network => 'tron',
}
uri.query = URI.encode_www_form(params)

req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

GET /api/v1/tracker/kya/risks

Query Parameters
Parameter Type Required Description
address string true The address that you want to retrieve a entity for.
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1726110279193,
    "address":"TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n",
    "network":"tron",
    "whitelist": false,
    "risks":[
      {
        "riskLevel":"generally-high",
        "riskType":"launder-money",
        "riskSource":"Bitrace"
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "riskSource":"Bitrace"
      },
      {
        "riskLevel":"high",
        "riskType":"online-gambling",
        "riskSource":"Bitrace"
      }
    ]
  }
}

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1714100534337,
    "address":"TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
    "network":"tron",
    "whitelist": false,
    "risks":null
  }
}

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1726107623669,
    "address":"13mnk8SvDGqsQTHbiGiHBXqtaQCUKfcsnP",
    "network":"btc",
    "whitelist": false,
    "risks":[
      {
        "riskLevel":"high",
        "riskType":"sanction",
        "riskSource":"Bitrace"
      }
    ]
  }
}
Property Type Description
time number the response timestamp from server
address string The address that you want to retrieve a risk for.
network string The supported chainns short name. Values can be,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains
whitelist boolean The whitelisted addresses are intended to represent official addresses such as exchanges, which are not suitable for risk assessment due to the complex composition of their revenue funds.
contract boolean Whether is a contract address or not.
risks array or null An object array that contains any available risk information for the provided address. If the object returns null, the address has not any risk information.
risks[].riskLevel string The level of the risk.
risks[].riskType string The type of the risk.
risks[].riskSource string The source of the risk.

Retrieve Bulk Risk Assessments

listAddressRisks - This endpoint retrieves bulk risks by given addresses.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/risks" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "addresses": [
        "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
        "THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
        "TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
        "TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk"
      ],
      "network": "tron"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

var payload = {
  "addresses": [
    "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
    "THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
    "TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
    "TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
    "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
    "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk"
  ],
  "network": "tron"
}

const response = await axios.post('/api/v1/tracker/kya/risks', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = baseUrl + "/api/v1/tracker/kya/risks"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'addresses': [
      'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
      'THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ',
      'TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5',
      'TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo',
      'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk',
      'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk'
    ],
    'network': 'tron',
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kya/risks"
  method := "POST"

  payload := strings.NewReader(`{
    "addresses": [
        "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
        "THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
        "TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
        "TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk"
    ],
    "network": "tron"
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kya/risks', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'addresses' => [
            'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
            'THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ',
            'TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5',
            'TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo',
            'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk',
            'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk'
        ],
        'network' => 'tron'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/risks')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'addresses' => [
    'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ',
    'TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5',
    'TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo',
    'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk',
    'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk'
  ],
  'network' => 'tron'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kya/risks

Request Body Schame
Parameter Type Required Description
addresses string[] true The address array that you want to retrieve entities for.
And the array limit size is 100
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":[
    {
      "time":1726107965915,
      "address":"TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
      "network":"tron",
      "whitelist": false,
      "risks":null
    },
    {
      "time":1726107965915,
      "address":"THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
      "network":"tron",
      "whitelist": false,
      "risks":null
    },
    {
      "time":1726107965915,
      "address":"TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
      "network":"tron",
      "whitelist": false,
      "risks":[
        {
          "riskLevel":"generally-high",
          "riskType":"online-gambling",
          "riskSource":"Bitrace"
        }
      ]
    },
    {
      "time":1726107965915,
      "address":"TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
      "network":"tron",
      "whitelist": false,
      "risks":[
        {
          "riskLevel":"high",
          "riskType":"online-gambling",
          "riskSource":"Bitrace"
        },
        {
          "riskLevel":"high",
          "riskType":"black-gray-goods",
          "riskSource":"Bitrace"
        }
      ]
    },
    {
      "time":1726107965915,
      "address":"TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
      "network":"tron",
      "whitelist": false,
      "risks":[
        {
          "riskLevel":"high",
          "riskType":"black-gray-goods",
          "riskSource":"Bitrace"
        }
      ]
    },
    {
      "time":1726107965915,
      "address":"TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
      "network":"tron",
      "whitelist": false,
      "risks":[
        {
          "riskLevel":"high",
          "riskType":"black-gray-goods",
          "riskSource":"Bitrace"
        }
      ]
    }
  ]
}
Property Type Description
time number the response timestamp from server
address string The address that you want to retrieve a entity for.
network string The supported chainns short name. Values can be,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains
whitelist boolean The whitelisted addresses are intended to represent official addresses such as exchanges, which are not suitable for risk assessment due to the complex composition of their revenue funds.
contract boolean Whether is a contract address or not.
risks array or null An object array that contains any available risk information for the provided address. If the object returns null, the address has not any risk information.
risks[].riskLevel string The level of the risk.
risks[].riskType string The type of the risk.
risks[].riskSource string The source of the risk.

Retrieve Entity and Risk Assessment

getAddressEntityAndRisk - This endpoint retrieves entity and risk by given address.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/entities-risks?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

const response = await axios.get('/api/v1/tracker/kya/entities-risks', {
  params: {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron'
  },
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

import requests

url = "${API_BASE_URL}/api/v1/tracker/kya/entities-risks"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

params = {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron',
}

response = requests.get(url, params=params, headers=headers)

print(response.text)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "${API_BASE_URL}/api/v1/tracker/kya/entities-risks?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-Access-Key", "${YOUR_API_KEY}")
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('${API_BASE_URL}' . '/api/v1/tracker/kya/entities-risks', [
    'query' => [
        'address' => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
        'network' => 'tron'
    ],
    'headers' => [
        'X-Access-Key'  => '${YOUR_API_KEY}',
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
]);

require 'net/http'

uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/entities-risks')
params = {
  :address => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
  :network => 'tron',
}
uri.query = URI.encode_www_form(params)

req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

GET /api/v1/tracker/kya/entities-risks

Query Parameters
Parameter Type Required Description
address string true The address that you want to retrieve a entity for.
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1726117290776,
    "address":"TNk8zE9iHPj8LExnLhRi8Ufs9zYbvgRc7n",
    "network":"tron",
    "whitelist": false,
    "contract": false,
    "entity":{
      "entityName":"Bitget User",
      "entityCode":"bitget-user",
      "entityCategory":"Exchange",
      "entityCategoryCode":"exchange"
    },
    "risks":[
      {
        "riskLevel":"generally-high",
        "riskType":"launder-money",
        "riskSource":"Bitrace"
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "riskSource":"Bitrace"
      },
      {
        "riskLevel":"high",
        "riskType":"online-gambling",
        "riskSource":"Bitrace"
      }
    ]
  }
}
Property Type Description
time number the response timestamp from server
address string The address that you want to retrieve a entity for.
network string The supported chainns short name. Values can be,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains
whitelist boolean The whitelisted addresses are intended to represent official addresses such as exchanges, which are not suitable for risk assessment due to the complex composition of their revenue funds.
contract boolean Whether is a contract address or not.
entity object An object that contains any available entity information for the provided address. If the object returns null, the address has not any entity information. More detail at Schema - Entity
entity.entityName string The name of the identified entity.
entity.entityCode string The code of the identified entity.
entity.entityCategory string The category of the identified entity
entity.entityCategoryCode string The category code of the identified entity
intelligenceEntities array or null An object arrya that contains any available intelligence entities. Same schema as Schema - Entity
intelligenceEntities[].entityName string The name of the identified entity.
intelligenceEntities[].entityCode string The code of the identified entity.
intelligenceEntities[].entityCategory string The category of the identified entity
intelligenceEntities[].entityCategoryCode string The category code of the identified entity
risks array or null An object array that contains any available risk information for the provided address. If the object returns null, the address has not any risk information.
risks[].riskLevel string The level of the risk.
risks[].riskType string The type of the risk.
risks[].riskSource string The source of the risk.

Retrieve Bulk Entities and Risk Assessments

listAddressEntitiesAndRisks - This endpoint retrieves bulk entities and risks by given addresses.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/entities-risks" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "addresses": [
        "TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
        "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW"
      ],
      "network": "tron"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

var payload = {
  "addresses": [
      "TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
      "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW"
  ],
  "network": "tron"
}

const response = await axios.post('/api/v1/tracker/kya/entities-risks', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = baseUrl + "/api/v1/tracker/kya/entities-risks"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'addresses': [
      'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc',
      'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW'
    ],
    'network': 'tron',
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kya/entities-risks"
  method := "POST"

  payload := strings.NewReader(`{
    "addresses": [
        "TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
        "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW"
    ],
    "network": "tron"
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kya/entities-risks', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'addresses' => [
            'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc',
            'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW'
        ],
        'network' => 'tron'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/entities-risks')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'addresses' => [
    'TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc',
    'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW'
  ],
  'network' => 'tron'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kya/entities-risks

Request Body Schame
Parameter Type Required Description
addresses string[] true The address array that you want to retrieve entities for.
And the array limit size is 100
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
  • ...
See at Supported Chains

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":[
    {
      "time":1714108038581,
      "address":"TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
      "network":"tron",
      "whitelist": false,
      "entity":{
        "entityName":"Bybit User",
        "entityCode":"bybit-user",
        "entityCategory":"Exchange",
        "entityCategoryCode":"exchange"
      },
      "risks":null
    },
    {
      "time":1714108038581,
      "address":"TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
      "network":"tron",
      "whitelist": false,
      "entity":{
        "entityName":"Money Laundering",
        "entityCode":"launder-money",
        "entityCategory":null,
        "entityCategoryCode":null
      },
      "risks":[
        {
          "riskLevel":"super-high",
          "riskType":"money_laundering"
        }
      ]
    }
  ]
}
Property Type Description
time number the response timestamp from server
address string The address that you want to retrieve a entity for.
network string The supported chainns short name. Values can be,
  • ethereum
  • tron
  • btc
  • bsc
whitelist boolean The whitelisted addresses are intended to represent official addresses such as exchanges, which are not suitable for risk assessment due to the complex composition of their revenue funds.
contract boolean Whether is a contract address or not.
entity object An object that contains any available entity information for the provided address. If the object returns null, the address has not any entity information. More detail at Schema - Entity
entity.entityName string The name of the identified entity.
entity.entityCode string The code of the identified entity.
entity.entityCategory string The category of the identified entity
entity.entityCategoryCode string The category code of the identified entity
intelligenceEntities array or null An object arrya that contains any available intelligence entities. Same schema as Schema - Entity
intelligenceEntities[].entityName string The name of the identified entity.
intelligenceEntities[].entityCode string The code of the identified entity.
intelligenceEntities[].entityCategory string The category of the identified entity
intelligenceEntities[].entityCategoryCode string The category code of the identified entity
risks array or null An object array that contains any available risk information for the provided address. If the object returns null, the address has not any risk information.
risks[].riskLevel string The level of the risk.
risks[].riskType string The type of the risk.
risks[].riskSource string The source of the risk.

Retrieve Risk Score

getAddressRiskScore - This endpoint get risk score by given address.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/risk-scores?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron&customId=123456' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/risk-scores?network=tron&requestId=063c04ef57e443eb70365795cf0c0cc7ac' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

const response = await axios.get('/api/v1/tracker/kya/risk-scores', {
  params: {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron',
    'customId': '123456'
  },
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

import requests

url = "${API_BASE_URL}/api/v1/tracker/kya/risk-scores"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

params = {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron',
    'customId': 'customId',
}

response = requests.get(url, params=params, headers=headers)

print(response.text)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "${API_BASE_URL}/api/v1/tracker/kya/risk-scores?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron&customId=123456", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-Access-Key", "${YOUR_API_KEY}")
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('${API_BASE_URL}' . '/api/v1/tracker/kya/risk-scores', [
    'query' => [
        'address' => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
        'network' => 'tron',
        'customId'=> '123456',
    ],
    'headers' => [
        'X-Access-Key'  => '${YOUR_API_KEY}',
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
]);

require 'net/http'

uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/risk-scores')
params = {
  :address => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
  :network => 'tron',
  :customId=> '123456',
}
uri.query = URI.encode_www_form(params)

req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

GET /api/v1/tracker/kya/risk-scores

Query Parameters
Parameter Type Required Description
address string true The address that you want to retrieve a entity for.
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
See at Supported Chains
customId string false The identifier by user-defined, it will be included in response if provided
requestId* string false The request idetifier to get the async result 
sequenceDiagram
    HTTP Client->>+Bitrace AML API: Retrive the Risk Score(s)
    Bitrace AML API->>-HTTP Client: Response the requestId
    loop if the scores is null
        HTTP Client-->>+Bitrace AML API: requestId
        Bitrace AML API-->>-HTTP Client: Corresponding Risk Score(s)
    end

workflow

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "requestId":"26784916292200597542974738410940",
    "status":1001,
    "customId": "1234567"
  }
}

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "scores":[
      {
        "address":"TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
        "score":"92"
      }
    ],
    "requestId":"26784916292200597542974738410940",
    "customId": "1234567",
    "status":1003
  }
}
Property Type Description
requestId string the corresponding request identifier
customId string The identifier by user-defined, if provided in request
status number The asynchronous task status,
  • 1000: Queueing
  • 1001: In Progress
  • 1002: Failed
  • 1003: Completed
See at Aysnc Task Status
scores array or null An object array that contains any available risk score information for the provided address. If the object returns null, risk calculation asynchronous processing is still in progress, please check back later for results.
scores[].address string The wallet address
scores[].score number or string The risk score of the address, More detail at Risk Score Explanation

Retrieve Bulk Risk Scores

listAddressRiskScores - This endpoint retrieves bulk risk scores by given addresses.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/risk-scores" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "customId": "123456",
      "addresses": [
        "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
        "THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
        "TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
        "TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk"
      ],
      "network": "tron"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

var payload = {
  "customId": "123456",
  "addresses": [
    "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
    "THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
    "TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
    "TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
    "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
    "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk"
  ],
  "network": "tron"
}

const response = await axios.post('/api/v1/tracker/kya/risk-scores', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = baseUrl + "/api/v1/tracker/kya/risk-scores"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'customId': '123456',
    'addresses': [
      'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
      'THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ',
      'TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5',
      'TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo',
      'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk',
      'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk'
    ],
    'network': 'tron',
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kya/risk-scores"
  method := "POST"

  payload := strings.NewReader(`{
    "customId": "123456",
    "addresses": [
        "TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
        "THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
        "TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
        "TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
        "TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk"
    ],
    "network": "tron"
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kya/risk-scores', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'customId' => '123456',
        'addresses' => [
            'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
            'THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ',
            'TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5',
            'TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo',
            'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk',
            'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk'
        ],
        'network' => 'tron'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/risk-scores')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'customId': '123456',
  'addresses' => [
    'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ',
    'TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5',
    'TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo',
    'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk',
    'TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk'
  ],
  'network' => 'tron'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kya/risk-scores

Request Body Schame
Parameter Type Required Description
addresses string[] true The address array that you want to retrieve entities for.
And the array limit size is 100
customId string false The identifier by user-defined, it will be included in response if provided
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
See at Supported Chains
requestId* string false The request idetifier to get the async result

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "requestId":"56500112606194083864862234828045",
    "status":1001,
    "customId": "1234567"
  }
}

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "scores":[
      {
        "address":"THyRaxcBo38AfW9XrKYutgJgRaGygucgKJ",
        "score":"1"
      },
      {
        "address":"TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW",
        "score":"92"
      },
      {
        "address":"TERx4pYzjM9jrShuRhGXvqxoAdZ83VyvZo",
        "score":"53"
      },
      {
        "address":"TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
        "score":"1"
      },
      {
        "address":"TQoYEabovCJaAaxt32m9khPbHJXRb8K6jk",
        "score":"2"
      }
    ],
    "requestId":"56500112606194083864862234828045",
    "status":1003,
    "customId":"123456"
  },
  "msg":"SUCCESS"
}
Property Type Description
requestId string the corresponding request identifier
customId string The identifier by user-defined, if provided in request
status number The asynchronous task status,
  • 1000: Queueing
  • 1001: In Progress
  • 1002: Failed
  • 1003: Completed
See at Aysnc Task Status
scores array or null An object array that contains any available risk score information for the provided address. If the object returns null, risk calculation asynchronous processing is still in progress, please check back later for results.
scores[].address string The wallet address
scores[].score number or string The risk score of the address, More detail at Risk Score Explanation

Retrieve Address Basic Info

getAddressBasic - This endpoint get basic information by given address.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/address/basic?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/address/basic?network=tron&requestId=063c04ef57e443eb70365795cf0c0cc7ac' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

const response = await axios.get('/api/v1/tracker/kya/address/basic', {
  params: {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron'
  },
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

import requests

url = "${API_BASE_URL}/api/v1/tracker/kya/address/basic"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

params = {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron',
}

response = requests.get(url, params=params, headers=headers)

print(response.text)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "${API_BASE_URL}/api/v1/tracker/kya/address/basic?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-Access-Key", "${YOUR_API_KEY}")
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('${API_BASE_URL}' . '/api/v1/tracker/kya/address/basic', [
    'query' => [
        'address' => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
        'network' => 'tron'
    ],
    'headers' => [
        'X-Access-Key'  => '${YOUR_API_KEY}',
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
]);

require 'net/http'

uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/address/basic')
params = {
  :address => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
  :network => 'tron',
}
uri.query = URI.encode_www_form(params)

req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

GET /api/v1/tracker/kya/address/basic

Query Parameters
Parameter Type Required Description
address string true The target address.
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
See at Supported Chains

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "activeType":2,
    "balance":{
      "USDT":15258.233985,
      "TRX":3708.129097
    },
    "firstInTx":{
      "time":1706946036000,
      "hash":"6a302a668f47a130c211cdcd0e4d1ab8e909e6817b989b17faa939c22da8292d",
      "symbol":"TRX"
    },
    "firstOutTx":{
      "time":1707159735000,
      "hash":"4996010dc51d24364b3ffba067de222f26faf953bb15fce531923732b6ceb8f8",
      "symbol":"USDT"
    },
    "mainInStatistic":{
      "symbol":"TRX",
      "contractAddr":null,
      "txCount":1463,
      "txValue":102615.909410
    },
    "mainOutStatistic":{
      "symbol":"TRX",
      "contractAddr":null,
      "txCount":3253,
      "txValue":10352.595733
    },
    "stableOutStatistic":{
      "symbol":"USDT",
      "contractAddr":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "txCount":3251,
      "txValue":8851064.257900
    },
    "stableInStatistic":{
      "symbol":"USDT",
      "contractAddr":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "txCount":1026,
      "txValue":8866322.491885
    }
  }
}
Property Type Description
activeType integer the address account active status in last 180 days,
  • 0: transfer in only
  • 1: Inactive
  • 2: Active
balance object the account balance
balance.[GAS_TOKEN] number the account gas token amount balance
balance.[STABLE_COIN_TOKEN] number the account stable coin token amount balance
firstInTx object the fisrt inflow transcation
firstInTx.time integer the timestamp of fisrt inflow transcation
firstInTx.hash string the trasaction hash of fisrt inflow transcation
firstInTx.symbol string the trasaction token symbol of fisrt inflow transcation
firstOutTx object the fisrt outflow transcation
firstOutTx.time integer the timestamp of fisrt outflow transcation
firstOutTx.hash string the trasaction hash of fisrt outflow transcation
firstOutTx.symbol string the trasaction token symbol of fisrt outflow transcation
mainInStatistic object the inflow statics of native token
mainInStatistic.symbol string the token symbol
mainInStatistic.contractAddr string or null the token contract address if exist
mainInStatistic.txCount integer or null the total inflow transaction count of native token
mainInStatistic.txValue number or null the total inflow transaction amount of native token
mainOutStatistic object the outflow statics of native token
mainOutStatistic.symbol string the token symbol
mainOutStatistic.contractAddr string null
mainOutStatistic.txCount integer or null the total outflow transaction count of native token
mainOutStatistic.txValue number or null the total outflow transaction amount of native token
stableInStatistic object the inflow statics of stable coin
stableInStatistic.symbol string the token symbol
stableInStatistic.contractAddr string or null the token contract address if exist
stableInStatistic.txCount integer or null the total inflow transaction count of stable coin
stableInStatistic.txValue number or null the total inflow transaction amount of stable coin
stableOutStatistic object the outflow statics of stable coin
stableOutStatistic.symbol string the token symbol
stableOutStatistic.contractAddr string null
stableOutStatistic.txCount integer or null the total outflow transaction count of stable coin
stableOutStatistic.txValue number or null the total outflow transaction amount of stable coin

Retrieve Address TopN Counterparties

getAddressCounterparties - This endpoint get counterparties (Top10) by given address.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/address/counterparties?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

# API_BASE_URL = https://api.bitrace.io
curl -X GET '${API_BASE_URL}/api/v1/tracker/kya/address/counterparties?network=tron&requestId=063c04ef57e443eb70365795cf0c0cc7ac' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

const response = await axios.get('/api/v1/tracker/kya/address/counterparties', {
  params: {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron'
  },
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

import requests

url = "${API_BASE_URL}/api/v1/tracker/kya/address/counterparties"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

params = {
    'address': 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
    'network': 'tron',
}

response = requests.get(url, params=params, headers=headers)

print(response.text)

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "${API_BASE_URL}/api/v1/tracker/kya/address/counterparties?address=TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW&network=tron", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-Access-Key", "${YOUR_API_KEY}")
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    bodyText, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s\n", bodyText)
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('${API_BASE_URL}' . '/api/v1/tracker/kya/address/counterparties', [
    'query' => [
        'address' => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
        'network' => 'tron'
    ],
    'headers' => [
        'X-Access-Key'  => '${YOUR_API_KEY}',
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
]);

require 'net/http'

uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/address/counterparties')
params = {
  :address => 'TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW',
  :network => 'tron',
}
uri.query = URI.encode_www_form(params)

req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

GET /api/v1/tracker/kya/address/counterparties

Query Parameters
Parameter Type Required Description
address string true The targe address
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "highNumberList":[
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TWBPGLwQw2EbqYLLw1DJnTDt2ZQ9yJW1JJ",
        "value":1710728,
        "txCount":80,
        "entityTag":"WhiteBIT",
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TU4vEruvZwLLkSfV9bNw12EJTPvNr7Pvaa",
        "value":1660328,
        "txCount":57,
        "entityTag":"Bybit",
        "contract":false
      },
      {
        "riskLevel":"high",
        "riskType":"online-gambling",
        "address":"TQi2Zr5T9U1EyGXGNLqnmJuZj5anXTUFX4",
        "value":981909,
        "txCount":22,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TXPizwQ2rUFJqqu4hTCx4mWRD5NwnKmSS5",
        "value":699637,
        "txCount":33,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"THxCSTmzSjZDorrac4hjrHLaeEZKZeP1jy",
        "value":645466,
        "txCount":11,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
        "value":542882,
        "txCount":30,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"THj1ZHWwey1wV2NsK3azXLVFYN5rYsrQB9",
        "value":455187,
        "txCount":123,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TMjNUbfb2aH14PTdnAyV9JXyMpBtBcVZr6",
        "value":454896,
        "txCount":63,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TVFfFJL4Eavgj6vyAGx6C8jSm7WyTAvxju",
        "value":439875,
        "txCount":28,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TZCmekMZDq4Rgn9Ropmk2EEQVwb4f4RJQc",
        "value":393028,
        "txCount":47,
        "entityTag":null,
        "contract":false
      }
    ],
    "highRiskList":[
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "address":"TD9HhCTfNgnk2TZ8y8qpTUaiLxnWmDTNiT",
        "value":399.70,
        "txCount":2,
        "entityTag":"Binance User",
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "address":"TDhL1uKjamnCoy51H2DNWeAh5X5kT6zSR5",
        "value":1020.00,
        "txCount":1,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "address":"THW4YpjmJ8noRpPTw9s5oiCfizEGxtyS2R",
        "value":2026.00,
        "txCount":4,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "address":"TEA6wJ8B26EsSD9RstxeXNp4tu81YpuKj6",
        "value":8538.40,
        "txCount":2,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "address":"TEQsQmx57KFHy5NXZCvwsgoNiXGustASpE",
        "value":67100,
        "txCount":5,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"online-gambling",
        "address":"TBbX6PsGzixzQ27UrTTEJwmQ8rh7viqAQL",
        "value":4046.40,
        "txCount":1,
        "entityTag":"Binance User",
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "address":"TKm25JvXgNVfyKd6jNabHcUuHWP6JpngY5",
        "value":1417.00,
        "txCount":1,
        "entityTag":"Binance User",
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"black-gray-goods",
        "address":"TLecbiYDo2fxKed3CfkytF2WiX5p8mcVpp",
        "value":613.48,
        "txCount":5,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"online-gambling",
        "address":"THS1hzARWE4dGRBw3J6NoKv2T3EyGWLg9h",
        "value":1934.09,
        "txCount":1,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":"generally-high",
        "riskType":"online-gambling",
        "address":"TXasHCbKz1udCcabk8nX2XXDoJ1wsJ5ndU",
        "value":48127,
        "txCount":21,
        "entityTag":"Binance User",
        "contract":false
      }
    ],
    "highFrequencyList":[
      {
        "riskLevel":null,
        "riskType":null,
        "address":"THj1ZHWwey1wV2NsK3azXLVFYN5rYsrQB9",
        "value":455187,
        "txCount":123,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TLoRSPNgVdg2PFjrzWgVD6H5aF349H4PS2",
        "value":154531,
        "txCount":114,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TWBPGLwQw2EbqYLLw1DJnTDt2ZQ9yJW1JJ",
        "value":1710728,
        "txCount":80,
        "entityTag":"WhiteBIT",
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TMjNUbfb2aH14PTdnAyV9JXyMpBtBcVZr6",
        "value":454896,
        "txCount":63,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TU4vEruvZwLLkSfV9bNw12EJTPvNr7Pvaa",
        "value":1660328,
        "txCount":57,
        "entityTag":"Bybit",
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TXFacGMGokWfsTKmZAYAUCbVrD51Jp8g9g",
        "value":276285,
        "txCount":52,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TW522J2sLwpxBCLtTZYTgCnZSLjhuir9SP",
        "value":288852,
        "txCount":51,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TYWDP3YVwEybggNx6mh6GDCPhd1FyjJpy1",
        "value":108136,
        "txCount":47,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TZCmekMZDq4Rgn9Ropmk2EEQVwb4f4RJQc",
        "value":393028,
        "txCount":47,
        "entityTag":null,
        "contract":false
      },
      {
        "riskLevel":null,
        "riskType":null,
        "address":"TEu1g5dkdjPrWWJFqFcZyJN56vZ5voYbrW",
        "value":156384,
        "txCount":46,
        "entityTag":null,
        "contract":false
      }
    ]
  }
}
Property Type Description
highNumberList array or null An object array that contains any available TopN high value counterparties information
highNumberList[].address string The counterparty address
highNumberList[].value nubmer The total cumulative transaction amount value (in USDT)
highNumberList[].txCount integer The total transaction count
highNumberList[].entityTag string or null The entity tag of the address
highNumberList[].riskLevel string or null The risk level of the address
highNumberList[].riskType string or null The risk type of the address
highNumberList[].contract boolean Whether is contrcat or not
highFrequencyList array or null An object array that contains any available TopN high frequency counterparties information
highFrequencyList[].address string The counterparty address
highFrequencyList[].value nubmer The total cumulative transaction amount value (in USDT)
highFrequencyList[].txCount integer The total transaction count
highFrequencyList[].entityTag string or null The entity tag of the address
highFrequencyList[].riskLevel string or null The risk level of the address
highFrequencyList[].riskType string or null The risk type of the address
highFrequencyList[].contract boolean Whether is contrcat or not
highRiskList array or null An object array that contains any available TopN high risk counterparties information
highRiskList[].address string The counterparty address
highRiskList[].value nubmer The total cumulative transaction amount value (in USDT)
highRiskList[].txCount integer The total transaction count
highRiskList[].entityTag string or null The entity tag of the address
highRiskList[].riskLevel string or null The risk level of the address
highRiskList[].riskType string or null The risk type of the address
highRiskList[].contract boolean Whether is contrcat or not

Retrieve Custom Risk Score

getAddressCustomRiskScore - This endpoint retrieves the custom risk scores by given address.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/custom-risk-scores" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "customId": "123456",
      "address": "TMqDrZa5kEebg5wi3W3wusVZ6ZF2w6JczH",
      "network": "tron"
  }'

curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/custom-risk-scores" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "requestId": "69417729314225615324513892905990"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

var payload = {
  "customId": "123456",
  "address": "TMqDrZa5kEebg5wi3W3wusVZ6ZF2w6JczH",
  "network": "tron"
}

const response = await axios.post('/api/v1/tracker/kya/custom-risk-scores', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = baseUrl + "/api/v1/tracker/kya/custom-risk-scores"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'customId': '123456',
    'address': 'TMqDrZa5kEebg5wi3W3wusVZ6ZF2w6JczH',
    'network': 'tron',
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kya/custom-risk-scores"
  method := "POST"

  payload := strings.NewReader(`{
    "customId": "123456",
    "address": "TMqDrZa5kEebg5wi3W3wusVZ6ZF2w6JczH",
    "network": "tron"
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kya/custom-risk-scores', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'customId' => '123456',
        'address' => 'TMqDrZa5kEebg5wi3W3wusVZ6ZF2w6JczH',
        'network' => 'tron'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/custom-risk-scores')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'customId': '123456',
  'address' => 'TMqDrZa5kEebg5wi3W3wusVZ6ZF2w6JczH',
  'network' => 'tron'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kya/custom-risk-scores

Request Body Schame
Parameter Type Required Description
address string true The address that you want to retrieve a entity for.
customId string false The identifier by user-defined, it will be included in response if provided
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
See at Supported Chains
requestId* string false The request idetifier to get the async result

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "requestId":"69417729314225615324513892905990",
    "status":1000,
    "customId":"123456"
  },
  "msg":"SUCCESS"
}

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "maxScore":"99",
    "dirData":{
      "in":{
        "default":{
          "strategyNo":"default",
          "strategyName":"default",
          "details":[
            {
              "code":"black-gray-goods",
              "name":"Black-Gray Market",
              "score":"80"
            }
          ],
          "score":"80"
        },
        "default_62680284809793536_71005651894991878734641207805009":{
          "strategyNo":"default_62680284809793536_71005651894991878734641207805009",
          "strategyName":"3 hop｜Online Gambling&Black-Gray Market&Money Laundering｜By Amount proportion",
          "details":[
            {
              "code":"online-gambling",
              "name":"Online Gambling",
              "score":"99"
            },
            {
              "code":"black-gray-goods",
              "name":"Black-Gray Market",
              "score":"99"
            },
            {
              "code":"launder-money",
              "name":"Money Laundering",
              "score":"65.1477"
            }
          ],
          "score":"99"
        }
      },
      "out":{
        "default_62680284809793536_81955706501512972153400093852167":{
          "strategyNo":"default_62680284809793536_81955706501512972153400093852167",
          "strategyName":"3 hop｜Online Gambling&Black-Gray Market&Money Laundering｜By Amount",
          "details":[
            {
              "code":"black-gray-goods",
              "name":"Black-Gray Market",
              "score":"99"
            }
          ],
          "score":"99"
        },
        "default_62680284809793536_51146476853089016489590924639443":{
          "strategyNo":"default_62680284809793536_51146476853089016489590924639443",
          "strategyName":"3 hop｜Severe Risk Address ｜By Amount ",
          "details":[
            {
              "code":"scam",
              "name":"Fraud",
              "score":"78.3752"
            }
          ],
          "score":"78.3752"
        },
        "default":{
          "strategyNo":"default",
          "strategyName":"default",
          "details":[
            {
              "code":"black-gray-goods",
              "name":"Black-Gray Market",
              "score":"80"
            }
          ],
          "score":"80"
        },
        "default_62680284809793536_37951575844750516343707207390480":{
          "strategyNo":"default_62680284809793536_37951575844750516343707207390480",
          "strategyName":"3 hop｜Severe Risk Address ｜By Amount proportion",
          "details":[
            {
              "code":"scam",
              "name":"Fraud",
              "score":"99"
            },
            {
              "code":"hack",
              "name":"Hacking",
              "score":"70.81815"
            }
          ],
          "score":"99"
        },
        "default_62680284809793536_71005651894991878734641207805009":{
          "strategyNo":"default_62680284809793536_71005651894991878734641207805009",
          "strategyName":"3 hop｜Online Gambling&Black-Gray Market&Money Laundering｜By Amount proportion",
          "details":[
            {
              "code":"online-gambling",
              "name":"Online Gambling",
              "score":"99"
            },
            {
              "code":"black-gray-goods",
              "name":"Black-Gray Market",
              "score":"99"
            },
            {
              "code":"launder-money",
              "name":"Money Laundering",
              "score":"99"
            }
          ],
          "score":"99"
        }
      }
    },
    "status":1003,
    "requestId":"69417729314225615324513892905990",
    "customId":"123456"
  },
  "msg":"SUCCESS"
}
Property Type Description
requestId string the corresponding request identifier
customId string The identifier by user-defined, if provided in request
status number The asynchronous task status,
  • 1000: Queueing
  • 1001: In Progress
  • 1002: Failed
  • 1003: Completed
See at Aysnc Task Status
maxScore string The maximum possible score value
dirData object Contains strategy maps for inflow and outflow data
dirData.in map<string, Strategy> Inflow tx hitting strategy map
dirData.in.<strategyNo> object The hitting strategy object in inflow
dirData.in.<strategyNo>.strategyNo string Unique identifier for the strategy
dirData.in.<strategyNo>.strategyName string Human-readable name of the strategy
dirData.in.<strategyNo>.score string or number The overall score of the strategy
dirData.in.<strategyNo>.details array or null List of detail objects related to the score
dirData.in.<strategyNo>.details[].score string Score value for the specific detail
dirData.in.<strategyNo>.details[].code string Code representing the detail
dirData.in.<strategyNo>.details[].name string Human-readable name of the detail
dirData.out map<string, Strategy> Outflow tx hitting strategy map
dirData.out.<strategyNo> object The hitting strategy object in outflow
dirData.out.<strategyNo>.strategyNo string Unique identifier for the strategy
dirData.out.<strategyNo>.strategyName string Human-readable name of the strategy
dirData.out.<strategyNo>.score string or number The overall score of the strategy
dirData.out.<strategyNo>.details array or null List of detail objects related to the score
dirData.out.<strategyNo>.details[].score string Score value for the specific detail
dirData.out.<strategyNo>.details[].code string Code representing the detail
dirData.out.<strategyNo>.details[].name string Human-readable name of the detail

Retrieve Entities, Risks and Scores

getAddressTagsAndScores - This endpoint retrieves the address information by given address,

  1. Entities
  2. Risk Assessments
  3. System Risk Score (Asynchronous Task)
  4. Custom Risk Score (Asynchronous Task)

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/tags-and-scores" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "customId": "123456",
      "address": "0x2c523bafccec0996335dfad5a1b4eca064f6ff91",
      "network": "eth"
  }'

curl -X POST "${API_BASE_URL}/api/v1/tracker/kya/tags-and-scores" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "requestId": "33787190817267129728257539512713"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

var payload = {
  "customId": "123456",
  "address": "0x2c523bafccec0996335dfad5a1b4eca064f6ff91",
  "network": "eth"
}

const response = await axios.post('/api/v1/tracker/kya/tags-and-scores', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = baseUrl + "/api/v1/tracker/kya/tags-and-scores"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'customId': '123456',
    'address': '0x2c523bafccec0996335dfad5a1b4eca064f6ff91',
    'network': 'eth',
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kya/tags-and-scores"
  method := "POST"

  payload := strings.NewReader(`{
    "customId": "123456",
    "address": "0x2c523bafccec0996335dfad5a1b4eca064f6ff91",
    "network": "eth"
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kya/tags-and-scores', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'customId' => '123456',
        'address' => '0x2c523bafccec0996335dfad5a1b4eca064f6ff91',
        'network' => 'eth'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kya/tags-and-scores')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'customId': '123456',
  'address' => '0x2c523bafccec0996335dfad5a1b4eca064f6ff91',
  'network' => 'eth'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kya/tags-and-scores

Request Body Schame
Parameter Type Required Description
address string true The address that you want to retrieve a entity for
customId string false The identifier by user-defined, it will be included in response if provided
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
See at Supported Chains
requestId* string false The request idetifier to get the async result

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "addressTags":{
      "time":1748516579866,
      "address":"0x2c523bafccec0996335dfad5a1b4eca064f6ff91",
      "whitelist":false,
      "network":"eth",
      "risks":[
        {
          "riskLevel":"high",
          "riskType":"launder-money",
          "riskSource":"Bitrace"
        }
      ],
      "intelligenceEntities":[
        {
          "entityName":"Community Disclosure",
          "entityCode":"community-disclosure",
          "entityCategory":"Community",
          "entityCategoryCode":"community"
        }
      ],
      "contract":false
    },
    "requestId":"33787190817267129728257539512713",
    "status":1000,
    "customId":"123456"
  },
  "msg":"SUCCESS"
}

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "addressTags":{
      "time":1748516695160,
      "address":"0x2c523bafccec0996335dfad5a1b4eca064f6ff91",
      "whitelist":false,
      "network":"eth",
      "risks":[
        {
          "riskLevel":"high",
          "riskType":"launder-money",
          "riskSource":"Bitrace"
        }
      ],
      "intelligenceEntities":[
        {
          "entityName":"Community Disclosure",
          "entityCode":"community-disclosure",
          "entityCategory":"Community",
          "entityCategoryCode":"community"
        }
      ],
      "contract":false
    },
    "systemScores":{
      "scores":[
        {
          "address":"0x2c523bafccec0996335dfad5a1b4eca064f6ff91",
          "score":"89"
        }
      ]
    },
    "customScores":{
      "maxScore":"80",
      "dirData":{
        "in":{
          "default":{
            "strategyNo":"default",
            "strategyName":"default",
            "details":[
              {
                "code":"launder-money",
                "name":"Money Laundering",
                "score":"80"
              }
            ],
            "score":"80"
          }
        },
        "out":{
          "default":{
            "strategyNo":"default",
            "strategyName":"default",
            "details":[
              {
                "code":"launder-money",
                "name":"Money Laundering",
                "score":"80"
              }
            ],
            "score":"80"
          }
        }
      },
      "status":1003
    },
    "requestId":"33787190817267129728257539512713",
    "status":1003,
    "customId":"123456"
  },
  "msg":"SUCCESS"
}
Property Type Description
requestId string the corresponding request identifier
customId string The identifier by user-defined, if provided in request
status number The asynchronous task status,
  • 1000: Queueing
  • 1001: In Progress
  • 1002: Failed
  • 1003: Completed
See at Aysnc Task Status
addressTags object The address entities and risk assessments, see at Entity and Risk Assessment
systemScores object The system risk score result in near real time, see at Risk Score
customScores object The custom risk score result in near real time, see at Custom Risk Score

Know Your Transaction（KYT)

KYT Quickstart

The KYT (Know Your Transaction) API is an automated crypto asset transaction monitoring and compliance solution.

The KYT API provides real-time risk screening and compliance insights for your customer's deposit and withdrawal activities with continuous retrieve KYT-generated alerts, exposure information, or identifications to help you quickly make synchronous decisions about how to treat the transfer or withdrawal.

KYT Supported Chains

Chain Full Name Chain Short Name Chain ID Code
Ethereum ETH 1 ethereum
TRON TRON N/A tron

KYT API

Retrieve Transaction Risks

getTransactionRisks - This endpoint retrieves risk informations for the specific transaction.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST '${API_BASE_URL}/api/v1/tracker/kyt/transfers/risk-screening' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}' \
  --data '{
    "network": "eth",
    "hash": "0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f",
    "tokenContractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "outputAddress": "0xa023319e8ed4302f7d05587ce3c7066aa97200c1",
    "direction": "received"
  }'

# API_BASE_URL = https://api.bitrace.io
curl -X POST '${API_BASE_URL}/api/v1/tracker/kyt/transfers/risk-screening' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: ${YOUR_API_KEY}' \
  --data '{
    "network": "eth",
    "externalId": "87111618424664721806777127547213"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

const payload = {
  "network":"eth",
  "hash":"0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f",
  "tokenContractAddress":"0xdac17f958d2ee523a2206206994597c13d831ec7",
  "outputAddress":"0xa023319e8ed4302f7d05587ce3c7066aa97200c1",
  "direction":"received"
}

const response = await axios.post(`/api/v1/tracker/kyt/transfers/risk-screening`, {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = "{baseUrl}/api/v1/tracker/kyt/transfers/risk-screening".format(baseUrl = baseUrl)

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'network':'eth',
    'hash':'0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f',
    'tokenContractAddress':'0xdac17f958d2ee523a2206206994597c13d831ec7',
    'outputAddress':'0xa023319e8ed4302f7d05587ce3c7066aa97200c1',
    'direction':'received'
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kyt/transfers/risk-screening"
  method := "POST"

  payload := strings.NewReader(`{
    'network':'eth',
    'hash':'0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f',
    'tokenContractAddress':'0xdac17f958d2ee523a2206206994597c13d831ec7',
    'outputAddress':'0xa023319e8ed4302f7d05587ce3c7066aa97200c1',
    'direction':'received'
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kyt/transfers/risk-screening', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'network' => 'eth',
        'hash' => '0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f',
        'tokenContractAddress' => '0xdac17f958d2ee523a2206206994597c13d831ec7',
        'outputAddress' => '0xa023319e8ed4302f7d05587ce3c7066aa97200c1',
        'direction' => 'received'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kyt/transfers/risk-screening')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'network' => 'eth',
  'hash' => '0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f',
  'tokenContractAddress' => '0xdac17f958d2ee523a2206206994597c13d831ec7',
  'outputAddress' => '0xa023319e8ed4302f7d05587ce3c7066aa97200c1',
  'direction' => 'received'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kyt/transfers/risk-screening

Request Body Schame

The request body for initial query,

Parameter Type Required Description
network string true The supported chainns short name. Values can be,
  • eth
  • tron
  • btc
hash string true The transaction for detect the risks
outputAddress string true The destination address in the transaction
tokenContractAddress string false The token contract address, for USDT,
  • eth: 0xdac17f958d2ee523a2206206994597c13d831ec7
  • tron: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
Note: it should not be empty if inquiring token transaction
index integer false The position of the output address in the transaction.
Note: it is only available in the UTXO model
direction string true This value defines whether the transfer is sent or received.
  • sent: retrieve the risks for toAddress
  • received: retrieve the risks for fromAddress
This value is case insensitive
depth integer false default is 0, and also you can also set the depth between 1-5 to the risks of screening within the transaction propagation path

The request body for result query,

Parameter Type Required Description
network string true The supported chainns short name. Values can be,
  • eth
  • tron
  • btc
externalId string true The risk screening ID to query the final result 
flowchart TD
    A[Retrieve Transaction Risks] --> B{depth}
    B -->|depth == 0| C((Risk Result))
    B -->|depth == 1| C
    B -->|depth > 1| D([ID Result])
    D --> |externalId| C((Risk Result))

workflow

HTTP Response Schema

Response example 1

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "risks":[
      {
        "riskLevel":"low",
        "riskType":"scam"
      },
      {
        "riskLevel":"high",
        "riskType":"online-gambling"
      },
      {
        "riskLevel":"high",
        "riskType":"launder-money"
      }
    ],
    "externalId":"87111618424664721806777127547213",
    "resultTime":1723542989406,
    "analyseStatus":true,
    "hash":"0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f",
    "value":1902.31608,
    "blockTime":1718669807000,
    "address":"0x974caa59e49682cda0ad2bbe82983419a2ecc400"
  }
}

Response example 2

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "risks":null,
    "externalId":"27367642482326998474459157634639",
    "resultTime":null,
    "analyseStatus":null,
    "hash":"0xddeb5d1e29a88ac9e0a304f415628ff45f53c7278127de7f47c75b43bebcce8f",
    "value":1902.31608,
    "blockTime":1718669807000,
    "address":"0x974caa59e49682cda0ad2bbe82983419a2ecc400"
  }
}
Property Type Description
externalId string or null The generated identifier ID of this request
hash string The transaction for risk screening
vaule number The (token) value in the transaction
blockTime integer The block time of the transaction
address string The blockchain target address for risk screening
resultTime integer the query response time
analyseStatus boolean or null whether the transaction analysis is complete
risks array or null An object array that contains any available risk information for the provided address. If the object returns null, the address has not any risk information.
risks[].riskLevel string The level of the risk. More detail at Schema - Risk Level
risks[].riskType string The type of the risk. More detail at Schema - Risk Type

Retrieve Custom Risk Score

getTxHashCustomRiskScore - This endpoint retrieves the custom risk scores by given transaction.

HTTP Request

# API_BASE_URL = https://api.bitrace.io
curl -X POST "${API_BASE_URL}/api/v1/tracker/kyt/custom-risk-scores" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "customId": "123456",
      "address": "0dcd9698297318e84fdf13445c5e7b1b92a94633f96b635dc707b8cdcc6271f2",
      "network": "btc"
  }'

curl -X POST "${API_BASE_URL}/api/v1/tracker/kyt/custom-risk-scores" \
  --header "X-Access-Key: ${YOUR_API_KEY}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
      "requestId": "60944883389642198713019658195148"
  }'

import axios from 'axios';

axios.defaults.baseURL = 'https://api.bitrace.io';

var payload = {
  "customId": "123456",
  "address": "0dcd9698297318e84fdf13445c5e7b1b92a94633f96b635dc707b8cdcc6271f2",
  "network": "btc"
}

const response = await axios.post('/api/v1/tracker/kyt/custom-risk-scores', {
  headers: {
    'X-Access-Key': '${YOUR_API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: payload
});

import os
import json
import requests

baseUrl = os.getenv('API_BASE_URL', 'https://api.bitrace.io')
url = baseUrl + "/api/v1/tracker/kyt/custom-risk-scores"

headers = {
  'X-Access-Key': '${YOUR_API_KEY}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

payload_data = json.dumps({
    'customId': '123456',
    'address': '0dcd9698297318e84fdf13445c5e7b1b92a94633f96b635dc707b8cdcc6271f2',
    'network': 'btc',
})

response = requests.post(url, headers=headers, json=payload_data)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  // API_BASE_URL = https://api.bitrace.io
  url := "${API_BASE_URL}/api/v1/tracker/kyt/custom-risk-scores"
  method := "POST"

  payload := strings.NewReader(`{
    "customId": "123456",
    "address": "0dcd9698297318e84fdf13445c5e7b1b92a94633f96b635dc707b8cdcc6271f2",
    "network": "btc"
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("X-Access-Key", "${YOUR_API_KEY}")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// API_BASE_URL = https://api.bitrace.io
$response = $client->post('${API_BASE_URL}' . '/api/v1/tracker/kyt/custom-risk-scores', [
    'headers' => [
        'X-Access-Key' => '${YOUR_API_KEY}',
        'Accept'       => 'application/json',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'customId' => '123456',
        'address' => '0dcd9698297318e84fdf13445c5e7b1b92a94633f96b635dc707b8cdcc6271f2',
        'network' => 'btc'
    ]
]);

require 'net/http'

# API_BASE_URL = https://api.bitrace.io
uri = URI('${API_BASE_URL}' + '/api/v1/tracker/kyt/custom-risk-scores')
req = Net::HTTP::Get.new(uri)
req['X-Access-Key'] = '${YOUR_API_KEY}'
req['Accept'] = 'application/json'
req['Content-Type'] = 'application/json'

req.body = {
  'customId': '123456',
  'address' => '0dcd9698297318e84fdf13445c5e7b1b92a94633f96b635dc707b8cdcc6271f2',
  'network' => 'btc'
}.to_json

req_options = {
  use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(req)
end

POST /api/v1/tracker/kyt/custom-risk-scores

Request Body Schame
Parameter Type Required Description
hash string true The transaction for calculating the custom risk score
customId string false The identifier by user-defined, it will be included in response if provided
network string true The supported chainns short name,
  • ethereum
  • tron
  • btc
  • bsc
See at Supported Chains
requestId* string false The request idetifier to get the async result

HTTP Response Schema

Response example

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "requestId":"60944883389642198713019658195148",
    "status":1000,
    "customId":"123456"
  },
  "msg":"SUCCESS"
}

{
  "success":true,
  "code":1,
  "status":"SUCCESS",
  "data":{
    "maxScore":"22.27626",
    "dirData":{
      "in":{
        "default-kyt":{
          "strategyNo":"default-kyt",
          "strategyName":"default",
          "details":[
            {
              "code":"hack",
              "name":"Hacking",
              "score":"22.27626"
            }
          ],
          "score":"22.27626"
        },
        "default_62680284809793536_86437582530844820316382104768774":{
          "strategyNo":"default_62680284809793536_86437582530844820316382104768774",
          "strategyName":"3 hop｜All type ｜1% or 5000",
          "details":[
            {
              "code":"hack",
              "name":"Hacking",
              "score":"22.27626"
            }
          ],
          "score":"22.27626"
        }
      },
      "out":{

      }
    },
    "status":1003,
    "requestId":"60944883389642198713019658195148",
    "customId":"123456"
  },
  "msg":"SUCCESS"
}
Property Type Description
requestId string the corresponding request identifier
customId string The identifier by user-defined, if provided in request
status number The asynchronous task status,
  • 1000: Queueing
  • 1001: In Progress
  • 1002: Failed
  • 1003: Completed
See at Aysnc Task Status
maxScore string The maximum possible score value
dirData object Contains strategy maps for inflow and outflow data
dirData.in map<string, Strategy> Inflow tx hitting strategy map
dirData.in.<strategyNo> object The hitting strategy object in inflow
dirData.in.<strategyNo>.strategyNo string Unique identifier for the strategy
dirData.in.<strategyNo>.strategyName string Human-readable name of the strategy
dirData.in.<strategyNo>.score string or number The overall score of the strategy
dirData.in.<strategyNo>.details array or null List of detail objects related to the score
dirData.in.<strategyNo>.details[].score string Score value for the specific detail
dirData.in.<strategyNo>.details[].code string Code representing the detail
dirData.in.<strategyNo>.details[].name string Human-readable name of the detail
dirData.out map<string, Strategy> Outflow tx hitting strategy map
dirData.out.<strategyNo> object The hitting strategy object in outflow
dirData.out.<strategyNo>.strategyNo string Unique identifier for the strategy
dirData.out.<strategyNo>.strategyName string Human-readable name of the strategy
dirData.out.<strategyNo>.score string or number The overall score of the strategy
dirData.out.<strategyNo>.details array or null List of detail objects related to the score
dirData.out.<strategyNo>.details[].score string Score value for the specific detail
dirData.out.<strategyNo>.details[].code string Code representing the detail
dirData.out.<strategyNo>.details[].name string Human-readable name of the detail

Webhooks

sequenceDiagram
    participant HTTP Client
    participant API Service
    participant Webhooks Service

    HTTP Client->>API Service: Send Request
    API Service-->>HTTP Client: Response with requestId

    alt HTTP Client Polling
        loop Check for Result
            HTTP Client->>API Service: Get Result by requestId
            API Service-->>HTTP Client: Response with Result
        end
    else Webhooks Service Push
        API Service->>Webhooks Service: Send Response
        Webhooks Service-->>HTTP Client: Push Result to Client
    end

Bitrace API service offers a Webhook feature that allows users to receive event notifications.

workflow

Setup

  1. Sign in to the Bitrace AML.
  2. Click the menu API > Settings, make sure you have configured the API Key before.
  3. Navigate to the Webhook section, and input the mandatory fields
    • Webhook URL: the URL where the user wants to receive event notifications
    • Webhook Secret Key: a secret key provided by the user to verify the integrity of the received data.

Supported Signatures

Hash Calculation Rules

  1. Hash Calculation Scope: Only the data object in the payload is used for hash calculation.
  2. Field Sorting and String Conversion:
    • Fields within the data object are sorted alphabetically.
    • Each field is converted to a key=value format.
    • Fields are joined using the & character.
    • For nested objects within data, the same sorting and conversion rules apply.
    • For arrays within data, elements are referenced using the format array[index].field, followed by the same sorting and conversion rules.
  3. The computed Hash value is included in the HTTP response header as x-encrypted-data

Example

{
  "webhookId":"60944883389642198713019658195148",
  "data":{
    "dirData":{
      "in":{
        "default-kyt":{
          "strategyNo":"default-kyt",
          "strategyName":"default",
          "score":"22.27626",
          "details":[
            {
              "score":"22.27626",
              "code":"hack",
              "name":"Hacking"
            }
          ]
        },
        "default_62680284809793536_86437582530844820316382104768774":{
          "strategyNo":"default_62680284809793536_86437582530844820316382104768774",
          "strategyName":"3 hop｜All type ｜1% or 5000",
          "score":"22.27626",
          "details":[
            {
              "score":"22.27626",
              "code":"hack",
              "name":"Hacking"
            }
          ]
        }
      },
      "out":{

      }
    },
    "requestId":"60944883389642198713019658195148",
    "maxScore":"22.27626",
    "customId":"123456",
    "status":1003
  },
  "eventType":"getTxHashCustomRiskScore",
  "timestamp":"2025-05-29 11:25:23"
}

Assume the current secret key is ABCDEFG123456,

customId=123456&dirData.in.default-kyt.details[0].code=hack&dirData.in.default-kyt.details[0].name=Hacking&dirData.in.default-kyt.details[0].score=22.27626&dirData.in.default-kyt.score=22.27626&dirData.in.default-kyt.strategyName=default&dirData.in.default-kyt.strategyNo=default-kyt&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].code=hack&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].name=Hacking&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyName=3 hop｜All type ｜1% or 5000&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyNo=default_62680284809793536_86437582530844820316382104768774&maxScore=22.27626&requestId=60944883389642198713019658195148&status=1003

customId=123456&dirData.in.default-kyt.details[0].code=hack&dirData.in.default-kyt.details[0].name=Hacking&dirData.in.default-kyt.details[0].score=22.27626&dirData.in.default-kyt.score=22.27626&dirData.in.default-kyt.strategyName=default&dirData.in.default-kyt.strategyNo=default-kyt&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].code=hack&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].name=Hacking&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyName=3 hop｜All type ｜1% or 5000&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyNo=default_62680284809793536_86437582530844820316382104768774&maxScore=22.27626&requestId=60944883389642198713019658195148&status=1003ABCDEFG123456

MD5(<string_in_step2>) = 1388efbf63c13bfa3c8c1bf32cb3a9d5

Tools

JSON Decoder & MD5 Hash Generator

Events

KYT Events

API Event
Retrieve Risk Score listAddressesScore
Retrieve Bulk Risk Scores listAddressesScore
Retrieve Custom Risk Score getAddressCustomRiskScore
Retrieve Entities, Risks and Scores getAddressTagsAndScores

KYA Events

API Event
Retrieve Transaction Risks retrieveTransactionRisks
Retrieve Custom Risk Score getTxHashCustomRiskScore

Resources

Schema

API Reponse

Example (success),

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1714052957650,
    "address":"TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
    "network":"tron",
    "entity":{
      "entityName":"Bybit User",
      "entityCode":"bybit-user",
      "entityCategory":"Exchange",
      "entityCategoryCode":"exchange"
    }
  }
}

Example (error),

{
    "code": 429,
    "msg": "You exceeded your current quota, please check your plan and billing details.",
    "success": false
}
Name Type Description
success boolean Request success or not
code number
msg string SUCCESS or error message
data object array
error object the error object when response 4xx or 5xx

Entity

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1714052957650,
    "address":"TZ1noC2vbh8HRjt2icUbM1E6pKbSZ83Lfc",
    "network":"tron",
    "entity":{
      "entityName":"Bybit User",
      "entityCode":"bybit-user",
      "entityCategory":"Exchange",
      "entityCategoryCode":"exchange"
    }
  }
}
Name Type Description
entityName string The name of the identified entity
entityCode string The code of the identified entity
entityCategory string The category of the identified entity
entityCategoryCode string The category code of the identified entity

Risk Assessment

{
  "success":true,
  "code":1,
  "msg":"SUCCESS",
  "data":{
    "time":1714099360308,
    "address":"TFaB5JCw9Gum2eufeE1Qmmw1uSZCoKXbJ5",
    "network":"tron",
    "risks":[
      {
        "riskLevel":"high",
        "riskType":"online_gambling"
      }
    ]
  }
}
Name Type Description
riskLevel string The level of the risk assessment, see in Enum - Risk Level
riskType string The type of the risk assessment, see in Enum - Risk Type

Transfer & Withdrawal

Direct Exposure

{
  "direct": {
    "name": "BitPay.com",
    "category": "merchant services",
    "categoryId": 17
  }
}
Name Type Description
name string The name of a given cluster's counterparty as identified. If null, the entity has no name or Detrust has not identified the entity.
category string The category of a given cluster's counterparty as identified. see Schema - Risk Level
categoryId string The unique identifie for category.

Alert

{
  "alertLevel": "Severe",
  "category": "sanctioned entity",
  "service": "OFAC SDN Blender.io 2022-05-06",
  "externalId": "906ff226-8b64-11eb-8e52-7b35a3dc1742",
  "alertAmount": 8868.24,
  "exposureType": "DIRECT",
  "categoryId": 3
}
Name Type Description
alertLevel string Defines the alert's risk level, see Schema - Risk Level
category string The category of a given cluster's counterparty as identified. see Schema - Risk Level
categoryId string The unique identifie for category.
service string or null The name of the service as defined by Detrust.
externalId string A unique identify of the alert.
alertAmount number The USD amount that caused the alert to trigger.
exposureType string Defines the exposure direction as DIRECT or INDIRECT.

Strategy

{
  "alertLevel": "Severe",
  "category": "sanctioned entity",
  "service": "OFAC SDN Blender.io 2022-05-06",
  "externalId": "906ff226-8b64-11eb-8e52-7b35a3dc1742",
  "alertAmount": 8868.24,
  "exposureType": "DIRECT",
  "categoryId": 3
}
Name Type Description
strategy string or null The name of the strategy as defined by user.
rule string or null The rule of the strategy as defined by user.
level string Defines the alert's risk level, see Schema - Risk Level.
decisionCode string The decision code
decisionMarker string The decision marker

Custom Risk Score

{
  "maxScore":"99",
  "dirData":{
    "in":{
      "default":{
        "strategyNo":"default",
        "strategyName":"default",
        "details":[
          {
            "code":"launder-money",
            "name":"Money Laundering",
            "score":"80"
          },
          {
            "code":"online-gambling",
            "name":"Online Gambling",
            "score":"50"
          }
        ],
        "score":"80"
      },
      "default_62680284809793536_71005651894991878734641207805009":{
        "strategyNo":"default_62680284809793536_71005651894991878734641207805009",
        "strategyName":"3 hop｜Online Gambling&Black-Gray Market&Money Laundering｜By Amount proportion",
        "details":[
          {
            "code":"launder-money",
            "name":"Money Laundering",
            "score":"99"
          },
          {
            "code":"online-gambling",
            "name":"Online Gambling",
            "score":"99"
          }
        ],
        "score":"99"
      }
    },
    "out":{
      "default":{
        "strategyNo":"default",
        "strategyName":"default",
        "details":[
          {
            "code":"launder-money",
            "name":"Money Laundering",
            "score":"80"
          },
          {
            "code":"online-gambling",
            "name":"Online Gambling",
            "score":"50"
          }
        ],
        "score":"80"
      },
      "default_62680284809793536_71005651894991878734641207805009":{
        "strategyNo":"default_62680284809793536_71005651894991878734641207805009",
        "strategyName":"3 hop｜Online Gambling&Black-Gray Market&Money Laundering｜By Amount proportion",
        "details":[
          {
            "code":"launder-money",
            "name":"Money Laundering",
            "score":"99"
          },
          {
            "code":"online-gambling",
            "name":"Online Gambling",
            "score":"99"
          }
        ],
        "score":"99"
      }
    }
  }
}
Name Type Description
maxScore string or number The maximum possible score value
dirData object Contains strategy maps for inflow and outflow data
dirData.in map<string, Strategy> Inflow tx hitting strategy map
dirData.out map<string, Strategy> Outflow tx hitting strategy map

Custom Risk Strategy Definition,

Name Type Description
strategyNo string Unique identifier for the strategy
strategyName string Human-readable name of the strategy
score string or number The overall score of the strategy
details array or null List of detail objects related to the score
details[].score string Score value for the specific detail
details[].code string Code representing the detail
details[].name string Human-readable name of the detail

Webhook

{
  "webhookId":"60944883389642198713019658195148",
  "data":{
    "dirData":{
      "in":{
        "default-kyt":{
          "strategyNo":"default-kyt",
          "strategyName":"default",
          "score":"22.27626",
          "details":[
            {
              "score":"22.27626",
              "code":"hack",
              "name":"Hacking"
            }
          ]
        },
        "default_62680284809793536_86437582530844820316382104768774":{
          "strategyNo":"default_62680284809793536_86437582530844820316382104768774",
          "strategyName":"3 hop｜All type ｜1% or 5000",
          "score":"22.27626",
          "details":[
            {
              "score":"22.27626",
              "code":"hack",
              "name":"Hacking"
            }
          ]
        }
      },
      "out":{

      }
    },
    "requestId":"60944883389642198713019658195148",
    "maxScore":"22.27626",
    "customId":"123456",
    "status":1003
  },
  "eventType":"getTxHashCustomRiskScore",
  "timestamp":"2025-05-29 11:25:23"
}
Name Type Description
webhookId string The unique identifier for the webhook
eventType string Type of event that triggered the webhook
timestamp string Timestamp indicating when the event occurred
data object The data related to this event

Enumeration

Blockchain

Name Blockchain
ethereum Ethereum
tron Tron
btc Bitcoin
bsc BNB Smart Chain

Entity Category

Name Code
Game game
Lending loan
Wallet wallet
Community community
Pool pool
Exchange exchange
Mixer mix
Hacker hack
OTC otc
Payment payments
Fraud scam
Gambling gambling
Swap trade
Quant quantitative
Cross-Chain cross-chain
Defi defi
Individual owner
Institution unsort-organ
Money Laundering launder-money
Online Gambling online-gambling
Finance finance
Sanction sanction
Organization organization
Market market

Risk Level

Name ID Description
high 4 super high risk
generally-high 3 generally high risk
low 1 low risk
whitelist 0 whitelist

Risk Type/Category

Code en zh-Hant
black-gray-goods Black-Gray Market 黑灰產
online-gambling Online Gambling 網賭
scam Fraud 欺詐
hack Hacking 駭客
launder-money Money Laundering 洗錢
sanction Sanctions 制裁
frozen Freeze 凍結
politics Political 涉政
drug Drug Trafficking 毒品買賣
gun Firearms Trafficking 槍支買賣
terrorist Terrorism Financing 恐怖主義融資
porn Pornography 色情
controlled-substance Controlled Substances 涉管制藥物
bloodiness Gore-related 涉血腥
religion Religion-related 涉宗教
csam CSAM 兒童性虐待材料

Asynchronous Task Status

Code Description
1000 Queueing
1001 In Progress
1002 Failed
1003 Completed

Errors

Bitrace AML API uses standard HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

HTTP Status Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Incorrect API key provided.
403 Forbidden -- The source IP address is not whitelisted.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
429 Too Many Requests --
1. Rate limit reached for requests.
2. You exceeded your current quota, please check your plan and billing details.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

API Error Codes

Error Code HTTP Status Code Error Message
3000 400 Not supported network or wallet address
3001 400 Not supported network
3002 400 Invalid wallet address
3003 400 Supports up to 100 addresses
3004 400 Transaction hash is not found
3005 400 Not supported token
3006 400 Not supported direction
3007 400 Not supported depth
3008 400 Not supported coinbase
3009 400 Not supported index
3010 400 ExternalId is not found
3011 400 The address cannot query the custom score
cURL NodeJS Python Go PHP Ruby