Status: private / entitled-only. The endpoint exists in production but
your aeg_… bearer must be flipped consensus_enabled = true by an Aegis
operator. Until then the call returns 403 consensus_not_entitled. Reach
out via the channel in your onboarding email.
Request
curl -X POST https://api.aegis-kyt.com/v2/inspect-address \
-H "Authorization: Bearer aeg_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: idem-2026-06-17-7a3c" \
-d '{
"address": "0x28C6c06298d514Db089934071355E5743bf21d60",
"network": "ETH"
}'
| Field | Type | Required | Notes |
|---|
address | string (1–120) | yes | EVM hex (auto-lowercased) or TRON base58. |
network | string | yes | ETH · BSC · TRON only. Others → 400 unsupported_network. |
providers | string[] | no | Subset of your entitled providers. Default = your saved active subset. Anything outside entitlement is silently dropped; globally-disabled providers are waived (not charged). aegis is always included. |
| Header | Purpose |
|---|
Idempotency-Key: <≤64 chars> | Strongly recommended. Replay-safe within 24h. Same key + same body → cached response, no second charge. Different body → 409 idempotency_conflict. Required to safely retry across 504 / TCP-disconnect. |
Synchronous, with a 202 fallback
The endpoint waits up to ~115s for completion (BFS-heavy graphs are slow on cold
cache; partner SLA targets resolve before this). Three outcomes:
- 200 — completed. Body carries the synthesized
final audit + each
provider’s raw verdict + a billing envelope. Charged once.
- 202 — still running past the sync budget. Body is
{ check_id, retry_url, created_at }. Fetch the verdict via the free
GET /v2/inspect/{check_id}/result — you are billed once
between the 202 and the eventual 200, never twice.
- 402 —
insufficient_funds / monthly_cap_exceeded.
- 403 —
consensus_not_entitled — your key is not flipped to consensus
yet (entitlement gate, see Note at top).
- 409 —
idempotency_conflict — same key + different body within 24h.
- 504 — gateway timeout (cold-graph BFS exceeded the wall-clock cap).
Nothing charged. Retry with the same
Idempotency-Key to get a 200
or 202 — the retry rides whatever pipeline the first attempt started.
Billing semantics on disconnect
The contract is at-most-once charge, anchored by row-stable idempotency:
| Event | Charge state |
|---|
| 200 with verdict | charged once (deduped if you replay with the same Idempotency-Key) |
202 with check_id | charged once on the first successful delivery — i.e. the eventual 200 on the poll URL, not the 202 itself |
| Client TCP disconnect between 202 and poll | charge still attached to that check_id; poll the result URL when you reconnect to get the verdict you already paid for |
| 504 gateway timeout | not charged; retry safely with the same Idempotency-Key |
| 502 / 503 from a downstream provider | not charged; result returns {ok: false, error} on that provider; the rest of the fan-out completes and is charged |
| Hard-fail past the wall-clock cap (rare) | reaper marks the row failed_timeout at 15m; if you were upfront-charged the refund posts automatically with idem-key refund:{check_id} (kya-session path only; /v2/inspect-address is charge-on-success so the refund-on-hard-fail branch does not apply) |
Idempotency-Key carries one charge across an
arbitrary number of retries / reconnects in the 24h window. Reuse it; never
rotate per-attempt.
Poll
curl https://api.aegis-kyt.com/v2/inspect/<check_id>/result \
-H "Authorization: Bearer aeg_YOUR_KEY_HERE"
- 200 — verdict, charged once on the first successful delivery.
- 202 — still running; poll again after a short backoff (start at 2s,
cap at 10s — there’s no rate-limit penalty for polling but no benefit
past 10s either).
- 404 — unknown
check_id or not owned by the caller.
- 502 — pipeline error; not charged.
See also
