Risk Score API

Fetches wallet risk data from the Alpha AML upstream API, renders it into a styled HTML report, and converts it to PDF via headless Chromium (Playwright).

Base URL

https://api-v3.alpha-aml.com

GET /api-v2/report-v1

Returns a PDF AML risk report for the given wallet address and chain.

GET /api-v2/report-v1?address={address}&chain={chain}

Query Parameters

Parameter	Type	Description
addressrequired	string	Wallet address to check. Blank or missing → `400`.
chainoptional	string	Blockchain the address belongs to. If omitted, upstream API attempts auto-detection.

Supported chain values:

ETH ARB BASE BSC TRON

Response

Status	Content-Type	Body
200	`application/pdf`	Generated PDF bytes. Header: `Content-Disposition: attachment; filename="aml-report-<address>.pdf"`.
400	—	Empty body. `address` is missing or blank.
404	`text/plain`	`Address not exist: <address>`
500	`text/plain`	`Some error occurred while generating PDF. Contact to: support@alphaaml.com`

curl Examples

curl "https://api-v3.alpha-aml.com/api-v2/report-v1?address=0x7f367cc41522ce07553e823bf3be79a889debe1b&chain=ETH" \
  -o aml-report.pdf

COPY

curl "https://api-v3.alpha-aml.com/api-v2/report-v1?address=TXyz1234567890abcdefgh&chain=TRON" \
  -o aml-report.pdf

COPY

GET /api/report-v1

Called internally via DataApiService (Retrofit). Not exposed to external clients — our service proxies and converts the JSON to PDF.

GET https://api-v2.alpha-aml.com/api/report-v1?address={address}&chain={chain}&apiKey={key}

Query Parameters

Parameter	Type	Description
addressrequired	string	Forwarded from our endpoint.
chainoptional	string	Forwarded from our endpoint.
apiKeyrequired	string	Long-lived API key injected server-side. Never supplied by callers of our endpoint.

Response Fields (200 OK JSON)

JSON body consumed by AMLReportGenerator

report.generated_at_utcstringTimestamp the upstream report was generated (shown in PDF header).

wallet.address / .blockchain / .description / .entity_tagstringAddress, chain, entity description, and tag shown in the report header.

risk_assessment.score / .score_maxnumberNumeric risk score and its scale (e.g. 85 / 100).

risk_assessment.risk_levelstringTier label: VERY LOW RISK / LOW RISK / HIGH RISK / VERY HIGH RISK.

risk_assessment.blacklisted / .blacklist_noteboolean / stringBlacklist flag and human-readable note.

risk_assessment.score_zones[]array{ label, range_min, range_max } — drives the gauge legend zones.

token_balances[]arrayToken balance table (ERC-20 / TRC-20).

wallet_statistics.*objectTx counts, first/last tx timestamps, wallet_age_days, status, stablecoin inflow/outflow/turnover.

funded_by_entity_type_distribution[]array{ label, percentage } — entity-type funding breakdown.

risk_factors.blacklists.statusstringblacklisted → LISTED, reported → FLAGGED, else CLEAR.

risk_factors.reported_connected_addresses[]arrayConnected addresses with hop counts and blacklist status.

Error Reference

Status	Trigger	Body
400	`address` param missing or blank	(empty)
404	Upstream call failed (non-2xx) or returned empty body	`text/plain`: Address not exist: <address>
500	Upstream data OK but Playwright/Chromium failed to render PDF	`text/plain`: Some error occurred while generating PDF. Contact to: support@alphaaml.com

Example Upstream Response

{
  "report": { "generated_at_utc": "2026-05-25T18:13:44Z" },
  "wallet": {
    "address": "0x7f367cc41522ce07553e823bf3be79a889debe1b",
    "blockchain": "ETHEREUM",
    "description": "Wu Huihui (DPRK OTC - ETH)",
    "entity_tag": "Mixer addresses"
  },
  "risk_assessment": {
    "score": 85,
    "score_max": 100,
    "risk_level": "VERY HIGH RISK",
    "blacklisted": true,
    "blacklist_note": "Direct blacklist match found"
  },
  "wallet_statistics": {
    "total_transactions_count": 8,
    "wallet_age_days": 1858,
    "status": "INACTIVE"
  }
}

Risk Grade API

Fast, API-key authenticated risk grade for any on-chain wallet address. Returns a single grade value indicating the address's risk tier.

Note: The time field in responses is a Unix timestamp (seconds) indicating when the risk grade was last computed for the given address.

Base URL

https://api.alpha-aml.com

GET /api/risk-grade

Returns the current risk grade for a wallet address.

GET /api/risk-grade?address={address}&apiKey={key}

Query Parameters

Parameter	Type	Description
addressrequired	string	Wallet address to grade. Must be a valid on-chain address. Missing → `{"error":"Address is required"}`.
apiKeyrequired	string	API key for authentication. Missing or invalid → `{"error":"Unauthorized"}`.

curl Example

curl "https://api.alpha-aml.com/api/risk-grade?address=0xd7632A8A3dC9287Ea25d2903df0cFb8702C49572&apiKey=<key>"

COPY

Success Response (200)

{ address, riskGrade, status, time }

addressstringThe queried wallet address (echo).

riskGradestringRisk tier. One of: very-low, low, high, very-high.

statusstring"success" on a valid result.

timeintegerUnix timestamp (seconds) indicating when this risk grade was last computed for the address.

{
  "address": "0xd7632A8A3dC9287Ea25d2903df0cFb8702C49572",
  "riskGrade": "very-low",
  "status": "success",
  "time": 1751500800
}

Grade Values

The riskGrade field carries one of four tiers:

very-low

low

high

very-high

Grade	Interpretation
`very-low`	Address has very low risk exposure — minimal suspicious activity detected.
`low`	Address has low risk — some indirect exposure but generally clean.
`high`	Address has high risk — notable exposure to flagged counterparties or patterns.
`very-high`	Address has very high risk — direct blacklist match or severe exposure.

Error Reference

All errors return a JSON body with an error field.

Error body	Trigger	HTTP Status
`{"error":"Unauthorized"}`	Missing, invalid, or expired `apiKey`	401
`{"error":"Address is required"}`	`address` parameter is missing or empty	400
`{"error":"Unsupported address format"}`	`address` provided but not a valid on-chain address format	400
`{"error":"Rate limit exceeded"}`	API key quota exhausted	429

Error Response Examples

// Unauthorized
{ "error": "Unauthorized" }

// Missing address
{ "error": "Address is required" }

// Bad format
{ "error": "Unsupported address format" }

// Rate limited
{ "error": "Rate limit exceeded" }

COPY