POST /apiv2/screening

Bir blokzincir adresi için AML taraması siparişi verin. Bu, sürüm 2 sözleşmesidir: her sağlayıcı ve siparişin her durumu için tek bir yanıt yapısı, dize olarak ondalık sayılar ve tek bir hata formatı.

Çalışmaya devam eden ve önceden bildirilmeksizin kaldırılmayacak olan POST /apiv2/aml uç noktasının yerini alır.

Uç Nokta URL'si

POST https://netts.io/apiv2/screening

İstek Üstbilgileri

Header	Required	Description
Content-Type	Evet	application/json
X-API-KEY	Evet	Netts kontrol panelinizdeki API anahtarınız
X-Idempotency-Key	Hayır	Güvenli yeniden denemeler için kendi anahtarınız. Bkz. Idempotency

İstek Gövdesi

json

{
    "address": "YOUR_ADDRESS_HERE",
    "network": "trx",
    "provider": "elliptic",
    "wait_for_result": true
}

İstek Parametreleri

Parameter	Type	Required	Description
address	string	Evet	Taranacak adres, 10–128 karakter
network	string	Evet	Ağ kısaltması. Her sağlayıcının kapsadığı kısaltmalar GET /apiv2/screening/providers tarafından listelenir; ağların adlarıyla birlikte tam tablosu buradadır
provider	string	Evet	`elliptic` veya `bitok`. Varsayılan bir değer yoktur
wait_for_result	boolean	Hayır	`true` sonucu 15 saniyeye kadar bekler. Varsayılan `false`
language	string	Hayır	Rapor dili. Yalnızca `en`

Bilinmeyen alanlar reddedilir. Yukarıdaki tabloda yer almayan bir alan içeren bir gövde, 4001 koduyla birlikte 400 döndürür. Sürüm 1'de bilinmeyen alanlar sessizce yok sayılırdı ve yanlış yazılmış bir wait, çağıranın eşzamanlı olarak asla gelmeyecek bir sonucu beklemesi anlamına gelirdi.

provider zorunludur ve varsayılanı yoktur. Sürüm 1'de belirtilmeyen bir sağlayıcı Elliptic anlamına geliyordu, bu nedenle seçim yapmayan bir çağıran, adını hiç belirtmediği bir sağlayıcı için ödeme yapıyordu.

provider, şemada bir numaralandırma değil, serbest biçimli bir dizedir. Bugün iki değer kabul edilmektedir; üçüncü bir sağlayıcı, yanıtları şemaya göre doğrulayan hiç kimse için bozucu bir değişiklik olmamalıdır. Mevcut liste, her sağlayıcının kapsadığı ağlar ve her birinin puanlama yaptığı ölçek GET /apiv2/screening/providers adresinden gelir.

Örnekler

cURL — sonucu bekle

bash

curl -X POST https://netts.io/apiv2/screening \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -d '{
    "address": "YOUR_ADDRESS_HERE",
    "network": "trx",
    "provider": "elliptic",
    "wait_for_result": true
  }'

cURL — kabul et ve sorgula

bash

curl -X POST https://netts.io/apiv2/screening \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -d '{
    "address": "YOUR_ADDRESS_HERE",
    "network": "trx",
    "provider": "bitok"
  }'

Yanıt, siparişi işaret eden bir Location başlığı ile birlikte 202 Accepted şeklindedir.

Python

python

import requests
from decimal import Decimal

