POST /apiv2/screening

Bir blokzincir adresi için AML taraması siparişi verin: 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 biçimi.

Uç Nokta URL'si

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

İstek Üstbilgileri

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

İstek Gövdesi

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

Parametreler

Parameter	Type	Required	Description
address	string	Yes	Taranacak adres, 10–128 karakter
network	string	Yes	Ağ kodu. Her sağlayıcının kapsadığı kodlar GET /apiv2/screening/providers tarafından listelenir
provider	string	Yes	elliptic veya bitok. Varsayılan bir değer yoktur
wait_for_result	boolean	No	true değeri, 15 saniyeye kadar sonucu bekler. Varsayılan false
language	string	No	Rapor dili. Yalnızca en

Bilinmeyen alanlar reddedilir. Yukarıdaki tabloda yer almayan bir alan içeren gövde, 4001 koduyla 400 döner.

provider zorunludur ve varsayılanı yoktur. Ödemesini yaptığınız sağlayıcıyı her zaman kendiniz seçersiniz.

provider, şemada serbest biçimli bir dizedir, bir sabit listesi (enum) değildir. 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 (breaking change) 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 uç noktasından alınır.

Örnek İstekler

cURL — sonucu bekle

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

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şe işaret eden bir Location başlığı ile birlikte 202 Accepted şeklindedir.

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 Kodları

Situation	Code	Headers
Sipariş oluşturuldu, tarama arka planda çalışıyor	202 Accepted	Location: /apiv2/screening/{client_order_id}
Sonuç yanıtta (wait_for_result)	200 OK	—
Sonuç yakın tarihli bir kontrolden yeniden kullanıldı, ücret alınmadı	200 OK	—
Adresin blokzincir etkinliği 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

