Creare un controllo AML

Crea un nuovo controllo AML per un indirizzo del wallet o per un hash di transazione specifico. Il prezzo del controllo viene riservato dal tuo saldo all’avvio del controllo e la risposta restituisce il controllo.

POST /v1/aml-checks/new

Richiesta

Parametri

Campo	Tipo	Obbligatorio	Descrizione
type	string	Sì	Tipo di servizio AML: `address` oppure `hash`
network	string	Sì	Codice della rete blockchain (vedi tabella)
address	string	Sì	Indirizzo valido per la rete selezionata. Per `type = hash` è l’indirizzo che partecipa alla transazione e di cui viene analizzato il lato (vedi `direction`).
hash	string	Condizionale*	Hash di transazione nel formato della rete selezionata (TRX: 64 caratteri esadecimali, senza prefisso `0x`; Ethereum e le altre reti EVM: `0x` e 64 caratteri esadecimali; il formato di ogni rete è mostrato dall’esempio nella tabella qui sotto). Obbligatorio quando `type` = `hash`
direction	string	Condizionale**	Quale lato della transazione viene analizzato per `address`: `deposit` — fondi in arrivo a quell’indirizzo, `withdrawal` — fondi in uscita da esso. Obbligatorio quando `type` = `hash`

* Solo per i controlli basati su hash.
** Solo per i controlli basati su hash. Non esiste un valore predefinito: un controllo hash senza una direction valida viene rifiutato.

Tipi di servizio supportati

Tipo	Descrizione
address	Analizza un indirizzo e calcola il relativo profilo di rischio
hash	Analizza una singola transazione dal lato di uno dei suoi indirizzi (`deposit` o `withdrawal`)

Reti supportate

Codice	Rete	Indirizzo di esempio	Hash di esempio
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

Tutte le reti di questo elenco vengono analizzate, allo stesso prezzo per controllo qualunque sia la rete. network non distingue maiuscole e minuscole (btc è BTC); address e hash vengono verificati secondo il formato della rete scelta. Un tipo di controllo non in vendita per il tuo progetto (vedi Ottenere i servizi AML), o una rete che il servizio di analisi non può accettare al momento, riceve il codice 35 e non viene addebitato nulla.

BashNode.jsPHPPython

bash

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

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

# Esegui la richiesta API
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}"

javascript

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'
});

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

// Esegui la richiesta API
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);

// Calcola la firma
$signature = hash('sha256', $requestBody . $apiSecret);

// Esegui la richiesta API
$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'
})

# Calcola la firma
signature = hashlib.sha256((request_body + api_secret).encode()).hexdigest()

# Esegui la richiesta API
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())

Esempio di richiesta per hash

BashNode.jsPHPPython

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"
}'

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

# Esegui la richiesta API
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}"

javascript

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'
});

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

// Esegui la richiesta API
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);

// Calcola la firma
$signature = hash('sha256', $requestBody . $apiSecret);

// Esegui la richiesta API
$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'
})

# Calcola la firma
signature = hashlib.sha256((request_body + api_secret).encode()).hexdigest()

# Esegui la richiesta API
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())

Risposta

La risposta restituisce il controllo AML. Se il risultato è ancora in fase di completamento, lo stato è pending: interroga Verificare lo stato AML con l’id restituito finché non cambia.

Campi della risposta

Campo	Tipo	Descrizione
code	integer	Codice di risposta (0 = successo)
request_id	string	Identificatore univoco della richiesta
result	object	Dati del controllo AML
result.id	string	Identificativo del controllo AML
result.type	string	Tipo di servizio AML (`address` oppure `hash`)
result.address	string	Indirizzo analizzato
result.network	string	Codice della rete blockchain come scritto nell’elenco delle reti supportate (ad es. `TRX`, `TetherOMNI`)
result.status	string	Stato del controllo (`pending`, `processing`, `completed`, `failed`, `expired`, `skipped`)
result.risk_score	string\|null	Punteggio di rischio come stringa con due decimali (ad es. `"12.50"`), oppure `null` finché non è disponibile un punteggio
result.risk_level	string\|null	Livello di rischio testuale (low, medium, high)
result.blacklist	boolean	`true` se viene rilevata una corrispondenza in blacklist
result.risk_factors	array	Categorie di rischio a cui sono collegati i fondi, ordinate per `score` decrescente, una voce per categoria; `[]` vuoto se non è stata segnalata alcuna categoria (ad esempio finché il controllo non è completato)
result.risk_factors[].name	string	Chiave della categoria, una di quelle elencate in Categorie dei fattori di rischio; una categoria fuori da questo elenco viene segnalata come `other`
result.risk_factors[].label	string	Etichetta inglese della categoria (non tradotta)
result.risk_factors[].group	string	Gruppo di rischio della categoria: `low`, `medium` o `high`
result.risk_factors[].score	number	Quota dei fondi collegata a questa categoria, da 0 a 1, arrotondata a 3 decimali
result.checked_at	string	Timestamp di creazione del controllo (ISO 8601)
result.hash	string	Hash analizzato (solo per i controlli hash)
result.direction	string	Lato della transazione analizzato, `deposit` o `withdrawal` (solo per i controlli hash)

