GET /apiv2/compliance/

Tra cứu tuân thủ mở, không cần khóa cho một địa chỉ TRON duy nhất. Nó trả về một kết luận — địa chỉ có bị chặn hay không, và thuộc danh mục nào — được phục vụ hoàn toàn từ bộ nhớ đệm danh sách từ chối trong bộ nhớ (in-memory deny-list cache). Không cần API key, không cần số dư, không tính phí. Mục đích là cho phép bất kỳ ai cũng có thể tích hợp lớp tuân thủ chỉ với một lệnh HTTP GET.

Điểm cuối này chỉ đọc từ bộ nhớ đệm, không bao giờ truy vấn cơ sở dữ liệu hay node mạng chuỗi, do đó một lượt tra cứu chỉ mất một phần nhỏ của mili giây. Nó được giới hạn tần suất theo từng IP bởi cổng gateway.

URL của Endpoint

GET https://netts.io/apiv2/compliance/{address}

Không yêu cầu bất kỳ header xác thực nào.

Tham số yêu cầu

Parameter	Type	Required	Description
address	string	Yes	Địa chỉ TRON base58 — ký tự T theo sau bởi 33 ký tự

Ví dụ

cURL

curl https://netts.io/apiv2/compliance/TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL

Python

import requests

address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL"
r = requests.get(f"https://netts.io/apiv2/compliance/{address}")
data = r.json()

if r.status_code == 200:
    d = data["data"]
    print(f"blocked : {d['blocked']}")
    print(f"category: {d['category']}")
    if d["category"] == "aml_risk":
        print(f"reason  : {d.get('reason_code')} — {d.get('label')}")
else:
    print(f"Error: {data}")

JavaScript

const address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL";
const res = await fetch(`https://netts.io/apiv2/compliance/${address}`);
const { data } = await res.json();
console.log(data.blocked, data.category, data.label);

Phản hồi

Bị chặn — nằm trong danh sách từ chối trung tâm (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL",
        "blocked": true,
        "category": "aml_risk",
        "severity": "BLOCK",
        "reason_code": "SANCTIONS_SCREENING",
        "label": "DPRK Bitget Exploit - September 2026",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": ["aml_risk"],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Ví GasFree — một smart contract có thể nhận USDT (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TZEMF5vmSABaWjeUPty8kFpUsquMAKhGFp",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "gasfree_wallet",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T12:00:00+00:00"
    }
}

