AML Address Checks

Last updated: 2026-10-16

Screen any wallet address for anti-money-laundering (AML) risk before you accept funds from it or pay out to it. A check returns an Elliptic risk score, a risk level, sanctions exposure and the risk detail behind the score.

For a quick, cheaper yes/no verdict on a TRON address (sanctions, Tether freezes, scam labels), see TRON Address Compliance Checks.

Overview

1. Run a check — POST /api/aml-checks with the address and its network.
2. Read the result — most checks settle within seconds and return the result directly. If the check is still running you get 202 with status: "PENDING"; poll GET /api/aml-checks/{checkId} until it settles.
3. Decide — apply your own policy to riskLevel, riskScore and isSanctioned (for example, hold deposits from high-risk or sanctioned addresses for manual review).

Price

The fee is reserved from your balance when the check starts (it shows under pending in GET /api/balance), then either charged on a result or returned to available. It appears in your fee ledger as an AML Check Fee charge.

Which balance pays: send feeCurrency and feeNetwork together to choose. Without them the fee is taken from the screened network's balance (USDT first, then USDC), then from USDT on TRX, then from your largest balance. A check is refused with 400 INSUFFICIENT_BALANCE if no balance can cover the fee, and nothing is reserved.

Supported networks

AML checks cover the networks live on DCE:

Testnet networks (TRX_NILE, tBNB, POL_AMOY, SEP) cannot be screened. GET /api/aml-checks returns the networks you can screen right now in service.supportedNetworks.

Run a check

POST /api/aml-checks
Authorization: <API key>
Content-Type: application/json

{
  "address": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
  "network": "TRX",
  "referenceId": "kyc-customer-1842"
}

Only write-capable merchant API keys can run checks.

Response

200 once settled, 202 while pending:

{
  "success": true,
  "check": {
    "id": "cmg4x0amz0001",
    "referenceId": "kyc-customer-1842",
    "address": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
    "network": "TRX",
    "provider": "elliptic",
    "status": "COMPLETED",
    "riskScore": "7.4",
    "riskLevel": "high",
    "isSanctioned": true,
    "sanctions": {
      "self": false,
      "exposure": { "share": 12.5, "hops": 2, "proximity": "indirect" }
    },
    "fee": { "amount": "1.5", "currency": "USDT", "network": "TRX", "status": "CHARGED" },
    "error": null,
    "result": {
      "risk_score_detail": { "source": 7.4, "destination": 0 },
      "contributions": { "source": [], "destination": [] },
      "cluster_entities": [],
      "evaluation_detail": { "source": [], "destination": [] },
      "detected_behaviors": []
    },
    "createdAt": "2026-09-29T09:00:00.000Z",
    "completedAt": "2026-09-29T09:00:04.000Z"
  }
}

A completed check with no risk data. In rare cases the provider completes and bills a check but returns no risk data. The check is COMPLETED and charged, riskScore, riskLevel and isSanctioned are all null, and error explains this. Do not read it as clean — contact support with the check id, or re-screen.

Get a check

GET /api/aml-checks/{checkId}

Returns the check with the full result. A PENDING check is refreshed from the provider when you read it, so poll every few seconds. Most checks settle within seconds; complex address histories can take up to about 3 minutes. A check still pending after an hour is marked FAILED and its fee is returned. An unknown id — or another merchant's check — returns 404.

List checks

GET /api/aml-checks?status=COMPLETED&network=TRX&page=1&limit=20

Query parameters (all optional): page, limit (max 100, default 20), status, network, address, referenceId. Rows omit the result detail. The response also carries service:

{
  "checks": [ { "id": "cmg4x0amz0001", "status": "COMPLETED", "riskLevel": "high", "...": "..." } ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "pages": 3 },
  "service": { "provider": "elliptic", "feePerCheck": "1.5", "supportedNetworks": ["BNB", "POL", "TRX"] }
}

Errors

Good practice

• Screen before crediting or paying out, and store the id with your customer record — results are kept and can be re-read at any time without a new charge.
• Re-screening the same address runs a new check and is charged again; reuse a recent result where your policy allows.
• Set referenceId so a retried request after a timeout returns 409 instead of charging a second check.
• A risk result is an input to your compliance decision, not the decision itself.