GET /apiv2/compliance/

针对单个 TRON 地址的公开、无需密钥的合规查询。它完全由内存黑名单缓存提供服务，返回裁决结果——该地址是否被封禁，以及属于哪个类别。无需 API 密钥，无需余额，完全免费。 其目的是让任何人都能通过一次 HTTP GET 请求集成合规层。

该端点仅读取缓存，绝不访问数据库或区块链节点，因此查询仅需不到一毫秒的时间。网关会针对每个 IP 对其进行速率限制。

端点 URL

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

无需任何身份验证请求头。

请求参数

Parameter	Type	Required	Description
address	string	Yes	TRON base58 地址——以 `T` 开头后接 33 个字符

示例

cURL

bash

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

Python

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

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

响应

已封禁——位于中央黑名单中 (200 OK)

json

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

GasFree 钱包——可接收 USDT 的智能合约 (200 OK)

json

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

已删除合约——该地址仍算作智能合约 (200 OK)

json

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

正常——不在任何集合中 (200 OK)

json

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

响应字段

Field	Type	Description
data.address	string	被检查的地址
data.blocked	boolean	如果地址存在于任何封禁集合中，则为 `true`
data.category	string	`aml_risk`、`usdt_frozen`、`smart_contract`、`spam_sender` 或 `clean`（见下文）；批量端点还可能返回 `invalid` 或 `unavailable`
data.severity	string	仅适用于 `aml_risk`。例如 `BLOCK`、`REVIEW`
data.reason_code	string	仅适用于 `aml_risk`。机器代码，例如 `SANCTIONS_OFAC_SDN`
data.label	string	仅适用于 `aml_risk`。人类可读的标签
data.subtype	string \| null	细化 `smart_contract`。`gasfree_wallet` — 活跃的 GasFree 钱包（见 GasFree 钱包）；`selfdestructed_contract` — 该地址的合约已被删除（见已删除合约）；其他情况为 `null`
data.subtype_status	string	`confirmed` — 子类型通过最新确认状态已知；`not_found` — 两种子类型均不适用；`unavailable` — 当前无法查阅子类型列表，因此 `subtype` 为 `null` 且不代表任何含义
data.matches	string[]	地址所在的所有集合，按优先级排序（例如 `["usdt_frozen", "smart_contract", "spam_sender"]`）。`category` 仅为其中的第一项
data.checks_complete	boolean	如果查询时所有四个集合均已加载且处于最新状态，则为 `true`。`false` 意味着 `clean` 结果基于不完整的检查
data.checked_at	string	查询的 UTC ISO-8601 时间戳

类别

category 是一项裁决，而非风险评分。当一个地址属于多个集合时，以最严重的类别为准，优先级顺序如下（所有类别均列在 matches 中）：

Category	`blocked`	含义
`aml_risk`	true	位于中央黑名单中：制裁、诈骗、勒索软件、被盗资产、欺诈、执法部门或内部滥用调查结果。附带经整理的原因
`usdt_frozen`	true	地址被 USDT 发行方 (Tether) 冻结。它无法转移 USDT，因此拒绝向其代理资源
`smart_contract`	true	已知的智能合约地址，包括随后被删除的合约。请参见下文说明
`spam_sender`	true	确认的垃圾信息群发者
`clean`	false	不在任何集合中
`unavailable`	null	无法查阅中央黑名单，因此该地址既未确认安全，也未确认封禁。仅限批量查询；单地址端点将返回带 `code 5004` 的 `503`。请参阅中央黑名单不可用

智能合约被封禁是出于技术原因，而非反洗钱 (AML) 原因

smart_contract 裁决意味着该地址属于合约，而非用户钱包，因此不会向其代理 Energy，且在下单前就会拒绝该地址。该集合包含所有成功创建合约的地址，包括随后被删除的合约——删除的合约不会将其地址转变为用户钱包。这并不意味着合约已被攻破、受污染或在 AML 项下属于高风险。 该集合中的大多数合约都是完全正常的。请将 smart_contract 视为“非代理目标”，而非风险标记。

GasFree 钱包

GasFree 钱包是一种合约，允许其所有者接收和发送代币，并使用这些代币支付网络费用。每个钱包均由 GasFree 控制器 TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U 创建。此类地址报告为 category: "smart_contract" 且 subtype: "gasfree_wallet"。

