POST /v2/screen

Cheap labels + consensus risk (Tier 0+1+2)

curl --request POST \
  --url https://api.aegis-kyt.com/v2/screen \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
  "network": "TRON"
}
'

import requests

url = "https://api.aegis-kyt.com/v2/screen"

payload = {
    "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
    "network": "TRON"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({address: 'TScSLnUodZVsgoGchZspDoimDjDB9bwqVv', network: 'TRON'})
};

fetch('https://api.aegis-kyt.com/v2/screen', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "schema_version": 6,
  "address": "0x21a31ee1afc51d94c2efccaa2092ad1028285549",
  "network": "ETH",
  "provider": "Aegis",
  "verdict": {
    "risk_level": "low",
    "risk_score": 12,
    "risk_categories": [
      "exchange"
    ],
    "consensus_found": true,
    "label": "Binance.com",
    "sdn_match": null,
    "labels": [
      {
        "source": "graphsense-tagpacks",
        "source_name": "GraphSense TagPacks",
        "label": "Binance.com",
        "category": "exchange",
        "confidence": 92,
        "first_seen_at": "2025-08-12T00:00:00+00:00",
        "last_seen_at": "2026-04-29T00:00:00+00:00"
      }
    ],
    "smart_contract": null,
    "entity": {
      "slug": "binance-com",
      "name": "Binance",
      "category": "centralized_exchange",
      "logo_url": "https://cdn.jsdelivr.net/gh/maslovsa/kyt-entity-registry@main/logos/exchanges/binance-com.png",
      "logo_source": "registry"
    }
  },
  "billing": {
    "model": "ledger",
    "charged_usd": "0.100000",
    "balance_usd": "42.500000",
    "monthly_spent_usd": "12.300000",
    "monthly_cap_usd": "500.000000"
  },
  "elapsed_ms": 240
}

