Create AML Check

Create a new AML screening for a wallet address or a specific transaction hash. The price of the check is reserved from your balance when the check starts, and the response returns the check.

POST /v1/aml-checks/new

Request

Request Parameters

Field	Type	Required	Description
type	string	Yes	AML service type: address or hash
network	string	Yes	Blockchain network code (see list below)
address	string	Yes	Valid address for the selected network. For type = hash, this is the address taking part in the transaction whose side is screened (see direction).
hash	string	Conditional*	Transaction hash in the selected network's format (TRX: 64 hex characters, no 0x prefix; Ethereum and the other EVM networks: 0x and 64 hex characters; every network's format is shown by the example in the table below). Required when type = hash
direction	string	Conditional**	Which side of the transaction is screened for address: deposit — funds arriving to that address, withdrawal — funds leaving it. Required when type = hash

* Only for transaction hash checks.
** Only for transaction hash checks. There is no default: a hash check without a valid direction is refused.

Supported Service Types

Type	Description
address	Screen a wallet address and calculate its risk profile
hash	Screen a single transaction from the side of one of its addresses (deposit or withdrawal)

Supported Networks

Code	Network	Address example	Hash example
TRX	TRON	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t	fd4f300e12040089f624353cdfe7c2ae7ed2378fa65c7e5cce60f69cb1d43bab
BTC	Bitcoin	bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
ETH	Ethereum	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
BSC	BNB Chain	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
SOL	Solana	TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA	5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
TON	TON	EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N	fd4f300e12040089f624353cdfe7c2ae7ed2378fa65c7e5cce60f69cb1d43bab
MATIC	Polygon	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
ARB	Arbitrum	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
BASE	Base	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
OP	Optimism	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
AVAX	Avalanche C-Chain	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
LTC	Litecoin	LQTpS3VaYTjCr4s9Y1t5zbeY26zevf7Fb3	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
XRP	Ripple	rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh	E3FE6EA3D48F0C2B639448020EA4F03D4F4F8FFDB243A852A0F59177921B4879
ALGO	Algorand	VCMJKWOY5P5P7SKMZFFOCEROPJCZOTIJMNIYNUCKH7LRO45JMJP6UYBIJA	UITN53MFMO6QHK6GCAUMF5MXBJG4OB6S3VCHTGFY5PQGHNWJ5NWQ
APT	Aptos	0x0000000000000000000000000000000000000000000000000000000000000001	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
BCH	Bitcoin Cash	bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
BSV	Bitcoin SV	1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
ADA	Cardano	addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x	8a5a6f0e9c5d7c4e1b62ef2b36d03b34f2b0b6f9f6c7e7a3d55b0f5c8a3b2c1d
CELO	Celo	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
DOGE	Dogecoin	DH5yaieqoZN36fDVciNyRueRGvGLR3mr7L	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
ETC	Ethereum Classic	0x742d35Cc6634C0532925a3b844Bc454e4438f44e	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
NEAR	NEAR	alice.near	6zgh2u9DqHHiXzdy9ouTP7oGky2T4nugqzqt9wJZwNFm
DOT	Polkadot	15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5	0x0f61ba2c923f4113a91eec9a9ce6145866e18b91dab5d2899dbe586a1847652b
XLM	Stellar	GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN7	3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889
TetherOMNI	Tether (Omni)	1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
XTZ	Tezos	tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	onvsLP3JFZia2mzZKWaFuFkWg2L5p3BDUhzh5Kr6CiDDN3rtQ1D
ZEC	Zcash	t1Rv4exT7bqhZqi2j7xz8bUHDMxwosrjADU	4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b

TIP

Every network in this list is screened, at the same price per check whatever the network. network is not case-sensitive (btc is BTC); address and hash are checked against the selected network's format. A check type that is not on sale for your project (see Get AML Services), or a network the screening service cannot take at the moment, is answered with code 35 and nothing is charged.

Bash

#!/bin/bash
API_TOKEN="your_api_token"
API_SECRET="your_api_secret"
REQUEST_BODY='{
  "type": "address",
  "network": "TRX",
  "address": "TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D"
}'

# Calculate signature
SIGNATURE=$(echo -n "${REQUEST_BODY}${API_SECRET}" | sha256sum | cut -d' ' -f1)

# Make API request
curl -X POST "https://api.trxup.com/v1/aml-checks/new" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "X-Signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"

Node.js

const crypto = require('crypto');
const axios = require('axios');