Hợp đồng đã bị xóa — địa chỉ vẫn được tính là một smart contract (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TBtrogXC58EAvE7vod56ZnzRY4y5jrwtbN",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "selfdestructed_contract",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

Sạch — không nằm trong bất kỳ tập hợp nào (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC",
        "blocked": false,
        "category": "clean",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": [],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Các trường phản hồi

Field	Type	Description
data.address	string	Địa chỉ đã được kiểm tra
data.blocked	boolean	true nếu địa chỉ nằm trong bất kỳ tập hợp chặn nào
data.category	string	aml_risk, usdt_frozen, smart_contract, spam_sender hoặc clean (xem bên dưới); điểm cuối xử lý hàng loạt cũng có thể trả về invalid hoặc unavailable
data.severity	string	Chỉ dành cho aml_risk. Ví dụ: BLOCK, REVIEW
data.reason_code	string	Chỉ dành cho aml_risk. Mã máy đọc, ví dụ: SANCTIONS_OFAC_SDN
data.label	string	Chỉ dành cho aml_risk. Nhãn con người có thể đọc
data.subtype	string | null	Chi tiết hơn cho smart_contract. gasfree_wallet — một ví GasFree đang hoạt động (xem Ví GasFree); selfdestructed_contract — hợp đồng tại địa chỉ này đã bị xóa (xem Hợp đồng đã bị xóa); null cho các trường hợp khác
data.subtype_status	string	confirmed — loại phụ đã được xác định qua trạng thái xác nhận mới nhất; not_found — không áp dụng loại phụ nào; unavailable — hiện không thể tham khảo danh sách loại phụ, nên subtype là null và không biểu thị thông tin
data.matches	string[]	Tất cả các tập hợp mà địa chỉ này thuộc về, theo thứ tự ưu tiên (ví dụ: ["usdt_frozen", "smart_contract", "spam_sender"]). category chỉ là mục đầu tiên trong số đó
data.checks_complete	boolean	true nếu toàn bộ bốn tập hợp đều đã được tải và cập nhật tại thời điểm tra cứu. false có nghĩa là kết quả clean dựa trên một quá trình kiểm tra chưa hoàn chỉnh
data.checked_at	string	Dấu thời gian UTC ISO-8601 của lần tra cứu

Các danh mục

category là một kết luận, không phải là một điểm số rủi ro. Khi một địa chỉ nằm trong nhiều hơn một tập hợp, danh mục nghiêm trọng nhất sẽ được chọn, theo thứ tự sau (tất cả đều được liệt kê trong matches):

Danh mục	blocked	Ý nghĩa
aml_risk	true	Nằm trong danh sách từ chối trung tâm: lệnh trừng phạt, lừa đảo, mã độc tống tiền, tài sản bị đánh cắp, gian lận, kết quả điều tra của cơ quan thực thi pháp luật hoặc vi phạm nội bộ. Có đính kèm lý do đã được kiểm duyệt
usdt_frozen	true	Địa chỉ bị đóng băng bởi đơn vị phát hành USDT (Tether). Địa chỉ không thể chuyển USDT, do đó việc ủy quyền tài nguyên cho nó sẽ bị từ chối
smart_contract	true	Một địa chỉ smart contract đã biết, bao gồm cả các hợp đồng đã bị xóa sau này. Xem lưu ý bên dưới
spam_sender	true	Người gửi thư rác hàng loạt đã được xác nhận
clean	false	Không nằm trong bất kỳ tập hợp nào
unavailable	null	Không thể tham khảo danh sách từ chối trung tâm, do đó địa chỉ không được xác nhận là sạch cũng như không bị chặn. Chỉ áp dụng cho hàng loạt; điểm cuối đơn địa chỉ sẽ trả về 503 kèm code 5004. Xem Danh sách từ chối trung tâm không khả dụng

Smart contract bị chặn vì lý do kỹ thuật, không phải vì lý do AML

Kết luận smart_contract có nghĩa là địa chỉ thuộc về một hợp đồng, không phải ví người dùng, do đó Energy không được ủy quyền cho nó và địa chỉ sẽ bị từ chối trước khi đơn hàng được tạo. Tập hợp này chứa mọi địa chỉ nơi một hợp đồng đã từng được tạo thành công, bao gồm cả các hợp đồng đã bị xóa sau này — một hợp đồng đã bị xóa không biến địa chỉ của nó thành ví người dùng. Điều này không có nghĩa là hợp đồng bị xâm phạm, bị vấy bẩn hoặc có rủi ro cao theo chuẩn AML. Hầu hết các hợp đồng trong tập hợp này hoàn toàn bình thường. Hãy coi smart_contract là "không phải đối tượng nhận ủy quyền", chứ không phải là cờ cảnh báo rủi ro.

Ví GasFree

Ví GasFree là một hợp đồng cho phép chủ sở hữu nhận và gửi token đồng thời thanh toán phí mạng lưới bằng chính các token đó. Mỗi ví được tạo bởi bộ điều khiển GasFree TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U. Một địa chỉ như vậy được báo cáo là category: "smart_contract" với subtype: "gasfree_wallet".

Sự khác biệt này rất quan trọng khi bạn định tuyến tiền:

	Smart contract thông thường	Ví GasFree
Gửi USDT đến địa chỉ này	không phải là người nhận bình thường	có — đây là ví của người dùng
Ủy quyền Energy cho địa chỉ này	không	không — chúng tôi không ủy quyền Energy cho các ví GasFree
category / subtype	smart_contract / null	smart_contract / gasfree_wallet

Phạm vi bảo đảm và lưu ý:

• Chỉ những ví đã triển khai mới được ghi nhận. Một địa chỉ GasFree đã nhận USDT nhưng chưa từng gửi bất kỳ giao dịch nào thì vẫn chưa được triển khai, do đó nó không nằm trong bất kỳ tập hợp nào và trả về kết quả là clean.
• Loại phụ mô tả nơi địa chỉ có thể nhận tiền. Nó không cho biết điều gì về các giao dịch chuyển tiền từ một ví GasFree; hãy sàng lọc địa chỉ người gửi một cách riêng biệt.
• subtype_status: "unavailable" có nghĩa là danh sách GasFree không thể tham khảo được vào lúc này. Phần còn lại của kết luận (blocked, category, matches) vẫn có hiệu lực.
• Bản thân bộ điều khiển và các hợp đồng khác không phải là ví GasFree: chúng trả về kết quả với subtype: null.

Hợp đồng đã bị xóa

Một hợp đồng có thể tự xóa chính nó (self-destruct). Địa chỉ vẫn nằm trong tập hợp smart_contract: nó từng là một địa chỉ hợp đồng, không phải ví người dùng, và Netts không ủy quyền tài nguyên hay gửi tiền chi trả đến đó. Địa chỉ như vậy được báo cáo là category: "smart_contract" với subtype: "selfdestructed_contract".

• confirmed có nghĩa là đã bị xóa theo trạng thái mới nhất được xác nhận bởi một TRON node. Đây không phải là một cam kết về tương lai: một hợp đồng có thể được triển khai lại tại cùng địa chỉ đó, và khi đó loại phụ sẽ bị xóa trong khi địa chỉ vẫn là một smart_contract.
• Chỉ riêng lệnh gọi self-destruct không đồng nghĩa với việc đã bị xóa: trên TRON, một hợp đồng được tạo trong giao dịch trước đó vẫn giữ nguyên mã của nó sau lệnh gọi này. Chỉ có trạng thái node mới có giá trị.
• Nếu một địa chỉ vừa là hợp đồng đã xóa vừa nằm trong danh sách GasFree, selfdestructed_contract sẽ được ưu tiên — địa chỉ sẽ không được báo cáo là ví GasFree đang hoạt động.
• subtype_status: "unavailable" có nghĩa là danh sách các hợp đồng đã xóa không thể tham khảo được; phần còn lại của kết luận vẫn có hiệu lực, và không có địa chỉ nào được xác nhận là ví GasFree cho đến khi danh sách có thể được tham khảo trở lại.

Mã lý do và nhà cung cấp dữ liệu

Đối với aml_risk, reason_code và label mô tả lý do địa chỉ bị đưa vào danh sách. Các cơ quan trừng phạt công khai được giữ nguyên — SANCTIONS_OFAC_SDN, SANCTIONS_EU_FSF, SANCTIONS_UK_FCDO, v.v. Tên của nhà cung cấp sàng lọc thương mại phía sau kết quả điều tra không bao giờ được tiết lộ: các mã như vậy được chuẩn hóa thành SANCTIONS_SCREENING, và mọi tên nhà cung cấp đều bị lược bỏ khỏi label.

Quy mô danh sách từ chối

GET https://netts.io/apiv2/compliance/stats

Tổng quy mô tổng hợp của các tập hợp phía sau kết luận, lấy từ cùng một bộ nhớ đệm. Công khai và không cần khóa.

{
    "code": 0,
    "status": "ok",
    "data": {
        "aml_risk": 1079,
        "usdt_frozen": 8022,
        "smart_contract": 7581686,
        "spam_sender": 27039018,
        "gasfree_wallets_subset": 512487,
        "selfdestructed_contracts_subset": 4065766,
        "total": 34629805,
        "revision": 1117,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

smart_contract là phần trung lập về AML lớn nhất trong tổng số — xem lưu ý về các hợp đồng ở trên. gasfree_wallets_subset (các ví GasFree đang hoạt động) và selfdestructed_contracts_subset (các hợp đồng đã bị xóa) là các tập hợp con của smart_contract; chúng không được cộng thêm vào total. Nếu một trong hai bộ đếm này hiện không thể đọc được, nó sẽ là null và các số liệu khác vẫn được trả về.

Tra cứu hàng loạt (API key)

Để kiểm tra nhiều địa chỉ cùng một lúc, hãy sử dụng điểm cuối hàng loạt đã được xác thực. Điểm cuối này ra đời nhằm tiết kiệm số lượt truyền nhận qua mạng: một yêu cầu duy nhất và một quy trình xử lý nội bộ thay vì N yêu cầu GET riêng lẻ. Một địa chỉ đơn lẻ chỉ đơn giản là một mảng có một phần tử.

POST https://netts.io/apiv2/compliance/batch
x-api-key: YOUR_KEY
Content-Type: application/json

{ "addresses": ["TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC"] }

Tối đa 1000 địa chỉ cho mỗi yêu cầu. Các kết luận được trả về theo đúng thứ tự đó, mỗi kết luận đều có cùng các trường như phản hồi đơn địa chỉ (bao gồm subtype, subtype_status, matches và checks_complete), cộng thêm category: "invalid" (kèm theo một trường error) cho bất kỳ mục nào sai định dạng — một mục lỗi không làm hỏng toàn bộ đợt xử lý. Nếu danh sách từ chối trung tâm chưa được tải, một địa chỉ vốn dĩ sạch sẽ được trả về dưới dạng category: "unavailable" (blocked: null, kèm trường error) thay vì clean — xem Danh sách từ chối trung tâm không khả dụng.

{
    "code": 0,
    "status": "ok",
    "data": {
        "count": 2,
        "checked_at": "2026-09-27T12:00:00+00:00",
        "results": [
            { "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "blocked": true, "category": "aml_risk", "subtype": null, "subtype_status": "not_found", "matches": ["aml_risk"], "checks_complete": true, "severity": "BLOCK", "reason_code": "SANCTIONS_SCREENING", "label": "DPRK Bitget Exploit - September 2026" },
            { "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC", "blocked": false, "category": "clean", "subtype": null, "subtype_status": "not_found", "matches": [], "checks_complete": true }
        ]
    }
}

Điểm cuối hàng loạt yêu cầu một API key (header x-api-key) và khóa này có thể tùy chọn ràng buộc với một danh sách trắng IP (IP whitelist). Hãy liên hệ với chúng tôi để nhận khóa.

Giới hạn tần suất của nó được tính trên mỗi khóa và cao hơn so với điểm cuối đơn địa chỉ công khai:

Chu kỳ	Giới hạn
1 giây	200 yêu cầu
1 phút	12.000 yêu cầu

Mỗi yêu cầu có thể chứa tối đa 1000 địa chỉ, vì vậy một khóa duy nhất có thể sàng lọc hơn một trăm nghìn địa chỉ mỗi giây trong phạm vi giới hạn này.

Phản hồi lỗi

Định dạng địa chỉ không hợp lệ (400)

{
    "code": 1001,
    "status": "error",
    "msg": "Invalid TRON address format (expected base58, 'T' + 33 chars)"
}

Dịch vụ tạm thời không khả dụng (503)

{
    "code": 5003,
    "status": "error",
    "msg": "compliance service temporarily unavailable"
}

Danh sách từ chối trung tâm không khả dụng (503, mã 5004)

Kết luận được phục vụ từ bộ nhớ đệm trong bộ nhớ. Nếu bộ nhớ đệm đó có thể truy cập được nhưng danh sách từ chối AML trung tâm hiện chưa được tải, hoặc bản sửa đổi hiện tại của nó không vượt qua được bước kiểm tra tính toàn vẹn, điểm cuối sẽ không tự động chuyển về clean — điều đó sẽ báo cáo một địa chỉ chưa được kiểm tra là an toàn. Thay vào đó, nó sẽ thông báo rõ ràng cho bạn biết rằng không thể đưa ra kết luận:

{
    "code": 5004,
    "status": "error",
    "msg": "compliance deny-list temporarily unavailable, verdict cannot be produced"
}

Điều này có nghĩa là: địa chỉ không được xác nhận là sạch cũng như không bị chặn. Dịch vụ hiện chưa thể sàng lọc nó dựa trên danh sách trừng phạt/AML. Đừng coi địa chỉ này là sạch — hãy thử lại sau ít phút.

Một lệnh chặn dứt khoát vẫn được trả về bình thường: nếu địa chỉ khớp với danh sách USDT bị đóng băng, smart contract hoặc danh sách gửi spam (các tập hợp không phụ thuộc vào danh sách trung tâm), bạn vẫn nhận được kết luận blocked: true như thường lệ ngay cả trong trạng thái này. Chỉ kết quả đáng lẽ là clean mới trở thành 5004.

Trong điểm cuối hàng loạt, tình huống tương tự được báo cáo cho từng địa chỉ dưới dạng category: "unavailable" (blocked: null, kèm trường error); phần còn lại của đợt xử lý không bị ảnh hưởng. Đây là một trạng thái hiếm gặp và chỉ mang tính tạm thời.

Cơ quan đăng ký không khả dụng (503, mã 5005)

Các tập hợp được cập nhật trực tiếp tại chỗ và vẫn có thể đọc được trong khi cập nhật, do đó một lần cập nhật định kỳ không bao giờ ảnh hưởng đến kết luận. Chỉ khi một tập hợp áp dụng thất bại thì một địa chỉ vốn dĩ sạch mới không thể được xác nhận là sạch. Khi đó, điểm cuối đơn địa chỉ sẽ trả về:

{
    "code": 5005,
    "status": "error",
    "msg": "address registry temporarily unavailable, verdict cannot be produced, retry shortly"
}

Tương tự như 5004, một lệnh chặn dứt khoát vẫn được trả về bình thường, và điểm cuối hàng loạt sẽ báo cáo trường hợp này theo từng địa chỉ dưới dạng category: "unavailable". Hãy thử lại sau.

Bảng tra cứu mã lỗi

Code	Description	HTTP Status
0	Thành công	200
1001	Định dạng địa chỉ TRON không hợp lệ	400
5003	Backend bộ nhớ đệm tạm thời không khả dụng	503
5004	Danh sách từ chối trung tâm chưa được tải — không thể đưa ra kết luận (thử lại)	503
5005	Áp dụng một tập hợp thất bại — không thể đưa ra kết luận (thử lại)	503

Giới hạn tốc độ

Có hai bậc giới hạn, được thực thi tại cổng gateway:

Điểm cuối	Xác thực	Giới hạn theo	1 giây	1 phút
GET /apiv2/compliance/{address}	mở, không cần khóa	IP	10	300
GET /apiv2/compliance/stats	mở, không cần khóa	IP	10	300
POST /apiv2/compliance/batch	API key	khóa	200	12.000

Điểm cuối đơn địa chỉ mở được thiết kế cho mục đích sử dụng tương tác và lập trình nhẹ. Đối với việc sàng lọc số lượng lớn, hãy sử dụng điểm cuối hàng loạt: với tối đa 1000 địa chỉ cho mỗi yêu cầu và 200 yêu cầu/giây trên mỗi khóa, một khóa duy nhất có thể sàng lọc hơn hàng trăm nghìn địa chỉ mỗi giây. Cần nhiều hơn? Giới hạn trên mỗi khóa là một thiết lập chính sách, không phải là giới hạn trần kỹ thuật — hãy liên hệ với chúng tôi.

Vượt quá giới hạn tần suất (429)

{
    "message": "API rate limit exceeded"
}

Ghi chú

• Không cần xác thực và không tốn phí. Bất kỳ ai cũng có thể gọi; không có gì cần phải ký duyệt.
• Chỉ sử dụng bộ nhớ đệm. Kết luận không bao giờ chạm vào cơ sở dữ liệu hay node mạng, vì vậy nó rất nhanh và an toàn để thăm dò liên tục trong phạm vi giới hạn tần suất.
• Không phải là một báo cáo AML đầy đủ. Để có điểm số rủi ro, phân tích mức độ phơi nhiễm và một báo cáo đã ký, hãy sử dụng API sàng lọc có xác thực (POST /apiv2/screening). Điểm cuối này chỉ trả lời một câu hỏi hẹp hơn: địa chỉ có nằm trong danh sách từ chối của chúng tôi không, và tại sao.