{
  "detail": [
    {
      "loc": [
        "body",
        "address"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

POST

screen

Cheap labels + consensus risk (Tier 0+1+2)

curl --request POST \
  --url https://api.aegis-kyt.com/v2/screen \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
  "network": "TRON"
}
'

import requests

url = "https://api.aegis-kyt.com/v2/screen"

payload = {
    "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
    "network": "TRON"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({address: 'TScSLnUodZVsgoGchZspDoimDjDB9bwqVv', network: 'TRON'})
};

fetch('https://api.aegis-kyt.com/v2/screen', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "schema_version": 6,
  "address": "0x21a31ee1afc51d94c2efccaa2092ad1028285549",
  "network": "ETH",
  "provider": "Aegis",
  "verdict": {
    "risk_level": "low",
    "risk_score": 12,
    "risk_categories": [
      "exchange"
    ],
    "consensus_found": true,
    "label": "Binance.com",
    "sdn_match": null,
    "labels": [
      {
        "source": "graphsense-tagpacks",
        "source_name": "GraphSense TagPacks",
        "label": "Binance.com",
        "category": "exchange",
        "confidence": 92,
        "first_seen_at": "2025-08-12T00:00:00+00:00",
        "last_seen_at": "2026-04-29T00:00:00+00:00"
      }
    ],
    "smart_contract": null,
    "entity": {
      "slug": "binance-com",
      "name": "Binance",
      "category": "centralized_exchange",
      "logo_url": "https://cdn.jsdelivr.net/gh/maslovsa/kyt-entity-registry@main/logos/exchanges/binance-com.png",
      "logo_source": "registry"
    }
  },
  "billing": {
    "model": "ledger",
    "charged_usd": "0.100000",
    "balance_usd": "42.500000",
    "monthly_spent_usd": "12.300000",
    "monthly_cap_usd": "500.000000"
  },
  "elapsed_ms": 240
}

{
  "detail": [
    {
      "loc": [
        "body",
        "address"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Auth: Required · Cost: 0.1 credit per call (1 credit = 1 USDT of top-up) · Provider: Aegis only (Tier 0+1+2 — no graph traversal, no external providers)

The same SQL queries that x402-api’s $0.10 GET /screen/{chain}/{address} runs, billed as 0.1 credit against your credit balance instead of via on-chain USDC. Designed for high-volume B2B integrations: a wallet running a pre-send screen on every user-typed address will use this endpoint, not /v2/check-address. Same compute as x402’s /screen, but settled off-chain against your credit balance instead of an on-chain USDC transfer — no per-call settlement gas to amortise.

Request

curl -X POST https://api.aegis-kyt.com/v2/screen \
  -H "Authorization: Bearer aeg_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
    "network": "TRON"
  }'

Field	Type	Notes
`address`	string	EVM hex (auto-lowercased) or base58 (TRON/BTC/SOL — case preserved)
`network`	string	Case-insensitive. Currently BSC, ETH, TRON (full Tier 0+1+2) and TON (label-only — see Networks). Other networks return `400 unsupported_network`

There is no provider field — screen always runs Aegis (Tier 0+1+2). For the full 4-tier verdict (with 1-hop + BFS exposure), use POST /v2/check-address. Optional headers:

Header	Purpose
`Idempotency-Key: <≤64 chars>`	Replay-safe within 24h. Same key + same body → cached response, no charge. Different body → HTTP 409.

TON example

TON is a label-only network: the answer comes from labels and sanctions lists, and coverage.network_coverage says so explicitly (onchain_graph: false). A confirmed centralized-exchange wallet reads low with a score of at most 5, as on every other network.

curl -X POST https://api.aegis-kyt.com/v2/screen \
  -H "Authorization: Bearer aeg_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "UQDKHZ7e70CzqdvZCC83Z4WVR8POC_ZB0J1Y4zo88G-zCSRH",
    "network": "TON"
  }'

{
  "schema_version": 6,
  "address": "UQDKHZ7e70CzqdvZCC83Z4WVR8POC_ZB0J1Y4zo88G-zCSRH",
  "network": "TON",
  "provider": "Aegis",
  "coverage": {
    "data_available": true,
    "label_count": 1,
    "sdn_checked": true,
    "consensus_found": true,
    "tiers": [
      "sdn",
      "consensus"
    ],
    "graph_analysed": false,
    "live_enrichment": "none",
    "network_coverage": {
      "onchain_graph": false,
      "onchain_stats": "unavailable",
      "basis": [
        "labels",
        "sanctions",
        "provider_screening"
      ],
      "balance": "provider_screening",
      "note": "The verdict is based on address labels, sanctions lists and external risk screening; this response carries no transaction analysis."
    }
  },
  "verdict": {
    "ok": true,
    "risk_level": "low",
    "risk_score": 5,
    "risk_categories": [
      "exchange"
    ],
    "consensus_found": true,
    "label": "Binance",
    "sdn_match": null,
    "labels": [
      {
        "source": "ton-labels",
        "source_name": "TON Community Labels",
        "label": "Binance",
        "category": "exchange",
        "confidence": null,
        "source_url": "https://binance.com",
        "first_seen_at": "2026-10-15T09:42:48.040825+00:00",
        "last_seen_at": "2026-10-15T09:42:48.040825+00:00"
      }
    ],
    "smart_contract": {
      "is_contract": true,
      "token_contract": false,
      "kind": "contract",
      "symbol": null,
      "decimals": null,
      "is_well_known": false,
      "logo_url": null,
      "primary_entity": null,
      "complementary_entities": [
        {
          "slug": "binance-com",
          "display_name": "Binance",
          "category": "centralized_exchange",
          "logo_url": null,
          "registry_slug": "binance-com"
        }
      ]
    },
    "entity": {
      "slug": "binance-com",
      "name": "Binance",
      "category": "centralized_exchange",
      "logo_url": null,
      "logo_source": null
    }
  }
}

TON addresses are case-sensitive; any spelling (UQ…, EQ…, raw 0:<hex>) is accepted and returned as the canonical UQ… form.

Response 200

{
  "schema_version": 6,
  "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
  "network": "TRON",
  "provider": "Aegis",
  "coverage": {
    "data_available":  true,
    "label_count":     3,
    "sdn_checked":     true,
    "consensus_found": true,
    "tiers":           ["sdn", "consensus"],
    "graph_analysed":  false
  },
  "verdict": {
    "ok":                  true,
    "risk_level":          "medium",
    "risk_score":          50,
    "risk_categories":     ["sanctions_exposure"],
    "consensus_found":     true,
    "label":               "Some Exchange",
    "sdn_match":           null,
    "labels": [
      {
        "source":        "graphsense-tagpacks",
        "source_name":   "GraphSense TagPacks",
        "label":         "Some Exchange",
        "category":      "exchange",
        "confidence":    78,
        "source_url":    "https://…",
        "first_seen_at": "2025-09-12T00:00:00Z",
        "last_seen_at":  "2026-04-29T00:00:00Z"
      }
    ],
    "smart_contract": {
      "is_contract":            false,
      "token_contract":         false,
      "symbol":                 null,
      "decimals":               null,
      "is_well_known":          false,
      "logo_url":               null,
      "primary_entity":         null,
      "complementary_entities": []
    },
    "entity": null
  },
  "billing": {
    "model":              "ledger",
    "currency":           "USD",
    "charged_usd":        0.1,
    "balance_usd":        15.9,
    "monthly_spent_usd":  0.1,
    "monthly_cap_usd":    null,
    "replay":             false,
    "unit":                  "credits",
    "credits_charged":       0.1,
    "credits_balance":       15.9,
    "credits_monthly_spent": 0.1,
    "credits_monthly_cap":   null
  },
  "elapsed_ms": 60
}

`coverage` — read this before `risk_level`

risk_level: "none" means we found no risk signal, which is not the same as “this address is clean”. For an address nobody has ever enriched, a Tier 0+1+2 screen has nothing to say, and the honest verdict shape for that is none / 0. coverage.data_available is the field that tells the two apart:

"coverage": {
  "data_available":  false,
  "label_count":     0,
  "sdn_checked":     true,
  "consensus_found": false,
  "tiers":           ["sdn", "consensus"],
  "graph_analysed":  false
}

Do not gate a transfer on risk_level === "none" alone. Treat coverage.data_available: false as unknown, not as clean — decide in your own policy whether unknown means allow, review, or escalate to /v2/check-address, which runs the full 4-tier analysis including the address’s counterparties.

graph_analysed is always false here by design — this endpoint never looks at who the address transacts with. An address that screens none can still come back high from /v2/check-address because its counterparties are what carry the risk. That is not a contradiction between two products; it is two different questions.

Field	Type	Notes
`data_available`	bool	`false` → we hold no SDN hit, no consensus row and no label claims for this address
`label_count`	int	Rows in `verdict.labels[]`
`sdn_checked`	bool	Always `true` — the sanctions lookup always runs
`consensus_found`	bool	Mirror of `verdict.consensus_found`
`tiers`	string[]	Analysis tiers this call ran
`graph_analysed`	bool	Always `false` — no 1-hop, no BFS

Quota is charged whether or not we had data — the customer paid for the lookup, not for a guarantee of a hit.

Source naming

Every source named in this response is either Aegis itself or an openly licensed public source — sanctions registries (ofac-sdn, uk-ofsi-sanctions, eu-cfsp-sanctions), stablecoin issuer blacklists (tether-blacklist, circle-blacklist), open label registries (graphsense-tagpacks, ethereum-lists, …) and our own curated VASP registry. Their identity is the evidence, so they are cited by name. Labels from our internal working sources are not listed. Aegis also blends licensed commercial intelligence into its own verdict. That data moves risk_level / risk_score / risk_categories, but it is never returned as a row, a source slug or a label. The sources you see listed are therefore a subset of what moved the verdict — that gap is intentional. label is the owner’s name (the entity name when one is resolved, the token’s symbol for an ownerless token contract) or null. It is null whenever the name would come from a source we don’t publish, or the underlying claim is a risk annotation rather than an identity.

`verdict` object

Field	Type	Notes
`ok`	bool	Always `true` when status is 200
`risk_level`	enum \| null	`none` / `low` / `medium` / `high` / `critical` / `sanctioned`
`risk_score`	int 0..100 \| null	Aggregated across sources
`risk_categories`	string[]	Slugs only — see risk categories
`consensus_found`	bool	`false` → no consensus row exists for this address
`label`	string \| null	Best human-readable NAME, or `null` when every claim is a risk annotation rather than an identity
`sdn_match`	object \| null	Tier-0 sanctions hit (OFAC SDN / UK OFSI / EU)
`labels[]`	array	Per-source label rows — same shape as x402 `/screen`. See Source naming above
`smart_contract`	object	Contract / token metadata for the address. Always present; `is_contract: false` for ordinary wallets
`entity`	object \| null	VASP that owns the address, with a PNG logo — `{slug, name, category, logo_url, logo_source}`. `null` when there is no corroborated VASP link (not “clean”), on hack / scam-class verdicts, and for unattributed placeholders. `logo_url` is an absolute https URL of a 160×160 transparent PNG, or `null` (draw your own placeholder). `logo_source`: `registry` (open kyt-entity-registry via jsDelivr) · `upload` · `null`. The image can be replaced over time — cache it, don’t treat the URL as immutable. Example: `{"slug":"binance-com","name":"Binance","category":"centralized_exchange","logo_url":"https://cdn.jsdelivr.net/gh/maslovsa/kyt-entity-registry@main/logos/exchanges/binance-com.png","logo_source":"registry"}`

Errors

Same envelope as POST /v2/check-address. Notable codes:

HTTP	code	Why
400	`bad_request`	empty address / unknown network
400	`unsupported_network`	`network` not supported (currently BSC / ETH / TRON / TON). Body has `supported_networks`
401	`missing_api_key`	no `Authorization: Bearer …`
401	`invalid_api_key`	unknown / revoked
402	`insufficient_funds`	credit balance too low; body has a `billing` envelope with the shortfall (`balance_usd`/`requested_usd` and the same values as `balance_credits`/`requested_credits`). The `message` text prints `$` — parse the numeric fields
409	`idempotency_conflict`	same `Idempotency-Key`, different body
502	`backend_unavailable`	Supabase reachability failed. Charge refunded.

Pricing vs x402 `/screen`

This endpoint and x402 /screen return the same data — same SQL queries, same labels[] shape, same risk fields. They differ only in the commercial rail:

	V2 `/v2/screen`	x402 `/screen`
Audience	B2B partners (wallets, exchanges)	AI agents, anonymous
Settlement	Credit balance debited per call (off-chain ledger)	USDC on Base, settled per call (`$0.10` floor — gas + facilitator fee)
Onboarding	Generate `aeg_…` key in your kabinet	Sign EIP-3009 transferAuthorization
Auth	`Authorization: Bearer aeg_…`	None — payment IS the auth

If you’re a wallet putting this behind a “send to address” prompt for thousands of end-users, V2 is the right channel — same data, no on-chain settlement step on each call. Talk to sales for volume pricing.

Get started

Authentication

x402 Endpoints (USDC pay-per-call)

V2 Public API

Webhooks (push events)

Methodology

Reference

Other

Request

TON example

Response 200

`coverage` — read this before `risk_level`

Source naming

`verdict` object

Errors

Pricing vs x402 `/screen`

See also

Authorizations

Headers

Body

Response

​Request

​TON example

​Response 200

​coverage — read this before risk_level

​Source naming

​verdict object

​Errors

​Pricing vs x402 /screen

​See also

Authorizations

Headers

Body

Response

Request

TON example

Response 200

`coverage` — read this before `risk_level`

Source naming

`verdict` object

Errors

Pricing vs x402 `/screen`

See also