Get your Risk API key
Screen ETH, TRON and BTC wallets from your own systems. Sign up with your email to get an API key and 1 free credit: your first check is free.
Submit, poll, read
1. Submit a wallet
POST /v1/checks with the address. You get a check_id back at once, plus your place in the queue.
2. Poll for the result
GET /v1/checks/{check_id} every few seconds until the status is done or failed.
3. Read the verdict
A done check carries the full result: verdict, risk score, exposure, freeze status and a cross-chain report link.
Checks are asynchronous
A check usually takes 30–120 seconds. Checks run one at a time on the same analysis engine as our WhatsApp service, so when it is busy your check waits in a queue; every response shows your position and an estimated wait. Build your integration to submit, then poll. Don’t hold a connection open waiting for the result.
Your first check in three calls
Send your key in the X-Api-Token header. Base URL: https://api.amlchain.com
1. Submit a wallet
curl -X POST https://api.amlchain.com/v1/checks \
-H "X-Api-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"address": "WALLET_ADDRESS"}'HTTP/1.1 202 Accepted
{
"check_id": "chk_8f14e45fceea167a5a36dedd",
"status": "pending",
"chain": "TRON",
"queue": { "position": 1, "estimated_wait_s": 90 },
"charged": false
}Optional: send an Idempotency-Key header. Retrying with the same key returns the same check instead of creating (and paying for) a new one.
2. Poll until done
curl https://api.amlchain.com/v1/checks/chk_8f14e45fceea167a5a36dedd \ -H "X-Api-Token: YOUR_API_KEY"
{
"check_id": "chk_8f14e45fceea167a5a36dedd",
"status": "done",
"charged": true,
"result": {
"schema": "1.0",
"outcome": "report",
"subject": { "address": "T…", "chain": "TRON" },
"verdict": { "safe": false, "risk_level": "medium", "risk_score": 51,
"frozen": false, "reasons": ["sanctions_exposure"] },
"exposure": { "flagged_pct": 0.86, "sanctions_usd": 6591.33,
"scam_usd": 4.58, "counterparties": ["Exchange", "Dex"] },
"freeze": { "status": "not_frozen" },
"cross_chain_report_url": "https://…"
}
}3. Check your credits
curl https://api.amlchain.com/v1/account -H "X-Api-Token: YOUR_API_KEY"
{
"credits": { "balance": 4, "reserved": 1, "available": 3 },
"keys": [{ "prefix": "amlk_AbC1234", "revoked": false }],
"ledger": [{ "kind": "check_debit", "delta": -1, "check_id": "chk_…" }]
}Result fields
| Field | Meaning |
|---|---|
| status | pending, processing, done or failed. A failed check has result: null and is never charged. |
| result.outcome | report, report_text, report_indirect_only, no_transactions, incomplete or failed. |
| result.verdict.safe | true only when the analysis positively confirms it; false for a risky or frozen wallet; null when the check could not be completed. Never treat null as safe. |
| result.verdict.risk_level | low, medium, high, critical or unknown, with risk_score (0–100) and the reasons behind it. |
| result.verdict.frozen | Whether the wallet is frozen by the stablecoin issuer. |
| result.exposure | flagged_pct (share of flagged funds), counterparty categories and USD exposure to sanctions, scams, stolen funds and blacklisted wallets. |
| result.freeze | Freeze status of the wallet itself, with the token and date when frozen. |
| result.cross_chain | Funds that arrived through bridges, with source chains; cross_chain_report_url links to the full cross-chain report. |
Errors
Every error is JSON with an error code; most also include a message.
| HTTP | error | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, wrong or revoked API key. |
| 402 | out_of_credits | No credits left. Buy more on WhatsApp. |
| 403 | account_disabled | The account is disabled. Message us on WhatsApp. |
| 404 | not_found | Unknown path, or a check that belongs to another account. |
| 409 | idempotency_key_reused | The Idempotency-Key was already used for a different wallet. |
| 413 | request_too_large | Request body too large. |
| 422 | invalid_address / unsupported_chain | Not a valid ETH, TRON or BTC wallet address, or a transaction hash. |
| 429 | rate_limited / too_many_in_flight / queue_full | Slow down; see Retry-After. |
| 503 | service_unavailable | Temporarily unavailable. Retry shortly. |
How credits work
- One credit pays for one completed check. A check that fails is never charged.
- Asking again for the same wallet within 10 minutes returns your earlier check without a second charge.
- Supported: ETH, TRON, BTC wallet addresses. Transaction hashes are not supported yet.
- Limits: 20 submissions and 60 status requests per minute per IP address, and 5 checks in progress per account.
Out of credits?
Buy more credits on WhatsApp. Tell us the email on your account and how many checks you need, and we add them to your balance.