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

# POST /v2/check-address

> Single-provider AML check on one address.

<Note>
  **Auth:** Required · **Billing:** per your plan (commercial agreement)
</Note>

Run the full Aegis 4-tier verdict on a single address.  Aegis-only — third-party providers run under the hood when the on-chain graph is sparse (opt-in), not as a selectable option.

<Warning>
  **This endpoint never blocks.** It always answers **202** with a `check_id`;
  the verdict comes from
  [`GET /v2/check-address/{check_id}/result`](/api-reference/v2-check-address-result).
  Billing fires **once**, on the first successful delivery of that result — not
  on submit. Polling early, or polling again later, never charges twice.
</Warning>

## Request

```bash theme={null}
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"
  }'
```

| Field     | Type   | Notes                                                               |
| --------- | ------ | ------------------------------------------------------------------- |
| `address` | string | EVM hex (auto-lowercased) or base58 (TRON/BTC/SOL — case preserved) |
| `network` | string | Case-insensitive.  Must be one of {BSC, ETH, TRON}.                 |

Optional headers:

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

## Response 202 — accepted

```json theme={null}
{
  "status": "queued",
  "check_id": "3f8c1e2a-...",
  "address": "TScSLnUodZVsgoGchZspDoimDjDB9bwqVv",
  "network": "TRON",
  "message": "check queued — poll GET /v2/check-address/{check_id}/result",
  "result_url": "/v2/check-address/3f8c1e2a-.../result"
}
```

Poll `result_url` every few seconds. Typical completion is 5-90 s; a cold BFS
can take longer. Network must be one of {BSC, ETH, TRON} — anything else is
rejected with HTTP 400 **before** a job is created.

## The verdict

Delivered by
[`GET /v2/check-address/{check_id}/result`](/api-reference/v2-check-address-result),
which is where the response body and its fields are documented.

**`decision`** (top-level) is the merchant traffic-light — one of
`accept` · `review` · `reject` · `unable`. Build your accept/block flow on
this field:

| `decision` | Meaning                                       |
| ---------- | --------------------------------------------- |
| `accept`   | no risk signals found                         |
| `review`   | elevated / borderline — your operator decides |
| `reject`   | high risk (sanctions / criminal exposure)     |
| `unable`   | no data to assess — do **not** treat as clean |

`decision` is a probabilistic risk signal, not a command to accept/reject and
not legal advice — the final decision and risk are yours.

`verdict.risk_level` / `verdict.risk_score` give the detail behind the
decision; `verdict.tier3_applied` / `tier4_applied` show which depth tiers
ran (`tier4_applied: false` may mean too few transactions for BFS — Tier
0+1+2 still executed).

## Errors

| HTTP | code                     | Why                                                                                              |
| ---- | ------------------------ | ------------------------------------------------------------------------------------------------ |
| 400  | `bad_request`            | malformed address, or `network` not a known chain                                                |
| 400  | `unsupported_network`    | valid chain, but not one Aegis ingests                                                           |
| 401  | `missing_or_invalid_key` | Bearer header missing or wrong                                                                   |
| 402  | `insufficient_funds`     | USD balance empty — see [GET /v2/balance](/api-reference/v2-balance)                             |
| 402  | `monthly_cap_exceeded`   | monthly spending cap reached (a cap is optional; it can bite while the balance is still healthy) |
| 409  | `idempotency_conflict`   | same key + different body within 24h                                                             |

Failures of the check itself surface on the **poll**, not here — this endpoint
only accepts the job.

## See also

* [V2 introduction](/api-reference/v2-introduction)
* [POST /v2/check-transfer](/api-reference/v2-check-transfer) — Transaction Check (KYT)
* [GET /v2/check-address/{check_id}/result](/api-reference/v2-check-address-result) — the verdict
* [GET /v2/balance](/api-reference/v2-balance) — what is left to spend
* [GET /v2/me/usage](/api-reference/v2-me-usage) — billing snapshot + call history


## OpenAPI

````yaml POST /check-address
openapi: 3.1.0
info:
  description: >-
    Public, subscription-billed AML API. Send `Authorization: Bearer aeg_<key>`
    on every call.  See the user kabinet at
    https://app.aegis-kyt.com/account?tab=api to generate a key.
  title: Aegis Public API
  version: 2.0.0
servers:
  - description: Production
    url: https://api.aegis-kyt.com/v2
security: []
paths:
  /check-address:
    post:
      tags:
        - v2-public
      summary: Aegis full 4-tier verdict (SDN + consensus + 1-hop + BFS) — submit
      description: >-
        Submits an address for the full Aegis Tier 0..4 pipeline (SDN +
        consensus + 1-hop + BFS).  Always returns **202** immediately with a
        `check_id` — this endpoint never blocks waiting for the engine.  Fetch
        the verdict from `GET /v2/check-address/{check_id}/result` (poll every
        few seconds; typical completion is 5-90s, occasionally longer on a cold
        BFS).  Billing fires once, on first successful delivery of the result —
        polling before completion, or polling again after, never charges twice.


        Aegis-only: third-party KYT providers are no longer selectable at this
        surface — when the on-chain graph is sparse they run under the hood via
        the Aegis fallback waterfall (opt-in).  Supported on BSC/ETH/TRON.


        Send `Idempotency-Key: <token>` header to make retries safe —
        resubmitting the same key returns the SAME check_id instead of starting
        a duplicate job.
      operationId: check_address_check_address_post
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckAddressRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                title: Response Check Address Check Address Post
                type: object
          description: Successful Response
        '202':
          description: Check queued — poll GET /v2/check-address/{check_id}/result
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '502':
          description: Idempotent replay landed on a failed check (no charge)
      security:
        - ApiKeyBearer: []
components:
  schemas:
    CheckAddressRequest:
      properties:
        address:
          description: >-
            On-chain wallet.  EVM is lowercased internally; TRON/BTC/SOL
            preserved.
          examples:
            - TScSLnUodZVsgoGchZspDoimDjDB9bwqVv
            - '0x21a31ee1afc51d94c2efccaa2092ad1028285549'
          maxLength: 120
          minLength: 1
          title: Address
          type: string
        network:
          description: Chain identifier.  See `/v2/networks` for allowed values.
          examples:
            - TRON
            - ETH
          maxLength: 20
          minLength: 1
          title: Network
          type: string
      required:
        - address
        - network
      title: CheckAddressRequest
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    ApiKeyBearer:
      description: Your `aeg_…` API key from the dashboard (Account → API tab).
      scheme: bearer
      type: http

````