在路由资金时，这种区别至关重要：

	普通智能合约	GasFree 钱包
发送 USDT 至该地址	非正常接收方	是 — 属于用户钱包
向其代理 Energy	否	否 — 我们不向 GasFree 钱包代理 Energy
`category` / `subtype`	`smart_contract` / `null`	`smart_contract` / `gasfree_wallet`

覆盖范围及注意事项：

仅包含已部署的钱包。接收过 USDT 但从未发送过任何交易的 GasFree 地址尚未部署，因此它不在任何集合中，返回为 clean。
该子类型描述了地址可以在何处接收资金。它不涉及来自 GasFree 钱包的转账；需单独筛查发送方地址。
subtype_status: "unavailable" 表示无法查阅 GasFree 列表。裁决的其余部分（blocked、category、matches）仍然有效。
控制器本身和其他合约不是 GasFree 钱包：它们返回 subtype: null。

已删除合约

合约可以自毁（self-destruct）。该地址仍保留在 smart_contract 集合中：它曾经是合约地址，而不是用户钱包，Netts 不会向其代理资源或发送款项。此类地址报告为 category: "smart_contract" 且 subtype: "selfdestructed_contract"。

confirmed 表示根据 TRON 节点的最新确认状态已被删除。这并不是对未来的保证：同一地址上可能会再次部署合约，届时该子类型会被移除，而地址仍保持 smart_contract。
仅有自毁调用并不意味着删除：在 TRON 上，早期交易中创建的合约在其后仍会保留其代码。仅以节点状态为准。
如果一个地址既是已删除合约又存在于 GasFree 列表中，则以 selfdestructed_contract 为准——该地址不会被报告为正常工作的 GasFree 钱包。
subtype_status: "unavailable" 表示无法查阅已删除合约列表；裁决的其余部分仍然有效，在可以再次查阅之前，不会将任何地址确认为 GasFree 钱包。

原因代码与数据提供商

对于 aml_risk，reason_code 和 label 描述了该地址被列入的原因。公开的制裁机构保持原样——SANCTIONS_OFAC_SDN、SANCTIONS_EU_FSF、SANCTIONS_UK_FCDO 等。调查结果背后的商业筛查提供商名称绝不会公开：此类代码被统一标准化为 SANCTIONS_SCREENING，并且任何提供商名称都会从 label 中去除。

黑名单规模

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

来自同一缓存的裁决底层集合的总规模。公开且无需密钥。

json

