GET /apiv2/screening/history

您的筛查历史记录，按最新优先排序，采用游标分页。

这是版本 2 协议规范。它取代了 GET /apiv2/aml/history，后者仍可继续使用。

端点 URL

GET https://netts.io/apiv2/screening/history

请求标头

请求头	必填	描述
X-API-KEY	是	来自 Netts 控制台的 API 密钥

查询参数

所有过滤参数均为可选。不提供任何参数将返回您的全部历史记录。

参数	类型	默认值	描述
address	字符串	—	精确地址，10–128 个字符
network	字符串	—	网络代码
provider	字符串	—	`elliptic` 或 `bitok`
status	字符串	—	`pending`、`processing`、`completed`、`skipped`、`failed`
from	字符串	—	仅查询在此时间点或之后创建的检查，RFC 3339 格式
to	字符串	—	仅查询在此时间点或之前创建的检查，RFC 3339 格式
cursor	字符串	—	继续遍历的游标起点。取自 `next_cursor`
limit	整数	50	每页条目数，1 到 200

在版本 1 中，address 和 network 都是必填项，因此无法直接查询“我最近检查了什么”。

状态为 skipped 的检查也会被包含在内。 版本 1 会隐藏它们。被跳过的检查是一笔真实的订单——由于该地址没有任何区块链活动，因此从未发送给提供商，也从未被计费——它属于历史记录的一部分。

示例

cURL

bash

curl "https://netts.io/apiv2/screening/history?limit=50" \
  -H "X-API-KEY: your_api_key"

Python — 遍历完整历史记录

python

import requests

headers = {"X-API-KEY": "your_api_key"}
params = {"limit": 200, "provider": "elliptic"}

while True:
    page = requests.get("https://netts.io/apiv2/screening/history",
                        headers=headers, params=params).json()
    for item in page["items"]:
        print(item["order"]["client_order_id"],
              item["order"]["status"],
              item["risk"]["level"],
              item["sanctions"]["verdict"])

    if not page["next_cursor"]:
        break
    params = {"limit": 200, "provider": "elliptic", "cursor": page["next_cursor"]}

分页遍历时请保持过滤参数一致。在使用相同游标的同时修改过滤条件会导致错误，而不是静默切换到不同的数据集。

响应

json

{
  "schema_version": 2,
  "items": [
    {
      "order": {
        "client_order_id": "A6F3221BAAE093A",
        "status": "completed",
        "api_version": "v2",
        "cache_hit": false,
        "created_at": "2026-09-13T08:24:19.838584Z",
        "started_at": "2026-09-13T08:24:20.998619Z",
        "completed_at": "2026-09-13T08:24:25.179967Z"
      },
      "request": {
        "address": "YOUR_ADDRESS_HERE",
        "network": "trx",
        "provider": "elliptic"
      },
      "check": {
        "provider": "elliptic",
        "provider_check_id": "1cc2fd64-1483-4ce3-946f-23a614f41a12",
        "checked_at": "2026-09-13T08:24:22.372000Z",
        "status": "completed",
        "provider_status": "complete"
      },
      "risk": {
        "score": "0.12428176721891304",
        "scale": { "min": 0, "max": 10 },
        "level": "low",
        "level_source": "computed",
        "provider_level": null,
        "policy": "netts-risk-v1",
        "by_direction": { "source": "0.12428176721891304", "destination": null }
      },
      "sanctions": { "verdict": "linked" }
    }
  ],
  "next_cursor": "eyJmIjp7InN0YXR1cyI6ImNvbXBsZXRlZCJ9LCJpIjoxMzQyNywidCI6...",
  "limit": 1
}

字段	类型	描述
items	数组	当前页数据，最新优先
next_cursor	字符串 \| null	回传此游标以获取下一页。`null` 表示已到达末尾
limit	整数	实际应用的条数限制

单个条目的简短格式

order、request、check 和 risk 块与 GET /apiv2/screening/{client_order_id} 的完整响应中的内容完全一致，字段一一对应，因此可以使用相同的解析器处理两者。

被省略的内容包括：provider_data、exposure[]、rules[]、entities[]、wallet、billing、precheck 以及完整的 sanctions 块。单个 Elliptic 结果约为 150 KB，一页 50 条记录将达到 7 MB。仅在需要详细信息时再获取单个检查详情。

`sanctions.verdict`

精简为一个词的制裁分析结果。

取值	含义
`listed`	地址本身处于制裁名单中
`linked`	发现制裁关联，但地址本身未被列入名单
`none`	分析已执行且未发现任何异常
`null`	尚无可供分析的结果

listed 和 linked 之间的区别是该字段的核心意义——请参见AML 结果中的制裁信息。

分页

版本 1 按页码分页：?page=2，每页 100 条。数据按创建时间降序排列，最新优先，因此在从第 1 页翻到第 2 页的过程中，新创建的检查项会写入并向下顺移所有条目。您已经查看过的记录会再次出现，而未查看过的记录可能已被跳过。对于业务繁忙的账户，这并不是极端偶发情况。

游标指向数据集中的某个固定位置，而不是其序号位置，因此在遍历过程中即使有新检查产生也不会受到干扰。

排序方式为 created_at DESC, id DESC。两个字段都包含在游标中，因为 created_at 并不唯一——同一微秒内创建的两个检查否则会导致死循环或遗漏；
游标是不透明的。其具体内容属于实现细节；请将其原样回传；
过滤条件包含在游标中。在复用游标时修改过滤条件将返回 400，而不会静默切换到另一个数据集——否则您可能会误以为自己已读取了从未读取过的数据集；
next_cursor: null 表示已到末尾。不提供总计数：在每一页计算整个数据集的开销远超其提供的价值。

错误响应

遵循 RFC 9457 规范，application/problem+json。完整的错误代码列表请参见 POST 页面。

代码	HTTP	触发场景
`4001`	400	`limit` 超出 1…200 范围，未知的 `network`、`provider` 或 `status`，`from`/`to` 不符合 RFC 3339 格式，格式错误的游标，或针对不同过滤条件签发的游标
`4010` / `4011`	401	未提供 API 密钥，或密钥/IP 未被接受

json

{
  "type": "https://doc.netts.io/api/v2/errors/validation-failed",
  "title": "Request validation failed",
  "status": 400,
  "detail": "Cursor was issued for a different set of filters",
  "instance": "/apiv2/screening/history",
  "code": 4001
}

速率限制

与其他所有 AML 接口共享限制：每秒 5 次请求，每分钟 150 次请求。在 limit=200 的情况下，获取一万条检查的完整历史记录仅需 50 次请求。

GET /apiv2/screening/history ​

端点 URL ​

请求标头 ​

查询参数 ​

示例 ​

cURL ​

Python — 遍历完整历史记录 ​

响应 ​

单个条目的简短格式 ​

sanctions.verdict ​

分页 ​

错误响应 ​

速率限制 ​