> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aegis-kyt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GET /check-transfer/{chain}/{tx_hash}
> Transaction Check (KYT) — decode an inbound tx, exposure-analyse every sender, return policy alerts. Paid $0.50.
**Tier:** \$0.50 · **Asset:** USDC · **Network:** Base
Per-tx KYT analysis. The endpoint:
1. **Decodes** the transaction on the target chain (parses Transfer
events for ERC-20 / TRC-20 + native value).
2. **Analyses every sender** via Aegis Tier 4 BFS exposure.
3. **Builds a USD-weighted composite** category vector across senders.
4. **Applies the BitOK Standard AML Policy** (281 rules) to produce
`policy_alerts[]`.
Synchronous wait up to 30 s. If the underlying check completes inside
the window, the full result body is returned (HTTP 200). If it's still
running, a 202 is returned with a `check_id` + a **free** retry URL —
you pay only once per `(chain, tx_hash)` tuple.
## Path parameters
| Name | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------ |
| `chain` | string | One of `ETH`, `BSC`, `POLYGON`, `BASE`, `ARBITRUM`, `TRON`. Case-insensitive. |
| `tx_hash` | string | 32-byte transaction hash, with or without `0x` prefix. |
## Request
```bash theme={null}
curl -H "X-PAYMENT: " \
https://x402.aegis-kyt.com/check-transfer/ETH/0x52e8e15b67b7e0d0ab86b8b8c93b5b78f7b8c93b5b78f7b8c93b5b78f7b8c93
```
## Response — 200 (completed within 30 s)
```json theme={null}
{
"check_id": "11111111-2222-3333-4444-555555555555",
"tx_hash": "0x52e8e15b…",
"chain": "ETH",
"subgroup_id": "00000000-…-system-default",
"our_receivers": [],
"parse_result": {
"sender": "0xabcdef…",
"block_time_iso": "2026-05-20T09:14:01+00:00",
"transfers": [
{
"from": "0xabcdef…",
"to": "0xrecipient…",
"asset_kind": "token",
"asset_symbol": "USDT",
"asset_decimals": 6,
"amount_raw": "1500000"
}
]
},
"unsupported_assets": [],
"composite_result": {
"categories": { "exchange": 0.85, "mixer": 0.02 },
"worst_category": "exchange",
"worst_share": 0.85,
"pricing_meta": {
"stale_any": false,
"unknown_any": false,
"symbols": [
{"symbol": "USDT", "source": "stablecoin"}
]
}
},
"policy_result": {
"alerts": [
{
"category": "Mixer",
"riskLevel": "Medium",
"ruleType": "Origin of funds / Indirect",
"actualShare": 2.0,
"thresholdShare": 1,
"thresholdValue": 10,
"entityName": "Sender 0xab…ef01 (exposed to mixer)",
"entityAddress": "0xabcdef…",
"direction": "incoming",
"entityScore": 0
}
],
"worst_alert_level": "Medium",
"triggered_count": 1,
"triggered_categories": 1
},
"alerts_dispatched": false,
"status": "completed",
"created_at": "2026-05-20T09:13:55Z",
"completed_at": "2026-05-20T09:14:01Z"
}
```
## Response — 202 (still running past 30 s)
```json theme={null}
{
"status": "timeout",
"message": "tx_check still running after 30s — retry via GET /check-transfer-result/ (free, no payment)",
"check_id": "11111111-2222-3333-4444-555555555555",
"retry_url": "/check-transfer-result/11111111-2222-3333-4444-555555555555",
"progress": { "parsed": true, "exposed": 2, "aggregated": false, "alerted": false }
}
```
Fetch the deferred result for free via the retry URL — see
[/check-transfer-result/{check_id}](/endpoints/check-transfer-result).
## Sender attribution semantics
The `entityName` / `entityAddress` on each policy alert reference the
**top-USD sender** that exposes the category, **not the dirty entity
itself**. Format: `Sender (exposed to )`.
A row reading `Sender 0xab…ef01 (exposed to mixer)` means: this
address sent value into the analysed transaction, AND this address
has historical exposure to Mixer category through its own activity —
NOT that the address IS a mixer.
This indirection matters for compliance reporting; see the docstring
in `aggregator.py` for the trade-off rationale.
## Errors
| Status | Code | Meaning |
| ------ | --------------------------- | -------------------------------------------------------------------- |
| 400 | `bad_request` | Unsupported chain slug, or `tx_hash` doesn't match the 32-byte regex |
| 402 | (x402) | Missing or invalid `X-PAYMENT` proof |
| 502 | `tx_check_failed_parse` | Transaction not found on chain, or unparseable |
| 502 | `tx_check_failed_rpc` | Etherscan / TronGrid rate-limit or 5xx after 3 retries |
| 502 | `tx_check_failed_aggregate` | Composite aggregator crashed (rare) |
| 502 | `upstream_unavailable` | Internal aegis-api unreachable |
Failure responses include the `check_id` so you can correlate logs.
**No refund on failure** — same doctrine as `/check-address`.
## OpenAPI
````yaml GET /check-transfer/{chain}/{tx_hash}
openapi: 3.1.0
info:
title: Aegis KYT x402 API
description: >-
Pay-per-call AML API for AI agents. USDC on Base, no API keys, no account
creation. See https://docs.aegis-kyt.com for the full endpoint reference.
version: 0.2.0
servers:
- url: https://x402.aegis-kyt.com
description: Production
security: []
paths:
/check-transfer/{chain}/{tx_hash}:
get:
summary: '$0.50 — Transaction Check (KYT): decode + Tier 4 BFS + policy → alerts'
operationId: tier_screen_tx_screen_tx__chain___tx_hash__get
parameters:
- name: chain
in: path
required: true
schema:
type: string
title: Chain
enum:
- ETH
- BSC
- POLYGON
- BASE
- ARBITRUM
- TRON
- name: tx_hash
in: path
required: true
schema:
type: string
title: Tx Hash
pattern: ^(0x)?[0-9a-fA-F]{64}$
responses:
'200':
description: Completed — full TxCheckResult body
content:
application/json:
schema:
type: object
additionalProperties: true
title: TxCheckResult
example:
schema_version: 1
check_id: 8f1f1c2e-4b8e-4f6a-9b3c-2a7d9e5c1f00
status: completed
chain: TRON
tx_hash: >-
3dba6516a1f9a1b2c3d4e5f60718293a4b5c6d7e8f901234567890abcdef1234
parse_result:
transfers:
- from: TXmVpin5vq5gdZsciyyjdZgKRUju4st1wM
to: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
asset: USDT
value: '2500.000000'
value_usd: 2500
composite_result:
risk_level: medium
risk_score: 38
risk_categories:
- sanctions_exposure
origin_sources:
- category: exchange
share: 0.81
- category: sanctions_exposure
share: 0.19
cold_enrich:
candidates: 1
folded: 1
policy_result:
risk_level: medium
alerts: []
policy: standard
decode_warnings: []
'202':
description: Still running — retry via /check-transfer-result/{check_id} (free)
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- timeout
message:
type: string
check_id:
type: string
format: uuid
retry_url:
type: string
progress:
type: object
additionalProperties: true
example:
status: timeout
check_id: 8f1f1c2e-4b8e-4f6a-9b3c-2a7d9e5c1f00
retry_url: /check-transfer-result/8f1f1c2e-4b8e-4f6a-9b3c-2a7d9e5c1f00
'400':
description: Bad chain or tx_hash
content:
application/json:
example:
error:
code: bad_request
message: invalid tx hash
'402':
description: Missing or invalid x402 payment proof
content:
application/json:
example:
error:
code: payment_required
message: x402 payment authorization required
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
example:
detail:
- loc:
- body
- address
msg: Field required
type: missing
'502':
description: Upstream tx_check failed_* or aegis-api unreachable
content:
application/json:
example:
error:
code: upstream_failed
message: decode failed — charge not taken
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
````