GET /apiv2/screening/history

Lịch sử kiểm tra của bạn, mới nhất trước, có phân trang bằng con trỏ (cursor).

Đây là hợp đồng phiên bản 2. Nó thay thế cho GET /apiv2/aml/history, vốn vẫn tiếp tục hoạt động.

URL endpoint

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

Header yêu cầu

Header	Bắt buộc	Mô tả
X-API-KEY	Có	Khóa API của bạn từ bảng điều khiển Netts

Tham số truy vấn

Tất cả các bộ lọc đều là tùy chọn. Nếu không có bộ lọc nào, bạn sẽ nhận được toàn bộ lịch sử của mình.

Tham số	Loại	Mặc định	Mô tả
address	string	—	Địa chỉ chính xác, 10–128 ký tự
network	string	—	Mã mạng (ticker)
provider	string	—	elliptic hoặc bitok
status	string	—	pending, processing, completed, skipped, failed
from	string	—	Chỉ các lượt kiểm tra được tạo tại hoặc sau thời điểm này, RFC 3339
to	string	—	Chỉ các lượt kiểm tra được tạo tại hoặc trước thời điểm này, RFC 3339
cursor	string	—	Vị trí để tiếp tục. Lấy từ next_cursor
limit	integer	50	Số lượng mục trên mỗi trang, 1 đến 200

Ở phiên bản 1, cả address và network đều bắt buộc, vì vậy không có cách nào để hỏi "gần đây tôi đã kiểm tra những gì".

Các lượt kiểm tra có trạng thái skipped được bao gồm. Phiên bản 1 ẩn chúng. Một lượt kiểm tra bị bỏ qua (skipped) là một đơn hàng thực sự — địa chỉ không có hoạt động blockchain nào, vì vậy nó không bao giờ được gửi tới nhà cung cấp và không bao giờ bị tính phí — và nó thuộc về lịch sử.

Yêu cầu mẫu

cURL

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

Python — duyệt qua toàn bộ lịch sử

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

Giữ nguyên các bộ lọc trong khi phân trang. Thay đổi một bộ lọc trong khi vẫn giữ nguyên con trỏ cũ là một lỗi, chứ không phải là một sự chuyển đổi âm thầm sang một tập dữ liệu khác.

Phản hồi

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

Trường	Loại	Mô tả
items	array	Trang dữ liệu, mới nhất trước
next_cursor	string | null	Truyền lại giá trị này để lấy trang tiếp theo. null nghĩa là bạn đã đến cuối
limit	integer	Giới hạn đã được áp dụng

Dạng rút gọn của một mục

Các khối order, request, check và risk hoàn toàn giống với các khối trong phản hồi đầy đủ của GET /apiv2/screening/{client_order_id}, từng trường một, do đó cùng một trình phân tích cú pháp có thể xử lý cả hai.

Những phần được bỏ qua: provider_data, exposure[], rules[], entities[], wallet, billing, precheck, và khối sanctions đầy đủ. Một kết quả Elliptic đơn lẻ có dung lượng khoảng 150 KB, và một trang gồm năm mươi kết quả sẽ là bảy megabyte. Hãy lấy từng lượt kiểm tra riêng lẻ khi bạn cần thông tin chi tiết.

sanctions.verdict

Phân tích lệnh trừng phạt được nén thành một từ.

Giá trị	Ý nghĩa
listed	Bản thân địa chỉ nằm trong danh sách trừng phạt
linked	Đã tìm thấy mối liên kết trừng phạt, nhưng bản thân địa chỉ không nằm trong danh sách
none	Phân tích đã chạy và không tìm thấy gì
null	Chưa có kết quả để phân tích

Sự khác biệt giữa listed và linked chính là mục đích của trường này — xem Trừng phạt trong kết quả AML.

Phân trang

Phiên bản 1 phân trang theo số: ?page=2, 100 mục mỗi trang. Thứ tự sắp xếp theo thời gian tạo, mới nhất trước, do đó khi bạn chuyển từ trang 1 sang trang 2, các lượt kiểm tra mới xuất hiện và đẩy mọi thứ xuống. Các bản ghi bạn đã xem xuất hiện lại, các bản ghi bạn chưa xem trôi qua mất. Với một tài khoản bận rộn, đây không phải là trường hợp hiếm gặp.

Một con trỏ (cursor) trỏ vào một vị trí cụ thể trong tập dữ liệu thay vì số thứ tự của nó, do đó các lượt kiểm tra mới xuất hiện trong quá trình duyệt sẽ không làm xáo trộn kết quả.

• thứ tự là created_at DESC, id DESC. Cả hai trường đều nằm trong con trỏ, bởi vì created_at không phải là duy nhất — hai lượt kiểm tra được tạo trong cùng một micro giây nếu không sẽ bị lặp lại hoặc bị bỏ qua;
• con trỏ là mờ đục (opaque). Nội dung của nó là chi tiết triển khai; hãy truyền lại chính xác như khi bạn nhận được;
• các bộ lọc là một phần của con trỏ. Việc thay đổi một bộ lọc trong khi tái sử dụng con trỏ sẽ trả về 400, chứ không phải là sự chuyển đổi âm thầm sang một tập dữ liệu khác — nếu không bạn sẽ tin rằng mình đã đọc một tập dữ liệu mà bạn chưa từng đọc;
• next_cursor: null biểu thị điểm kết thúc. Không có tổng số lượng: việc đếm toàn bộ tập dữ liệu trên mỗi trang gây tốn kém hơn nhiều so với giá trị thông tin nó mang lại.

Lỗi

RFC 9457, application/problem+json. Danh sách mã đầy đủ có trên trang POST.

Mã	HTTP	Khi nào
4001	400	limit ngoài phạm vi 1…200, network, provider hoặc status không xác định, from/to không đúng định dạng RFC 3339, con trỏ bị lỗi cú pháp, hoặc con trỏ được phát hành cho các bộ lọc khác
4010 / 4011	401	Không có API key, hoặc khóa hay IP không được chấp nhận

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

Giới hạn tốc độ

Được chia sẻ với mọi đường dẫn AML khác: 5 yêu cầu mỗi giây, 150 yêu cầu mỗi phút. Với limit=200, toàn bộ lịch sử gồm mười nghìn lượt kiểm tra chỉ mất năm mươi yêu cầu.