const apiToken = 'your_api_token';
const apiSecret = 'your_api_secret';
const requestBody = JSON.stringify({
  type: 'address',
  network: 'TRX',
  address: 'TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D'
});

// Calculate signature
const signature = crypto
  .createHash('sha256')
  .update(requestBody + apiSecret)
  .digest('hex');

// Make API request
axios({
  method: 'post',
  url: 'https://api.trxup.com/v1/aml-checks/new',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  data: requestBody
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

PHP

<?php
$apiToken = 'your_api_token';
$apiSecret = 'your_api_secret';
$requestBody = json_encode([
  'type' => 'address',
  'network' => 'TRX',
  'address' => 'TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D',
], JSON_UNESCAPED_SLASHES);

// Calculate signature
$signature = hash('sha256', $requestBody . $apiSecret);

// Make API request
$ch = curl_init('https://api.trxup.com/v1/aml-checks/new');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $apiToken,
  'X-Signature: ' . $signature,
  'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import hashlib
import json
import requests

api_token = 'your_api_token'
api_secret = 'your_api_secret'
request_body = json.dumps({
  'type': 'address',
  'network': 'TRX',
  'address': 'TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D'
})

# Calculate signature
signature = hashlib.sha256((request_body + api_secret).encode()).hexdigest()

# Make API request
headers = {
  'Authorization': f'Bearer {api_token}',
  'X-Signature': signature,
  'Content-Type': 'application/json'
}

response = requests.post(
  'https://api.trxup.com/v1/aml-checks/new',
  headers=headers,
  data=request_body
)

print(response.json())

Example Request for Hash Screening

Bash

#!/bin/bash
API_TOKEN="your_api_token"
API_SECRET="your_api_secret"
REQUEST_BODY='{
  "type": "hash",
  "network": "TRX",
  "address": "TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D",
  "hash": "E3F2A1B66DBB9F0B24C4125229163944A7D91EB3F1AC5E409FFCEE0C81A913F2",
  "direction": "withdrawal"
}'

# Calculate signature
SIGNATURE=$(echo -n "${REQUEST_BODY}${API_SECRET}" | sha256sum | cut -d' ' -f1)

# Make API request
curl -X POST "https://api.trxup.com/v1/aml-checks/new" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "X-Signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"

Node.js

const crypto = require('crypto');
const axios = require('axios');

const apiToken = 'your_api_token';
const apiSecret = 'your_api_secret';
const requestBody = JSON.stringify({
  type: 'hash',
  network: 'TRX',
  address: 'TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D',
  hash: 'E3F2A1B66DBB9F0B24C4125229163944A7D91EB3F1AC5E409FFCEE0C81A913F2',
  direction: 'withdrawal'
});

// Calculate signature
const signature = crypto
  .createHash('sha256')
  .update(requestBody + apiSecret)
  .digest('hex');

// Make API request
axios({
  method: 'post',
  url: 'https://api.trxup.com/v1/aml-checks/new',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  data: requestBody
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

PHP

<?php
$apiToken = 'your_api_token';
$apiSecret = 'your_api_secret';
$requestBody = json_encode([
  'type' => 'hash',
  'network' => 'TRX',
  'address' => 'TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D',
  'hash' => 'E3F2A1B66DBB9F0B24C4125229163944A7D91EB3F1AC5E409FFCEE0C81A913F2',
  'direction' => 'withdrawal'
], JSON_UNESCAPED_SLASHES);

// Calculate signature
$signature = hash('sha256', $requestBody . $apiSecret);

// Make API request
$ch = curl_init('https://api.trxup.com/v1/aml-checks/new');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $apiToken,
  'X-Signature: ' . $signature,
  'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import hashlib
import json
import requests

api_token = 'your_api_token'
api_secret = 'your_api_secret'
request_body = json.dumps({
  'type': 'hash',
  'network': 'TRX',
  'address': 'TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D',
  'hash': 'E3F2A1B66DBB9F0B24C4125229163944A7D91EB3F1AC5E409FFCEE0C81A913F2',
  'direction': 'withdrawal'
})

# Calculate signature
signature = hashlib.sha256((request_body + api_secret).encode()).hexdigest()

# Make API request
headers = {
  'Authorization': f'Bearer {api_token}',
  'X-Signature': signature,
  'Content-Type': 'application/json'
}

response = requests.post(
  'https://api.trxup.com/v1/aml-checks/new',
  headers=headers,
  data=request_body
)

print(response.json())

Response

The response returns the AML check. If the result is still being finished, the status is pending: poll Check AML Status with the returned id until it changes.

Response Fields

Field	Type	Description
code	integer	Response code (0 = success)
request_id	string	Unique request identifier
result	object	Screened AML check data
result.id	string	AML check identifier
result.type	string	AML service type (address or hash)
result.address	string	Screened address
result.network	string	Blockchain network code as written in the list of supported networks (e.g. TRX, TetherOMNI)
result.status	string	AML check status (pending, processing, completed, failed, expired, skipped)
result.risk_score	string|null	Risk score as a string with two decimals (e.g. "12.50"), or null when there is no score yet
result.risk_level	string|null	Textual risk level (low, medium, high)
result.blacklist	boolean	true if the address or hash appears on a blacklist
result.risk_factors	array	Risk categories the funds are linked to, largest score first, one entry per category; empty [] when no categories were reported (for example, while the check has not completed)
result.risk_factors[].name	string	Category key, one of the keys listed in Risk Factor Categories; a category outside that list is reported as other
result.risk_factors[].label	string	English label of the category (not translated)
result.risk_factors[].group	string	Risk group of the category: low, medium or high
result.risk_factors[].score	number	Share of the funds linked to this category, from 0 to 1, rounded to 3 decimals
result.checked_at	string	Timestamp when the check was created (ISO 8601)
result.hash	string	Screened transaction hash (hash checks only)
result.direction	string	Screened side of the transaction, deposit or withdrawal (hash checks only)

The full list of category keys, with their labels and groups, is in Risk Factor Categories.

Example Response

{
  "code": 0,
  "request_id": "bbf74bcd-fb36-4df8-adc8-25f2bacd087b",
  "result": {
    "id": "1041",
    "type": "address",
    "address": "TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D",
    "network": "TRX",
    "status": "completed",
    "risk_score": "12.50",
    "risk_level": "medium",
    "blacklist": false,
    "risk_factors": [
      {
        "name": "exchange",
        "label": "Exchange",
        "group": "low",
        "score": 0.9
      },
      {
        "name": "p2p_exchange_mlrisk_high",
        "label": "P2P Exchange (High Risk)",
        "group": "medium",
        "score": 0.1
      }
    ],
    "checked_at": "2024-03-25T10:40:05+00:00"
  }
}

For a hash check, hash and direction follow checked_at:

{
  "code": 0,
  "request_id": "bbf74bcd-fb36-4df8-adc8-25f2bacd087b",
  "result": {
    "id": "1042",
    "type": "hash",
    "address": "TPY1Kb8cKAZQfm95gXQQs2Mh8Uygtos21D",
    "network": "TRX",
    "status": "pending",
    "risk_score": null,
    "risk_level": null,
    "blacklist": false,
    "risk_factors": [],
    "checked_at": "2024-03-25T10:42:12+00:00",
    "hash": "E3F2A1B66DBB9F0B24C4125229163944A7D91EB3F1AC5E409FFCEE0C81A913F2",
    "direction": "withdrawal"
  }
}

Charges and Repeated Requests

• The price of the check is reserved when the check starts. If the check cannot be run — the input is refused or the error is on our side — the reservation is returned in full.
• For a hash check, if address does not take part in the transaction, the check is refused with code 2 (The address was not found in this transaction) and nothing is charged.
• For an address check, if the screening service declines to check the address, the check is refused with code 2 (The screening service could not check this address; nothing was charged, key invalid_service_or_params, no detail) and nothing is charged. Check the address and try again later.
• Repeating the same question within one hour — the same type, network and address, and for hash checks also the same hash and direction — returns the earlier check and charges nothing.
• A second identical request sent while the first one is still running is refused with HTTP 503 (temporarily_unavailable) and nothing is charged. Retry in a moment.

Possible Errors

Error Code	Key	Description
1	auth	Authentication error (incorrect token or signature)
2	invalid_service_or_params	Invalid parameters, checked in this order: type; network (Unsupported network); address (Invalid address provided); for hash checks hash (Hash is required for hash checks) and direction (Invalid direction value); for a hash check whose address does not take part in the transaction, The address was not found in this transaction (key invalid_service_or_params.hash), nothing is charged; for an address check the screening service declined, The screening service could not check this address; nothing was charged (key invalid_service_or_params), nothing is charged
5	wallet_not_found	Wallet not found
6	insufficient_funds	Insufficient funds to run the check
35	service_unavailable	This check type or network is not available for your project (for example, a check type that is not on sale for your project); nothing is charged
500	internal_server_error	Internal server error
503	temporarily_unavailable	An identical check is still running (HTTP 503); nothing was charged, retry in a moment