> ## 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.

# V2 Public API

> Subscription-billed AML API — per-user quota, X-API-Key auth.

<Note>
  **Surface:** `https://api.aegis-kyt.com/v2/*`
</Note>

The V2 API is the **subscription-billed** counterpart to x402.  Where
x402 is per-call USDC for AI agents that don't want accounts, V2 is
the traditional API model for businesses that want monthly quotas,
predictable bills, and human-issued keys.

|            | V2 API                                 | x402 API                        |
| ---------- | -------------------------------------- | ------------------------------- |
| Auth       | `Authorization: Bearer aeg_<48 chars>` | x402 protocol (HTTP 402 + USDC) |
| Billing    | Monthly quota (default 15/mo)          | Per-call USDC on Base           |
| Customer   | Has account on app.aegis-kyt.com       | Anonymous AI agent              |
| Onboarding | Sales contact → API key generated      | None — discover & pay           |
| Hosted at  | `api.aegis-kyt.com/v2/*`               | `x402.aegis-kyt.com/*`          |

Both surfaces run the SAME Aegis 4-tier engine + same external
providers (provider\_b, provider\_a).  Pick whichever fits your usage model.

## Pricing vs x402 — same logic, different channels

Some V2 endpoints return data that x402 also sells.  The compute is
identical (same SQL, same Python aggregator) — what differs is the
settlement rail:

|                | V2 (this surface)                               | x402                                                                   |
| -------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
| **Settlement** | Subscription quota debited per call (off-chain) | USDC on Base, settled per call (`$0.10` floor — gas + facilitator fee) |
| **Auth model** | API key (one per user)                          | None — payment IS the auth                                             |
| **Audience**   | B2B partners (wallets, exchanges, PSPs)         | AI agents, no human in the loop                                        |

Most direct overlap:

| V2 endpoint                                                 | x402 endpoint                                                      | Same data?            |
| ----------------------------------------------------------- | ------------------------------------------------------------------ | --------------------- |
| [POST /v2/screen](/api-reference/v2-screen)                 | [GET /screen/{chain}/{address}](/endpoints/screen)                 | ✅ identical SQL       |
| [POST /v2/check-address](/api-reference/v2-check-address)   | [GET /check-address/{chain}/{address}](/endpoints/check-address)   | ✅ same 4-tier verdict |
| [POST /v2/check-transfer](/api-reference/v2-check-transfer) | [GET /check-transfer/{chain}/{tx_hash}](/endpoints/check-transfer) | ✅ same KYT pipeline   |

Practical consequence: if you're a partner wallet putting a screen
behind every "send to address" prompt for your users — use the V2
API.  x402 is for callers who don't have an account relationship
with us.

## Quickstart

```bash theme={null}
# 1) Generate an API key in your kabinet:
#    https://app.aegis-kyt.com/account?tab=api → "Generate key"
#    Copy the 48-character `aeg_…` value (shown once).

# 2) Call from anywhere, anytime:
curl -X POST https://api.aegis-kyt.com/v2/check-address \
  -H "Authorization: Bearer aeg_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
    "network": "TRON"
  }'
```

## Endpoints

| Method | Path                                                     | Auth     | Billing  |
| ------ | -------------------------------------------------------- | -------- | -------- |
| GET    | `/v2/health`                                             | free     | free     |
| GET    | `/v2/networks`                                           | free     | free     |
| POST   | [`/v2/screen`](/api-reference/v2-screen)                 | required | per plan |
| POST   | [`/v2/check-address`](/api-reference/v2-check-address)   | required | per plan |
| POST   | [`/v2/check-transfer`](/api-reference/v2-check-transfer) | required | per plan |
| GET    | `/v2/me/usage`                                           | required | free     |

Billing is per your plan / commercial agreement.
See the per-endpoint pages for full request/response shapes.

## Authentication

```
Authorization: Bearer aeg_<48 chars>
```

* One active key per user.
* Plaintext shown once at creation.  Server stores SHA-256 only.
* Revoke / rotate via `/account?tab=api` in your kabinet.
* Missing or invalid key → **HTTP 401**.

## Quota

Each successful call deducts quota units from your monthly balance.  Cost
per call:

| Provider    | Units | Networks       |
| ----------- | ----- | -------------- |
| Aegis       | 1     | BSC, ETH, TRON |
| provider\_b | 1     | BSC, ETH, TRON |
| provider\_a | 1     | BSC, ETH, TRON |

* Consensus charges the **sum** of providers that ran.
  Unsupported-network skips are **free**.
* Quota exceeded → **HTTP 402** with `code: quota_exceeded`.
* Current quota and balance: call `GET /v2/me/usage` or visit your
  kabinet at [app.aegis-kyt.com](https://app.aegis-kyt.com/account?tab=api).

### Refund policy

| Scenario                                                             | Refund?                              |
| -------------------------------------------------------------------- | ------------------------------------ |
| Single provider call fails (502)                                     | ✅ full refund                        |
| `/v2/screen` Supabase-reachability fails (502 `backend_unavailable`) | ✅ full refund                        |
| Consensus partial fail (some ok)                                     | ❌ no refund (you got partial result) |
| Consensus all-fail (502)                                             | ✅ full refund                        |

## Idempotency-Key

Send `Idempotency-Key: <≤64 chars>` header to make retries safe:

* Same key + same body within 24h → cached response, **no charge**
* Same key + DIFFERENT body → HTTP 409 `idempotency_conflict`

Use any high-entropy token (UUID v4 recommended).