Documentation API

API WebSocket en temps réel pour la surveillance des événements de blocage USDT/USDC sur les réseaux Tron et Ethereum.

v1.0wss://api.usdtbanlist.com/ws

Démarrage

Connectez-vous au point de terminaison WebSocket pour recevoir les événements de blocage en temps réel et interroger les informations d'adresse.

Point de terminaison WebSocket

wss://api.usdtbanlist.com/ws?apiKey=YOUR_API_KEY

🔑

Obtenez votre clé API

Go to your Account → Profile to generate an API key, or use @USDTBanBot on Telegram.

Authentification

Incluez votre clé API dans l'URL de connexion ou envoyez un message d'authentification après la connexion.

Option 1 : Paramètre d'URL (recommandé)

wss://api.usdtbanlist.com/ws?apiKey=mk_your_api_key_here

Option 2 : Message d'authentification

{
  "type": "auth",
  "apiKey": "mk_your_api_key_here"
}

Réponse de connexion

{
  "type": "connected",
  "clientId": "client_xxx",
  "authenticated": true,
  "tier": "free"
}

Événements

Une fois connecté et authentifié, vous recevrez les événements de blocage en temps réel.

⚠️

Important

Les événements en temps réel ne sont envoyés que pour les adresses de votre liste de surveillance. Ajoutez des adresses via @USDTBanBot (section Portefeuilles), Tableau de bord, Telegram Mini App.

Type d'événement	Description	Niveau
`ban_submitted`	Blocage en attente dans le multisig	Premium
`ban_executed`	Adresse bloquée (confirmé)	Gratuit
`unban_submitted`	Déblocage en attente dans le multisig	Premium
`unban_executed`	Adresse débloquée	Gratuit
`destroy_submitted`	Destruction de fonds en attente dans le multisig	Premium
`destroy_executed`	Fonds détruits depuis l'adresse bloquée	Gratuit

Format des messages d'événement

{
  "type": "event",
  "event": {
    "id": "uuid",
    "network": "trx",
    "eventType": "ban_executed",
    "address": "41...",
    "addressBase58": "T...",
    "symbol": "USDT",
    "txHash": "...",
    "blockNumber": 12345678,
    "timestamp": "2024-01-15T12:00:00Z",
    "amount": "1234.56",
    "amountRaw": "1234560000"
  }
}

Méthodes JSON-RPC

Envoyez des requêtes JSON-RPC 2.0 pour interroger les données et gérer les abonnements.

ping

Vérifier l'état de la connexion

Request

{ "jsonrpc": "2.0", "id": 1, "method": "ping" }

Response

{ "jsonrpc": "2.0", "id": 1, "result": "pong" }

getStatus

Obtenir l'état actuel de la connexion et les infos de limite de débit

Request

{ "jsonrpc": "2.0", "id": 1, "method": "getStatus" }

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "tier": "free",
    "subscriptions": ["all"],
    "rateLimit": { "used": 5, "limit": 10, "windowMs": 60000 }
  }
}

subscribe

S'abonner aux canaux d'événements

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "subscribe",
  "params": { "channels": ["all"] }
}

Response

{ "jsonrpc": "2.0", "id": 1, "result": { "subscribed": ["all"], "total": 1 } }

unsubscribe

Se désabonner des canaux

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "unsubscribe",
  "params": { "channels": ["eth"] }
}

Response

{ "jsonrpc": "2.0", "id": 1, "result": { "unsubscribed": ["eth"], "remaining": 1 } }

checkAddress

Vérifier si une adresse est bloquée

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "checkAddress",
  "params": { "address": "TLJpijVuVyjAtKRahhGTAFkpZxfpzHMtWe" }
}

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "address": "TLJpijVuVyjAtKRahhGTAFkpZxfpzHMtWe",
    "network": "trx",
    "isBanned": false,
    "usdt_status": "active",
    "usdt_balance": "0.00",
    "tag": { "type": "Exchange", "tag": "Binance" },
    "events": [{ "event_name": "Block", "volume": "1234.56", "symbol": "USDT", "status": "executed" }],
    "walletScore": { "totalScore": 45, "riskLevel": "medium" },
    "connections": { "totalConnections": 3, "categories": ["Blacklist"] }
  }
}

amlCheck$1.50

AML compliance check for a wallet address — risk score, fund sources breakdown

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "amlCheck",
  "params": { "address": "TGpnJAXqxmMoPQhaKcPN3jc6nDYbbiyYCz" }
}

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "address": "TGpnJAXqxmMoPQhaKcPN3jc6nDYbbiyYCz",
    "network": "tron",
    "riskScore": 75,
    "riskLevel": "high",
    "sources": {
      "byType": [{ "name": "Cross-chain protocol", "share": 85.2 }, { "name": "Exchange", "share": 14.8 }],
      "byName": [{ "name": "Swft Swap", "share": 85.2 }, { "name": "OKX", "share": 14.8 }]
    },
    "details": {
      "directTxCount": 14, "depth": 3, "totalVolume": 225046.97,
      "flags": ["risky", "has_risky_sources"], "riskySourcesCount": 9
    },
    "price": 1.50,
    "balanceAfter": 8.50
  }
}

txCheck$1.50

AML compliance check for a transaction — trace fund sources (USDT/USDC only)

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "txCheck",
  "params": {
    "txHash": "a1b2c3d4e5f6...64_hex_chars",
    "direction": 0
  }
}