{
  "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 kümesi 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ığı şey null değerindedir; içinde hiçbir şey olmayan bir liste null değil, [] şeklindedir; henüz verisi olmayan bir blok çıkarılmak yerine null değerleriyle doldurulur. Tek bir ayrıştırıcı, henüz kabul edilmiş bir kontrolü ve tamamlandığında aynı kontrolü işleyebilir.

Kodunuz için iki sonuç:

• bilmediğiniz alanları yoksayın. Bu bloklara yeni bir sürüm olmadan da 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ıya bağlıdır ve sağlayıcı değiştiğinde 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	Sonucu daha sonra okumak için kullanılan sipariş tanımlayıcısı
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 hiçbir ü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, Z soneki ve mikrosaniye hassasiyetindedir.

billing

Field	Type	Description
charged	boolean	Para alınıp alınmadığı
price_usdt	string	Sağlayıcının USDT cinsinden liste fiyatı
base_amount	string	Alt kullanıcı marjı olmadan, ücretlendirilen para birimindeki sipariş fiyatı
markup_amount	string	Alt kullanıcı marjı. Doğrudan bir hesap için "0"
charged_amount	string	Bakiyeden fiilen alınan miktar
charged_currency	string	TRX
exchange_rate	string | null	Dönüşüm için kullanılan kur
payment_status	string	paid, pending, failed, not_charged, postpaid

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 zaman bir ücretlendirme oluşturulmadığı anlamına gelir — yeniden kullanılan bir sonuç veya atlanan bir adres. postpaid — bkz. Postpaid Accounts.

precheck

Ücretli bir taramadan önce adres blokzincir etkinliği açısından kontrol edilir. Etkinliği 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: etkinlik hizmeti kullanılamıyorsa adres etkin olarak kabul edilir.

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 sonuca itiraz ederken 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	Meaning
pending	pending	Sipariş kabul edildi, henüz başlamadı
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	Adresin etkinliği yok; sağlayıcı hiç çağrılmadı ve hiçbir ücret alınmadı

risk

Field	Type	Description
score	string | null	Sağlayıcının ondalık dize olarak 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ı bunu belirtti
provider_level	string | null	Sağlayıcı bir seviye döndürdüğünde kendi ifadesi
policy	string	Eşik politikasının adı, netts-risk-v1
by_direction	object	Sağlayıcı böldüğünde, source ve destination olarak ayrılmış puan

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

Seviye, tüm API genelinde tek bir terminolojidir. Sağlayıcının kendi seviyesini belirttiği durumlarda bunu doğrudan aktarır ve level_source içinde belirtiriz; belirtmediği durumlarda ise netts-risk-v1 eşikleriyle puandan seviyeyi türetir ve bunun yerine bunu belirtiriz. Aynı kontrol için API yanıtında, kontrol panelinde ve PDF raporunda aynı ifade yer alı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 bizzat 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 takdirde ilki, aksi takdirde null. sanctioned_entities[], entities[] içinden bir yaptırım tarihinden sonra aktif olarak işaretlenenleri tutar.

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

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

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

Sağlayıcılar birimler konusunda uyuşmaz: maruziyetin aynı üçte biri birinden 31.57, diğerinden 0.3157 olarak gelir. Her ikisini de taşıyan tek bir alanın sağlayıcı bilinmeden okunması 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 — ondalık bir dizedir.

"score": "0.9634087310611608"

Bunu JavaScript, Go veya ikili kayan nokta kullanan başka herhangi bir dilde bir 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şmeyi bırakır. 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 sonucu yeniden kullanma

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 birlikte "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.

Situation	Code	Response
Bu anahtarla yapılan ilk istek hâlâ ç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 zaman aralığında sizin için bir anahtar oluşturulur. Bu, çift tıklamaya ve bir ağ geçidi yeniden denemesine karşı koruma sağlar, ancak bir dakika sonraki tekrara karşı koruma sağlamaz: bu yeni ve gerçek bir sipariştir ve ücretlendirilir.

Hata Yanıtları

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

{
  "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 bir uzantıdır: hata işlemenizi bununla eşleştirin. Ek alanlar hataya bağlıdır ve bilmediğiniz durumlarda yoksayılmalıdır.

Code	HTTP	Meaning
4000	400	Gövde geçerli bir JSON değil
4001	400	Bir alan doğrulamayı geçemedi veya bilinmeyen bir alan gönderildi
4002	403	Sağlayıcı hesabınız için açık değil
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 hâlâ çalışıyor
4091	409	Yinelenen istek
4093	409	Bu idempotency anahtarı farklı bir gövde ile kullanıldı
1004	403	Yetersiz bakiye
5000	500	Sunucu içi hata
5001	500	Ücret tahsilatı gerçekleştirilemedi
5002	500	Sipariş oluşturulamadı
5030	503	Sağlayıcı kullanılamıyor

Bu biçimi 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 tüm yanıtları bunlardan biri olarak ele alın:

Situation	HTTP	Body
API anahtarı yok veya kabul edilmeyen bir anahtar	401	{"detail":{"code":-1,"msg":"Invalid or missing API key"}}
Hız sınırı 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ı

Tüm tarama yolları tarafından paylaşılan saniyede 5 istek ve dakikada 150 istek.

Faturalı (Postpaid) Hesaplar

Sonradan ödemeli faturalandırma kullanan hesaplar, herkesle aynı uç noktayı, URL'yi, başlıkları ve istek gövdesini kullanır. Fark, kontrolün nasıl ödendiğindedir:

• Depozitonuzdan hiçbir şey düşülmez. Tamamlanan her kontrolün ABD doları cinsinden fiyatı (örneğin Elliptic için 0,98 $), sözleşmenizde kararlaştırılan ödeme para biriminde borç bakiyenize eklenir. Anlaşmanıza göre fatura karşılığı ödersiniz.
• Hesabınızın bir kredi limiti vardır. Ödenecek tutar limit dahilinde olduğu sürece, sıfır depozitoyla bile kontroller kabul edilir.
• Yalnızca tamamlanan kontroller faturalandırılır. Başarısız olan bir kontrol, etkinliği olmayan bir adres (skipped) ve yeniden kullanılan yakın tarihli bir sonuç hiçbir maliyet oluşturmaz.

Sonradan ödemeli faturalandırma, talep üzerine Netts tarafından bir hesap için etkinleştirilir.

Sonradan ödemeli bir kontrolün billing bloğu

"billing": {
    "charged": false,
    "price_usdt": "0.98",
    "base_amount": "2.960725",
    "markup_amount": "0",
    "charged_amount": "2.960725",
    "charged_currency": "TRX",
    "exchange_rate": "0.33100000",
    "payment_status": "postpaid"
}

Field	Description
charged	false: depozitodan hiçbir şey alınmaz
price_usdt	Kontrolün ABD doları cinsinden fiyatı. Bu, borç bakiyenize eklenen tutardır
charged_amount	Referans olması açısından TRX cinsinden aynı fiyat
payment_status	postpaid. Başarısız veya atlanan bir kontrol için — not_charged

Kredi limitine ulaşıldı (402)

{
  "type": "https://doc.netts.io/api/v2/errors/credit-limit-reached",
  "title": "Postpaid credit limit reached",
  "status": 402,
  "detail": "Postpaid credit limit reached.",
  "instance": "/apiv2/screening",
  "code": 1004,
  "payment_mode": "postpaid",
  "reason": "limit_reached"
}

Kontrol siparişi verilmez ve hiçbir ücret faturalandırılmaz. Ödemeniz kaydedildikten veya limitiniz artırıldıktan sonra yeni kontroller tekrar kabul edilir.

Sonradan ödemeli hata kodları

Code	HTTP	Description
1004	402	Sonradan ödemeli kredi limitine ulaşıldı
5032	503	Fiyat geçici olarak kullanılamıyor
5034	503	Faturalandırma geçici olarak kullanılamıyor — kontrol kabul edilmedi
5036	503	Kredi kontrolü geçici olarak kullanılamıyor — daha sonra tekrar deneyin

Yukarıdaki tüm yanıtlarda hiçbir sipariş verilmez ve hiçbir faturalandırma yapılmaz.

Notlar

• Fiyatlandırma: her sağlayıcı için kontrol başına sabit bir fiyat, bkz. GET /apiv2/screening/providers; ücret, kesinti anındaki kurdan TRX bakiyesinden alınır.
• İşlem süresi: çoğu kontrol birkaç saniye içinde biter; uzun geçmişe sahip bir adres üç dakikaya kadar sürebilir. Eşzamansız modu kullanın ve sonucu GET /apiv2/screening/{client_order_id} ile okuyun.
• Etkin olmayan adresler skipped döner ve ücretlendirilmez.
• Ham sağlayıcı yanıtı asla döndürülmez. provider_data incelenmiş bir projeksiyondur; taranan adres yerine sağlayıcıdaki hesabımıza ait olan alanlar hiç kimseye yayınlanmaz.

Reports

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 derlemek size gerçekten istediğiniz belgeyi sunar — kendi markanız, kendi diliniz, kendi düzeniniz — bu da özellikle kontrolleri yeniden satıyorsanız önemlidir, çünkü bizim adımızı taşıyan bir rapor kendi müşterinize vermek için yanlış bir 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, bir imza veya genel bir doğrulama sayfası gerektirir ve bu farklı bir özelliktir. Durumunuz buysa, karşı tarafınızın ne talep ettiğini bize bildirin.

İnsan tarafından okunabilir PDF raporları, Netts kontrol panelinde aynı kontroller için 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 sayfalandırılmış
• 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 der ve sağlayıcı bayrağı ne der