{
    "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 是总数中与 AML 中立的最大组成部分——请参阅上述关于合约的说明。gasfree_wallets_subset（活跃的 GasFree 钱包）和 selfdestructed_contracts_subset（已删除合约）是 smart_contract 的子集；它们不会累加到 total 中。如果这两个计数器之一当前无法读取，则为 null，其他数值仍会返回。

批量查询 (API 密钥)

要一次检查多个地址，请使用需身份验证的批量端点。它的存在是为了节省网络往返开销：使用一次请求和一个内部流水线，而不是 N 次单独的 GET 请求。单个地址只需传入一个元素的数组即可。

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

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

每次请求最多 1000 个地址。裁决按相同顺序返回，每个地址的字段与单地址响应相同（包括 subtype、subtype_status、matches 和 checks_complete），对于格式错误的条目还会返回 category: "invalid"（带有 error 字段）——单个错误条目不会导致整个批次失败。如果中央黑名单未加载，原本正常的地址将返回 category: "unavailable"（blocked: null，带有 error 字段）而非 clean——参见中央黑名单不可用。

json

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

批量端点需要 API 密钥（x-api-key 请求头），并且密钥可以选择绑定到 IP 白名单。请联系我们获取密钥。

其速率限制是按密钥计算的，并且高于公开的单地址端点：

Period	Limit
1 秒	200 个请求
1 分钟	12,000 个请求

每个请求最多可携带 1000 个地址，因此在此限制下单单个密钥每秒可筛查远超十万个地址。

错误响应

地址格式无效 (400)

json

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

服务暂不可用 (503)

json

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

中央黑名单不可用 (503, code 5004)

裁决由内存缓存提供服务。如果该缓存可访问，但中央 AML 黑名单当前未加载，或者其当前版本未通过完整性检查，该端点不会回退为 clean——否则会将未检查的地址报告为安全。相反，它会明确告知无法产生裁决：

json

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

这意味着：该地址既未确认安全，也未确认封禁。服务当前无法对照制裁/AML 列表对其进行筛查。切勿将该地址视为正常——请稍后重试。

明确的封禁仍会正常返回：如果该地址匹配冻结 USDT、智能合约或垃圾信息发送者（不依赖中央列表的集合），即使处于此状态，您仍会收到通常的 blocked: true 裁决。只有原本应为 clean 的响应才会变为 5004。

在批量端点中，相同情况会在每个地址上报告为 category: "unavailable"（blocked: null，带有 error 字段）；批次中的其余地址不受影响。这是一种罕见的暂时状态。

注册表不可用 (503, code 5005)

集合在原地更新，并在更新期间保持可读，因此例行更新绝不会影响裁决。仅当集合应用失败时，原本正常的地址才无法确认为安全。此时单地址端点返回：

json

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

与 5004 相同，明确的封禁仍会正常返回，批量端点会在对应地址上将其报告为 category: "unavailable"。请稍后重试。

错误代码参考

Code	Description	HTTP Status
`0`	成功	200
`1001`	TRON 地址格式无效	400
`5003`	缓存后端暂不可用	503
`5004`	中央黑名单未加载——无法产生裁决（请重试）	503
`5005`	集合应用失败——无法产生裁决（请重试）	503

速率限制

在网关处实施两级限制：

Endpoint	Auth	Limited by	1 秒	1 分钟
`GET /apiv2/compliance/{address}`	公开，无需密钥	IP	10	300
`GET /apiv2/compliance/stats`	公开，无需密钥	IP	10	300
`POST /apiv2/compliance/batch`	API 密钥	密钥	200	12,000

公开的单地址端点适用于交互式和轻量级程序化调用。对于批量筛查，请使用批量端点：每次请求最多 1000 个地址，每个密钥每秒 200 次请求，单个密钥每秒可筛查远超十万个地址。需要更多？按密钥限制属于策略配置，而非技术上限——请联系我们。

超出速率限制 (429)

json

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

注意事项

无需身份验证且完全免费。 任何人都可以调用；无需签名。
纯缓存。 裁决绝不接触数据库或节点，因此在速率限制内轮询速度极快且安全。
非完整 AML 报告。 如需风险评分、风险暴露明细和带签名的报告，请使用经身份验证的筛查 API（POST /apiv2/screening）。该端点仅回答一个更具体的问题：该地址是否在我们的黑名单上，以及原因。

GET /apiv2/compliance/ ​

端点 URL ​

请求参数 ​

示例 ​

cURL ​

Python ​

JavaScript ​

响应 ​

已封禁——位于中央黑名单中 (200 OK) ​

GasFree 钱包——可接收 USDT 的智能合约 (200 OK) ​

已删除合约——该地址仍算作智能合约 (200 OK) ​

正常——不在任何集合中 (200 OK) ​

响应字段 ​

类别 ​

GasFree 钱包 ​

已删除合约 ​

原因代码与数据提供商 ​

黑名单规模 ​

批量查询 (API 密钥) ​

错误响应 ​

地址格式无效 (400) ​

服务暂不可用 (503) ​

中央黑名单不可用 (503, code 5004) ​

注册表不可用 (503, code 5005) ​

错误代码参考 ​

速率限制 ​

超出速率限制 (429) ​

注意事项 ​

GET /apiv2/compliance/

端点 URL

请求参数

示例

cURL

Python

JavaScript

响应

已封禁——位于中央黑名单中 (200 OK)

GasFree 钱包——可接收 USDT 的智能合约 (200 OK)

已删除合约——该地址仍算作智能合约 (200 OK)

正常——不在任何集合中 (200 OK)

响应字段

类别

GasFree 钱包

已删除合约

原因代码与数据提供商

黑名单规模

批量查询 (API 密钥)

错误响应

地址格式无效 (400)

服务暂不可用 (503)

中央黑名单不可用 (503, code 5004)

注册表不可用 (503, code 5005)

错误代码参考

速率限制

超出速率限制 (429)

注意事项