url = "https://netts.io/apiv2/screening"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
}
payload = {
    "address": "YOUR_ADDRESS_HERE",
    "network": "trx",
    "provider": "elliptic",
    "wait_for_result": True,
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code in (200, 202):
    body = response.json()
    print("Order:", body["order"]["client_order_id"])
    print("Status:", body["order"]["status"])
    if body["risk"]["score"] is not None:
        # Parse provider numbers as Decimal, never as float
        print("Score:", Decimal(body["risk"]["score"]), "of", body["risk"]["scale"]["max"])
    print("Level:", body["risk"]["level"], "-", body["risk"]["level_source"])
    print("Charged:", body["billing"]["charged_amount"], body["billing"]["charged_currency"])
else:
    problem = response.json()
    print(problem["code"], problem["title"], "-", problem["detail"])

Yanıt

Durum	Kod	Başlıklar
Sipariş oluşturuldu, tarama arka planda çalışıyor	`202 Accepted`	`Location: /apiv2/screening/{client_order_id}`
Sonuç yanıtta yer alıyor (`wait_for_result`)	`200 OK`	—
Sonuç yakın tarihli bir kontrolden yeniden kullanıldı, ücret alınmadı	`200 OK`	—
Adreste blokzincir faaliyeti yok, ücret alınmadı	`200 OK`	—
Hata	bkz. Errors	`Content-Type: application/problem+json`

Bir tarama sonucu taşıyan yanıtlar Cache-Control: private, no-store ile gönderilir.

Yanıt

json

{
  "schema_version": 2,
  "order": {
    "client_order_id": "A90D21F68C9AEA2",
    "status": "completed",
    "api_version": "v2",
    "cache_hit": false,
    "created_at": "2026-09-13T08:14:29.614988Z",
    "started_at": "2026-09-13T08:14:30.288251Z",
    "completed_at": "2026-09-13T08:14:34.993174Z"
  },
  "request": {
    "address": "YOUR_ADDRESS_HERE",
    "network": "trx",
    "provider": "elliptic"
  },
  "billing": {
    "charged": true,
    "price_usdt": "0.98",
    "base_amount": "2.882421",
    "markup_amount": "0",
    "charged_amount": "2.882421",
    "charged_currency": "TRX",
    "exchange_rate": "0.33999200",
    "payment_status": "pending"
  },
  "precheck": {
    "activity_checked": true,
    "activity_status": "active",
    "source": "tron-address-checker"
  },
  "check": {
    "provider": "elliptic",
    "provider_check_id": "b4903a5d-9f22-4075-b51b-beb40b419b97",
    "checked_at": "2026-09-13T08:14:32.144000Z",
    "status": "completed",
    "provider_status": "complete"
  },
  "risk": {
    "score": "0.9634087310611608",
    "scale": { "min": 0, "max": 10 },
    "level": "low",
    "level_source": "computed",
    "provider_level": null,
    "policy": "netts-risk-v1",
    "by_direction": {
      "source": "0.12332156899576921",
      "destination": "0.9634087310611608"
    }
  },
  "sanctions": {
    "self": false,
    "self_entities": null,
    "exposure": {
      "entity": "HTX (formerly Huobi) - Post-Sanctions - UK Sanctions List - 26 May 2026",
      "category": "Exchange",
      "share_fraction": "0.004409451392423414",
      "proximity": "indirect",
      "hops": 3,
      "direction": "source",
      "rule_name": "Sanctioned, TF & CSAM"
    },
    "items": []
  },
  "exposure": [
    {
      "category": "Exchange",
      "share_fraction": "0.1888065152442461",
      "direction": "source",
      "hops": 2,
      "is_screened_address": false,
      "entities": [
        { "name": "Binance", "category": "Exchange", "is_vasp": true,
          "is_primary": true, "is_after_sanction_date": null }
      ]
    }
  ],
  "rules": [
    { "name": "Sanctioned, TF & CSAM", "type": "exposure", "level": null,
      "score": "0.061426483114820525", "share_fraction": null, "category": null,
      "proximity": null, "direction": "source", "detected_at": null }
  ],
  "entities": [
    { "name": "Unknown", "category": "Unknown", "is_vasp": null,
      "is_primary": true, "is_after_sanction_date": false }
  ],
  "primary_entity": {
    "name": "Unknown", "category": "Unknown", "is_vasp": null,
    "is_primary": true, "is_after_sanction_date": false
  },
  "sanctioned_entities": [],
  "wallet": {
    "inflow_usd": "354663.6116669158",
    "outflow_usd": "80248.63081808022"
  },
  "provider_data": { }
}

Alan seti asla değişmez

Yukarıda listelenen her blok, sağlayıcı ne olursa olsun ve siparişin durumu ne olursa olsun her yanıtta mevcuttur. Bir sağlayıcının sağlamadığı değer null olur; içinde hiçbir şey olmayan bir liste null değil, [] olur; henüz verisi olmayan bir blok atlanmak yerine null değerlerle doldurulur. Tek bir ayrıştırıcı, henüz kabul edilmiş bir kontrolü ve tamamlandıktan sonraki aynı kontrolü işler.

Kodunuz için iki sonuç:

bilmediğiniz alanları yok sayın. Bu bloklara yeni bir sürüm olmadan yeni alanlar eklenir. Bilinmeyen bir alanı reddetmek bizim değil, sizin hatanızdır;
provider_data sözleşmenin bir parçası değildir. Şekli sağlayıcıyı takip eder ve sağlayıcı değiştikçe değişir. Sözleşmenin garanti ettiği her şey yukarıdaki bloklarda yer alır.

`order`

Field	Type	Description
client_order_id	string	Sipariş tanımlayıcısı, sonucu daha sonra okumak için kullanılır
status	string	`pending`, `processing`, `completed`, `skipped`, `failed`
api_version	string	Siparişi oluşturan sözleşme
cache_hit	boolean	Yakın tarihli bir sonuç yeniden kullanıldığında ve ücret alınmadığında `true`
created_at	string	RFC 3339, UTC, mikrosaniye
started_at	string \| null	Sağlayıcı çağrısının başladığı zaman. `skipped` için `null`
completed_at	string \| null	Sonucun ulaştığı zaman
error	string	Yalnızca `failed` için: neden başarısız olduğu
reason	string	Yalnızca `skipped` için: `address_inactive`

Tüm zaman damgaları UTC, RFC 3339 formatında, Z sonekine ve mikrosaniye hassasiyetine sahiptir.

`billing`

Field	Type	Description
charged	boolean	Para tahsil edilip edilmediği
price_usdt	string	Sağlayıcının USDT cinsinden liste fiyatı
base_amount	string	Alt kullanıcı kâr marjı olmadan, tahsil edilen para biriminde sipariş fiyatı
markup_amount	string	Alt kullanıcı kâr marjı. Doğrudan bir hesap için `"0"`
charged_amount	string	Bakiyeden fiilen tahsil edilen tutar
charged_currency	string	`TRX`
exchange_rate	string \| null	Dönüşüm için kullanılan kur
payment_status	string	`paid`, `pending`, `failed`, `not_charged`

payment_status, başarılı bir kontrolden sonra kısa bir süre için pending durumundadır: ücret önce bloke edilir ve bir saat içinde kesinleşir. failed, paranın iade edildiği anlamına gelir. not_charged, hiçbir ücret oluşturulmadığı anlamına gelir — yeniden kullanılan bir sonuç veya atlanan bir adres.

`precheck`

Ücretli bir taramadan önce adres, blokzincir faaliyeti açısından kontrol edilir. Hiçbir faaliyeti olmayan bir adres sağlayıcıya gönderilmez ve ücretlendirilmez.

Field	Type	Description
activity_checked	boolean	Kontrolün çalışıp çalışmadığı. Mevcut olmadığı ağlarda `false`
activity_status	string	`active`, `inactive`, `unknown`
source	string \| null	Mekanizmanın adı

unknown, ücretli taramayı durdurmaz: faaliyet servisi kullanılamıyorsa adres aktif olarak değerlendirilir.

`check`

Field	Type	Description
provider	string	Kontrolü gerçekleştiren sağlayıcı
provider_check_id	string \| null	Sağlayıcının kendi tanımlayıcısı — onlarla bir sonucu tartışırken bunu belirtin
checked_at	string \| null	Sağlayıcının sonucu ürettiği zaman
status	string	Aşağıdaki tabloya bakın
provider_status	string \| null	Sağlayıcının değiştirilmemiş kendi ifadesi

`order.status`	`check.status`	Anlamı
`pending`	`pending`	Sipariş kabul edildi, henüz başlatılmadı
`processing`	`running`	Sağlayıcı üzerinde çalışıyor
`completed`	`completed`	Sonuç alındı
`failed`	`failed`	Sağlayıcı çağrısından önce veya çağrı sırasında reddedildi
`skipped`	`not_performed`	Adreste hiçbir faaliyet yok; sağlayıcı hiçbir zaman çağrılmadı ve hiçbir ücret tahsil edilmedi

`risk`

Field	Type	Description
score	string \| null	Ondalık dize olarak sağlayıcının kendi puanı
scale	object	Bu sağlayıcının ölçeğinin `min` ve `max` değerleri
level	string	`none`, `low`, `medium`, `high`, `severe`
level_source	string	`computed` — seviyeyi puandan türettik; `provider` — sağlayıcı belirtti
provider_level	string \| null	Sağlayıcının döndürdüğü durumlarda kendi ifadesi
policy	string	Eşik politikasının adı, `netts-risk-v1`
by_direction	object	Sağlayıcının ayırdığı durumlarda `source` ve `destination` olarak ayrılmış puan

Puan asla yeniden ölçeklendirilmez. Elliptic 0–10 ve BitOK 0–1 aralığında çalışır ve bir ölçekteki 7, diğerindeki 0.7 ile anlamlı hiçbir şekilde denk değildir. Tek bir sağlayıcıya göre yazılmış bir entegrasyonun tek bir yapılandırma değişikliğinden sonra bir başkasını yanlış yorumlamaması için ölçek yanıtta iletilir.

Seviye, tüm API genelinde tek bir sözlüktür. Sağlayıcının kendi seviyesini belirttiği durumlarda bunu doğrudan iletir ve level_source içinde bunu belirtiriz; belirtmediği durumlarda ise seviyeyi netts-risk-v1 eşikleriyle puandan türetir ve bunun yerine bunu ifade ederiz. Aynı kontrol için API yanıtında, kontrol panelinde ve PDF raporunda aynı sözcük görünür.

`exposure[]`, `rules[]`, `entities[]`

exposure[], fonları karşı taraf kategorisine göre ayrıştırır. rules[], sağlayıcının tetiklenen kurallarını listeler. entities[], adresin kendisinin ait olduğu varlıkları listeler; primary_entity, sabit bir kuralla bunlardan birini seçer — sağlayıcının birincil olarak işaretlediği varlık, aksi halde ilki, aksi halde null. sanctioned_entities[], entities[] içinden bir yaptırım tarihinden sonra aktif olarak işaretlenenleri barındırır.

Paylar orandır, asla yüzde değildir

Yanıttaki her pay, "0" ile "1" arasında bir ondalık dize olan tek bir alandır: share_fraction.

text

Elliptic reports 31.574732212596924 %  ->  "share_fraction": "0.31574732212596924"
BitOK reports    0.8488                ->  "share_fraction": "0.8488"

Sağlayıcılar birimler konusunda farklılık gösterir: aynı üçte birlik risk maruziyeti birinden 31.57, diğerinden 0.3157 olarak gelir. Her ikisini birden taşıyan tek bir alanı sağlayıcıyı bilmeden okumak imkansız olurdu. Sağlayıcının kendi birimlerindeki kendi sayısı provider_data içinde kalır.

Sayılar dizedir

Bir sağlayıcıdan gelen her sayı — puanlar, paylar, USD hacimleri ve billing içindeki her tutar — bir ondalık dizedir.

json

"score": "0.9634087310611608"

Bunu JavaScript, Go veya ikili kayan noktalı sayı kullanan başka bir dilde JSON sayısı olarak ayrıştırmak yaklaşık bir değer verir ve yazdırdığınız değer sağlayıcının verdiği değerle eşleşmemeye başlar. Bu alanları ondalık bir türle ayrıştırın: Python'da Decimal, Java'da BigDecimal, JavaScript'te decimal.Decimal veya bir dize.

Sağlayıcıya değil bize ait olan alanlar — scale.min, scale.max, hops — düz JSON sayılarıdır.

Yakın tarihli bir sonucun yeniden kullanılması

Aynı adresi, ağı ve sağlayıcıyı 60 saniye içinde tekrar taradığınızda, önceki sonuç döndürülür ve hiçbir ücret alınmaz.

Her istek yine de kendi client_order_id değeriyle kendi siparişini oluşturur; yeniden kullanılan sipariş "cache_hit": true olarak işaretlenir ve billing bloğu "payment_status": "not_charged" ile "charged": false bildirir. Sonucun geldiği siparişin tanımlayıcısı açıklanmaz — başka bir hesaba ait olabilir.

Yeniden kullanım yalnızca tek bir hesap içinde gerçekleşir. Başkası tarafından taranan bir sonuç asla size döndürülmez.

Idempotency

Yeniden denemeyi güvenli hale getirmek için kendi belirleyeceğiniz bir değerle X-Idempotency-Key gönderin: aynı gövdeye sahip aynı anahtar, ikinci bir kontrol siparişi vermek yerine saklanan yanıtı döndürür.

Durum	Kod	Yanıt
Bu anahtara sahip ilk istek hala çalışıyor	`409`	`4090`
Aynı anahtar, farklı bir istek gövdesi	`409`	`4093`
Aynı anahtar, aynı gövde, zaten tamamlanmış	saklanan kod	saklanan yanıt

Başlığı göndermezseniz, API anahtarından, adresten, sağlayıcıdan ve IP adresinizden iki saniyelik bir pencerede sizin için bir anahtar oluşturulur. Bu, çift tıklamaya ve ağ geçidi yeniden denemesine karşı koruma sağlar; bir dakika sonraki tekrara karşı sağlamaz: o gerçek bir yeni sipariştir ve ücretlendirilir.

Anahtarların kapsamı uç nokta başınadır. POST /apiv2/aml ve bu uç noktaya gönderilen aynı değer, iki farklı istek hakkında iki bağımsız taahhüttür — gövdeler farklıdır ve yanıtlar da öyledir. Bir entegrasyonu sürüm 1'den sürüm 2'ye taşırken anahtarınızı yeniden kullanmak güvenlidir: bu ne size bir sürüm 1 yanıtı döndürür ne de farklı bir gövdeyle kullanılan aynı anahtar sayılır.

Hata Yanıtları

Uygulama tarafından üretilen her hata Content-Type: application/problem+json ile RFC 9457 standardını kullanır:

json

{
  "type": "https://doc.netts.io/api/v2/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 403,
  "detail": "Insufficient funds. Required: 2.888742 TRX, Available: 1.203000 TRX",
  "instance": "/apiv2/screening",
  "code": 1004,
  "required_trx": "2.888742",
  "available_trx": "1.203000"
}

type, title, status, detail ve instance standart alanlardır. Sayısal code, sürüm 1'e göre yazılmış entegrasyonların bununla eşleşmeye devam edebilmesi için bir uzantı olarak tutulmuştur. Ek alanlar hataya bağlıdır ve bilmediğiniz durumlarda yok sayılmalıdır.

Kod	HTTP	Anlamı
`4000`	400	Gövde geçerli bir JSON değil
`4001`	400	Bir alan doğrulamadan geçemedi veya bilinmeyen bir alan gönderildi
`4002`	403	Sağlayıcı hesabınız için kullanılamıyor
`4003`	400	Hatalı biçimlendirilmiş sipariş tanımlayıcısı
`4004`	400	Sağlayıcı istenen ağı desteklemiyor
`4010`	401	API anahtarı yok
`4011`	401	API anahtarı veya IP adresi kabul edilmedi
`4040`	404	Sipariş bulunamadı
`4041`	404	Hesap bulunamadı
`4090`	409	Bu idempotency anahtarına sahip bir istek hala çalışıyor
`4091`	409	Yinelenen istek
`4093`	409	Bu idempotency anahtarı farklı bir gövdeyle kullanıldı
`1004`	403	Yetersiz bakiye
`5000`	500	Dahili hata
`5001`	500	Tahsilat gerçekleşmedi
`5002`	500	Sipariş oluşturulmadı
`5030`	503	Sağlayıcı kullanılamıyor

Bu formatı kullanmayan hatalar

Bazı arızalar uygulamaya ulaşılmadan önce ağ geçidinde meydana gelir ve ağ geçidinin kendi biçimini korur. Content-Type değeri application/problem+json olmayan herhangi bir yanıtı bunlardan biri olarak ele alın:

Durum	HTTP	Gövde
API anahtarı yok veya kabul edilmeyen bir anahtar	401	`{"detail":{"code":-1,"msg":"Invalid or missing API key"}}`
İstek limiti aşıldı	429	`{"message":"API rate limit exceeded"}`
Bilinmeyen yol veya rotanın hizmet vermediği bir yöntem	404 / 405	`{"detail":"Method Not Allowed"}`

İstek Hızı Sınırları

Limit, POST /apiv2/aml ve diğer AML yolları ile paylaşılır: saniyede 5 istek ve dakikada 150 istek. Bu uç noktaya geçmek size ikinci bir kota hakkı vermez.

Notlar

Fiyatlandırma: Kontrol başına Elliptic $0.98, BitOK $0.50 olup, tahsilat anındaki kur üzerinden TRX bakiyesinden tahsil edilir.
İşlem süresi: çoğu kontrol birkaç saniyede tamamlanır; uzun bir geçmişe sahip bir adres üç dakikaya kadar sürebilir. Asenkron modu kullanın ve sonucu GET /apiv2/screening/{client_order_id} ile okuyun.
Etkin olmayan adresler skipped döndürür ve ücretlendirilmez.
Sağlayıcının ham yanıtı asla döndürülmez. provider_data gözden geçirilmiş bir izdüşümdür; taranan adresten ziyade sağlayıcı nezdindeki hesabımıza ait olan alanlar hiç kimseye yayınlanmaz.

Raporlar

Uç nokta JSON döndürür ve başka hiçbir şey döndürmez. PDF ve Markdown yoktur.

Bir raporu oluşturan her şey yanıtta zaten mevcuttur: birleştirilmiş blok ve provider_data. Bunu kendi tarafınızda oluşturmak size gerçekten istediğiniz belgeyi sunar — kendi markanız, kendi diliniz, kendi düzeniniz — bu da kontrolleri yeniden satıyorsanız özellikle önemlidir, çünkü bizim adımızı taşıyan bir rapor kendi müşterinize teslim edilecek yanlış belgedir.

Bir rapora üçüncü bir taraf için kanıt olarak ihtiyacınız varsa — bir banka, bir düzenleyici kurum, bir karşı taraf — imzasız bir PDF'in, kim oluşturursa oluştursun bir kanıt olmadığını unutmayın: bir metin düzenleyicide bir dakika içinde düzenlenebilir. Doğrulanabilir bir yapıt için bir imza veya genel bir doğrulama sayfası gerekir ve bu farklı bir özelliktir. Durumunuz buysa, karşı tarafınızın ne talep ettiğini bize bildirin.

Aynı kontroller için insan tarafından okunabilir PDF raporları, Netts kontrol panelinde on yedi dilde mevcuttur.

Ayrıca Bakınız

GET /apiv2/screening/{client_order_id} — bir kontrolü okuyun
GET /apiv2/screening/history — kontrolleriniz, imleç ile sayfalanmış
GET /apiv2/screening/providers — sağlayıcılar, fiyatlar, ağlar, ölçekler
GET /apiv2/screening/price — bir sağlayıcının fiyatı
Sanctions in an AML result — sanctions ne söyler ve sağlayıcı işareti ne söyler

POST /apiv2/screening ​

Uç Nokta URL'si ​

İstek Üstbilgileri ​

İstek Gövdesi ​

İstek Parametreleri ​

Örnekler ​

cURL — sonucu bekle ​

cURL — kabul et ve sorgula ​

Python ​

Yanıt ​

Yanıt ​

Alan seti asla değişmez ​

order ​

billing ​

precheck ​

check ​

risk ​

exposure[], rules[], entities[] ​

Paylar orandır, asla yüzde değildir ​

Sayılar dizedir ​

Yakın tarihli bir sonucun yeniden kullanılması ​

Idempotency ​

Hata Yanıtları ​

Bu formatı kullanmayan hatalar ​

İstek Hızı Sınırları ​

Notlar ​

Raporlar ​

Ayrıca Bakınız ​

POST /apiv2/screening

Uç Nokta URL'si

İstek Üstbilgileri

İstek Gövdesi

İstek Parametreleri

Örnekler

cURL — sonucu bekle

cURL — kabul et ve sorgula

Python

Yanıt

Yanıt

Alan seti asla değişmez

`order`

`billing`

`precheck`

`check`

`risk`

`exposure[]`, `rules[]`, `entities[]`

Paylar orandır, asla yüzde değildir

Sayılar dizedir

Yakın tarihli bir sonucun yeniden kullanılması

Idempotency

Hata Yanıtları

Bu formatı kullanmayan hatalar

İstek Hızı Sınırları

Notlar

Raporlar

Ayrıca Bakınız