L’elenco completo delle chiavi di categoria, con etichette e gruppi, si trova in Categorie dei fattori di rischio.

Esempio di risposta

json

{
  "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"
  }
}

Per un controllo hash, hash e direction seguono checked_at:

json

{
  "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"
  }
}

Addebiti e richieste ripetute

Il prezzo del controllo viene riservato all’avvio del controllo. Se il controllo non può essere eseguito — dati rifiutati o errore da parte nostra — la riserva viene restituita per intero.
Per un controllo hash, se address non partecipa alla transazione, il controllo viene rifiutato con il codice 2 (The address was not found in this transaction) e non viene addebitato nulla.
Per un controllo di indirizzo, se il servizio di controllo rifiuta di controllare l’indirizzo, il controllo viene rifiutato con il codice 2 (The screening service could not check this address; nothing was charged, chiave invalid_service_or_params, senza dettaglio) e non viene addebitato nulla. Verifica l’indirizzo e riprova più tardi.
Ripetere la stessa domanda entro un’ora — stessi type, network e address, e per i controlli hash anche stessi hash e direction — restituisce il controllo precedente senza alcun addebito.
Una seconda richiesta identica inviata mentre la prima è ancora in corso viene rifiutata con HTTP 503 (temporarily_unavailable) e non viene addebitato nulla. Riprova tra un momento.

Possibili errori

Codice errore	Key	Descrizione
1	`auth`	Errore di autenticazione (token o firma non validi)
2	`invalid_service_or_params`	Parametri non validi, verificati in questo ordine: `type`; `network` (`Unsupported network`); `address` (`Invalid address provided`); per i controlli hash `hash` (`Hash is required for hash checks`) e `direction` (`Invalid direction value`); per un controllo hash il cui `address` non partecipa alla transazione, `The address was not found in this transaction` (chiave `invalid_service_or_params.hash`), non viene addebitato nulla; per un controllo di indirizzo rifiutato dal servizio di controllo, `The screening service could not check this address; nothing was charged` (chiave `invalid_service_or_params`), non viene addebitato nulla
5	`wallet_not_found`	Wallet non trovato
6	`insufficient_funds`	Fondi insufficienti per eseguire il controllo
35	`service_unavailable`	Questo tipo di controllo o questa rete non è disponibile per il tuo progetto (ad esempio, un tipo di controllo non in vendita per il tuo progetto); non viene addebitato nulla
500	`internal_server_error`	Errore interno del server
503	`temporarily_unavailable`	Un controllo identico è ancora in corso (HTTP 503); non è stato addebitato nulla, riprova tra un momento

Abbonamenti

Controlli AML

Creare un controllo AML

Richiesta

Parametri

Tipi di servizio supportati

Reti supportate

Esempio di richiesta per hash

Risposta

Campi della risposta

Esempio di risposta

Addebiti e richieste ripetute

Possibili errori

Creare un controllo AML ​

Richiesta ​

Parametri ​

Tipi di servizio supportati ​

Reti supportate ​

Esempio di richiesta per hash ​

Risposta ​

Campi della risposta ​

Esempio di risposta ​

Addebiti e richieste ripetute ​

Possibili errori ​

Creare un controllo AML

Richiesta

Parametri

Tipi di servizio supportati

Reti supportate

Esempio di richiesta per hash

Risposta

Campi della risposta

Esempio di risposta

Addebiti e richieste ripetute

Possibili errori