// direction: 0 = Source of Funds (default), 1 = Use of Funds
// Supported: USDT on TRON, USDT/USDC on Ethereum
// Network is auto-detected: 0x-prefix → Ethereum, plain hex → TRON

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "txHash": "a1b2c3d4...",
    "network": "tron",
    "direction": 0,
    "riskScore": 82,
    "riskLevel": "high",
    "sources": {
      "byType": [{ "name": "Mixing service", "share": 65.3 }, { "name": "Exchange", "share": 34.7 }],
      "byName": [{ "name": "Tornado Cash", "share": 65.3 }, { "name": "Binance", "share": 34.7 }]
    },
    "details": { "timestamp": 1716500000 },
    "price": 1.50,
    "balanceAfter": 7.00
  }
}

getAddressInfo

Obtenir des informations détaillées sur une adresse

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "getAddressInfo",
  "params": { "address": "T...", "network": "trx" }
}

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "address": "T...", "network": "trx",
    "info": { "label": "Exchange", "firstSeen": "2023-01-15" },
    "cached": true
  }
}

Wallet Monitoring

Manage your monitoring list — addresses that trigger real-time ban/unban event delivery. Up to 20 addresses per account.

wallets.list

List all monitored addresses

Request

{ "jsonrpc": "2.0", "id": 1, "method": "wallets.list" }

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "count": 2, "limit": 20,
    "wallets": [
      { "address": "TN1s8MwSd7TVWGS4sfWgaKJkpKaFExnRUB", "network": "tron", "label": "Hot wallet", "notificationsEnabled": true, "createdAt": "2026-05-01T10:30:00.000Z" },
      { "address": "0x5754284f345afc66a98fbb0a0afe71e0f007b949", "network": "ethereum", "label": null, "notificationsEnabled": true, "createdAt": "2026-04-28T08:15:00.000Z" }
    ]
  }
}

wallets.add

Add address to monitoring list

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "wallets.add",
  "params": { "address": "TN1s8MwSd7TVWGS4sfWgaKJkpKaFExnRUB", "label": "Hot wallet" }
}

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "address": "TN1s8MwSd7TVWGS4sfWgaKJkpKaFExnRUB", "network": "tron",
    "label": "Hot wallet", "notificationsEnabled": true, "createdAt": "2026-05-01T10:30:00.000Z"
  }
}

wallets.update

Update label or notification settings

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "wallets.update",
  "params": { "address": "TN1s8MwSd7TVWGS4sfWgaKJkpKaFExnRUB", "label": "Cold storage", "notificationsEnabled": false }
}

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "address": "TN1s8MwSd7TVWGS4sfWgaKJkpKaFExnRUB", "network": "tron",
    "label": "Cold storage", "notificationsEnabled": false, "createdAt": "2026-05-01T10:30:00.000Z"
  }
}

wallets.delete

Remove address from monitoring

Request

{
  "jsonrpc": "2.0", "id": 1,
  "method": "wallets.delete",
  "params": { "address": "TN1s8MwSd7TVWGS4sfWgaKJkpKaFExnRUB" }
}

Response

{ "jsonrpc": "2.0", "id": 1, "result": { "deleted": true } }

Limites de débit

Niveau	Requêtes RPC	Événements
Gratuit	10 / minute	Exécutés uniquement
Premium	100 / minute	Tous les événements (en attente + exécutés)

Error Codes

Errors follow JSON-RPC 2.0 format with numeric codes.

Code	Message	Description
`-32000`	Rate limit exceeded	Too many requests per minute / wallet limit reached
`-32003`	Authentication required	Missing or invalid API key
`-32004`	Not found	Wallet not found in monitoring list
`-32010`	Insufficient balance	Not enough balance for paid method (amlCheck, txCheck)
`-32600`	Invalid request	Malformed JSON-RPC request
`-32601`	Method not found	Unknown method name
`-32602`	Invalid params	Missing or invalid parameters
`-32603`	Internal error	Server-side error

Error Response Example

{
  "jsonrpc": "2.0", "id": 1,
  "error": {
    "code": -32010,
    "message": "Insufficient balance",
    "data": { "balance": 0, "price": 1.5 }
  }
}

Exemples

JavaScript / Node.js

example.js

const WebSocket = require('ws');

const API_KEY = 'mk_your_api_key';
const ws = new WebSocket(`wss://api.usdtbanlist.com/ws?apiKey=${API_KEY}`);

ws.on('open', () => {
  console.log('Connected');
  // Subscribe to TRX events
  ws.send(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'subscribe', params: { channels: ['trx'] } }));
  // AML check on wallet address (costs $1.50)
  ws.send(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'amlCheck', params: { address: 'T...' } }));
  // AML check on transaction hash (costs $1.50)
  ws.send(JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'txCheck', params: { txHash: '...64hex...' } }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'event') console.log('Ban event:', msg.event.eventType, msg.event.addressBase58);
  if (msg.id === 2 && msg.result) console.log('Address AML:', msg.result.riskScore, msg.result.riskLevel);
  if (msg.id === 3 && msg.result) console.log('Tx AML:', msg.result.riskScore, msg.result.riskLevel);
});

Python

example.py

import json, websocket

API_KEY = 'mk_your_api_key'

def on_message(ws, message):
    msg = json.loads(message)
    if msg.get('type') == 'event':
        print(f"Ban: {msg['event']['eventType']} - {msg['event'].get('addressBase58', msg['event']['address'])}")
    if msg.get('type') == 'connected' and msg.get('authenticated'):
        ws.send(json.dumps({ 'jsonrpc': '2.0', 'id': 1, 'method': 'amlCheck', 'params': {'address': 'T...'} }))

ws = websocket.WebSocketApp(f"wss://api.usdtbanlist.com/ws?apiKey={API_KEY}", on_message=on_message)
ws.run_forever()

Besoin d'aide ?

Contactez-nous sur Telegram pour du support ou des demandes de fonctionnalités.

Contacter le support