Wallet AML Check API
Public API reference for customer authentication, wallet funding, AML credits, wallet screening, JSON result access, and PDF report downloads.
Wallet AML Check API
This document describes the public AML wallet check API for website and external integrations.
All endpoints in this document are published under the following namespace:
/external/aml-wallet-check/*Base URL
https://back.2aml.com/external/aml-wallet-checkAuthentication
Public authentication endpoints:
POST /auth/registerPOST /auth/loginPOST /auth/login/2faPOST /auth/verify-email/requestPOST /auth/verify-email/confirm
Protected endpoints require the bearer token returned by one of the following successful flows:
POST /auth/registerPOST /auth/loginwhenstatus=authenticatedPOST /auth/login/2fa
POST /auth/login is branch-aware. A successful credential check can return one of the following statuses:
authenticatedtwo_factor_requiredemail_verification_required
Recommended headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer <accessToken>Optional attribution header for register, login, two-factor completion, and wallet-check creation:
x-fingerprint: fp_browser_or_device_identifierIf you send x-fingerprint on POST /auth/login and receive two_factor_required, send the same header again on POST /auth/login/2fa.
General Conventions
- All TRX amounts are returned as decimal strings.
- All timestamps are returned as ISO 8601 strings.
- Authentication responses are controlled by the
statusfield when you callPOST /auth/login. requestIdidentifies one customer screening request in history.checkIdidentifies the canonical completed screening result and is used for JSON and PDF retrieval.idempotencyKeyis recommended for retriable credit purchases and wallet-check creation calls.billingMode=autofirst uses available AML credits and otherwise charges the wallet balance when wallet-balance billing is available.servedFromCache=truemeans the request reused an existing completed screening result and the request itself did not create a new screening charge.
Integration Flow
Recommended integration sequence:
- Call
POST /auth/registerorPOST /auth/login. - If
POST /auth/loginreturnstwo_factor_required, callPOST /auth/login/2fa. - If
POST /auth/loginreturnsemail_verification_required, complete the email verification flow and then sign in again. - Call
GET /auth/profileto load the authenticated account state. - Call
GET /wallet/summary. - If the wallet balance is low, call
GET /wallet/deposit-instructionsand transfer TRX to the returned address. - Optionally call
POST /wallet/topups/reconcileafter the on-chain transfer is confirmed. - Call
GET /credits/catalogandGET /credits/summary. - If you want prepaid screening credits, call
POST /credits/purchases. - Call
POST /checksto run a wallet AML check. - Use
GET /checksto read request history. - Use
GET /checks/:checkIdfor the canonical JSON result. - Use
GET /checks/:checkId/reportorGET /checks/:checkId/report-summaryfor PDF downloads.
Wallet Check Status
| Status | Terminal | Description |
|---|---|---|
processing | No | The request is accepted and processing is not yet finalized. |
completed | Yes | The AML wallet check completed successfully. |
failed | Yes | The AML wallet check could not be completed. |
expired | Yes | The request expired before it could be completed. |
Integration rules:
- stop polling after a terminal status is returned
- use
requestIdfor history correlation andcheckIdfor JSON or PDF retrieval - preserve
checkIdexactly as returned
Billing Modes
Request billing modes:
| Value | Description |
|---|---|
auto | Uses AML credits when available, otherwise uses wallet balance when enabled. |
credit_pack | Requires at least one available AML credit. |
wallet_balance | Charges the per-check TRX fee from the internal wallet balance. |
Response billing modes:
| Value | Description |
|---|---|
free | The request consumed a free screening allowance. |
credit_pack | The request consumed one AML credit. |
wallet_balance | The request charged the internal TRX wallet balance. |
payment_credit | The request consumed a previously confirmed payment credit. |
Endpoint Summary
| Method | Path | Purpose |
|---|---|---|
POST | /auth/register | Register a new customer account, return a bearer token, and send an account verification email |
POST | /auth/login | Authenticate a customer and return the next sign-in step |
POST | /auth/login/2fa | Complete a pending two-factor sign-in challenge |
POST | /auth/verify-email/request | Request a new account verification email |
POST | /auth/verify-email/confirm | Confirm an email verification token |
GET | /auth/profile | Get the authenticated customer profile and security state |
GET | /wallet/summary | Get the authenticated wallet balance and AML credit balance |
GET | /wallet/deposit-instructions | Get the TRX deposit address for wallet top-up |
GET | /wallet/history | List AML-related wallet balance activity |
GET | /wallet/topups | List wallet top-up records |
POST | /wallet/topups/reconcile | Reconcile a confirmed TRX transfer into the wallet |
GET | /credits/catalog | Get the AML credit-pack catalog and available billing modes |
GET | /credits/summary | Get AML credit balances and expiration summary |
GET | /credits/history | List AML credit purchase and consumption history |
POST | /credits/purchases | Purchase an AML credit pack from wallet balance |
POST | /checks | Run an AML wallet check |
GET | /checks | List AML wallet check history |
GET | /checks/:checkId | Get the canonical JSON result for a completed check |
GET | /checks/:checkId/report | Download the full PDF report |
GET | /checks/:checkId/report-summary | Download the summary PDF report |
1. Register
Creates a customer account, starts a session, and sends an account verification email.
Endpoint
POST /auth/registerRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Customer email address. |
password | string | Yes | Password with at least 6 characters. |
referralCode | string | No | Optional inviter referral code. |
Example Response
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 17,
"email": "[email protected]",
"isActive": true,
"role": "user",
"referralCode": "REF123ABC",
"referredByUserId": 12,
"firstName": null,
"lastName": null,
"displayName": null,
"emailVerifiedAt": null,
"pendingEmail": null,
"pendingEmailRequestedAt": null,
"twoFactorEnabled": false,
"twoFactorEnabledAt": null,
"twoFactorPendingSetup": false
},
"emailVerificationRequired": true,
"verificationEmailSent": true,
"message": "Account created. Verify your email address to complete sign-in on future sessions."
}2. Login
Authenticates an existing customer and returns the next sign-in step.
Endpoint
POST /auth/loginRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Customer email address. |
password | string | Yes | Customer password. |
Example Response: authenticated
{
"status": "authenticated",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 17,
"email": "[email protected]",
"isActive": true,
"role": "user",
"referralCode": "REF123ABC",
"referredByUserId": null,
"firstName": null,
"lastName": null,
"displayName": null,
"emailVerifiedAt": "2026-05-03T10:20:00.000Z",
"pendingEmail": null,
"pendingEmailRequestedAt": null,
"twoFactorEnabled": false,
"twoFactorEnabledAt": null,
"twoFactorPendingSetup": false
},
"message": "Authenticated successfully."
}Example Response: two_factor_required
{
"status": "two_factor_required",
"loginChallengeToken": "c4c3d0a2f97b...",
"loginChallengeExpiresAt": "2026-05-03T10:40:00.000Z",
"message": "Two-factor authentication code is required to complete sign-in."
}Example Response: email_verification_required
{
"status": "email_verification_required",
"verificationEmailSent": true,
"message": "Email verification is required before sign-in can complete."
}Always evaluate the status field before attempting to use the response as an authenticated session.
3. Complete Two-Factor Login
Completes a pending two-factor sign-in challenge and returns a bearer token.
Endpoint
POST /auth/login/2faRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
challengeToken | string | Yes | Challenge token returned by POST /auth/login. |
code | string | Yes | Current authenticator app code or one-time recovery code. |
Example Response
{
"status": "authenticated",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 17,
"email": "[email protected]",
"isActive": true,
"role": "user",
"referralCode": "REF123ABC",
"referredByUserId": null,
"firstName": null,
"lastName": null,
"displayName": null,
"emailVerifiedAt": "2026-05-03T10:20:00.000Z",
"pendingEmail": null,
"pendingEmailRequestedAt": null,
"twoFactorEnabled": true,
"twoFactorEnabledAt": "2026-05-01T08:00:00.000Z",
"twoFactorPendingSetup": false
},
"message": "Authenticated successfully."
}4. Request Email Verification
Requests a new email verification message for an account that still needs verification.
Endpoint
POST /auth/verify-email/requestRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Account email address. |
Example Response
{
"success": true,
"message": "If an active account exists and still needs verification, a verification message has been sent."
}5. Confirm Email Verification
Confirms an email verification token.
Endpoint
POST /auth/verify-email/confirmRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Verification token received by email. |
Example Response
{
"success": true,
"message": "Email address has been verified successfully.",
"purpose": "verify_email",
"email": "[email protected]",
"sessionsRevoked": false
}If sessionsRevoked is true, sign in again before making further authenticated requests.
6. Profile
Returns the authenticated customer profile and the current email-verification and two-factor state.
Endpoint
GET /auth/profileExample Response
{
"id": 17,
"email": "[email protected]",
"isActive": true,
"role": "user",
"referralCode": "REF123ABC",
"referredByUserId": null,
"firstName": null,
"lastName": null,
"displayName": null,
"emailVerifiedAt": "2026-05-03T10:20:00.000Z",
"pendingEmail": null,
"pendingEmailRequestedAt": null,
"twoFactorEnabled": true,
"twoFactorEnabledAt": "2026-05-01T08:00:00.000Z",
"twoFactorPendingSetup": false
}7. Wallet Summary
Returns the authenticated wallet balance used for AML billing and the current AML credit balance.
Endpoint
GET /wallet/summaryExample Response
{
"availableBalanceTrx": "40.000000",
"reservedBalanceTrx": "0.000000",
"amlCreditsBalance": 4,
"status": "active",
"currency": "TRX"
}8. Deposit Instructions
Returns the TRX deposit route for topping up the authenticated wallet.
Endpoint
GET /wallet/deposit-instructionsExample Response
{
"network": "tron",
"depositAddress": "TNYmcW4cAyczQzj5QXHBa4FwxMPRw4DgiD",
"depositMemo": null,
"memoRequired": false,
"depositRouteStatus": "active",
"minDepositTrx": "1.000000",
"minConfirmations": 1,
"confirmationPolicy": "Credit after 1 on-chain confirmation(s)."
}9. Wallet History
Returns wallet balance activity relevant to top-ups, AML credit-pack purchases, AML wallet-balance charges, and AML refunds.
Endpoint
GET /wallet/history?page=1&limit=20Example Response
{
"data": [
{
"id": 145,
"type": "topup",
"direction": "credit",
"status": "completed",
"amountTrx": "25.00000000",
"availableBalanceTrx": "40.00000000",
"reservedBalanceTrx": "0.00000000",
"txHash": "6c1a7b4bfe2d7d84b4eb58a9f1e0f5bb0a5f1f9a9d406b6fd4c0f5e9f4f6a001",
"planCode": null,
"checkRequestId": null,
"description": "Top-up credited to the wallet.",
"createdAt": "2026-04-15T12:03:00.000Z"
},
{
"id": 146,
"type": "aml_check_charge",
"direction": "debit",
"status": "completed",
"amountTrx": "8.00000000",
"availableBalanceTrx": "32.00000000",
"reservedBalanceTrx": "0.00000000",
"txHash": null,
"planCode": null,
"checkRequestId": 73,
"description": "AML wallet check charged to the wallet balance.",
"createdAt": "2026-04-15T12:04:00.000Z"
}
],
"total": 2,
"page": 1,
"limit": 20
}10. List Wallet Top-Ups
Returns paginated top-up history sorted from newest to oldest.
Endpoint
GET /wallet/topups?page=1&limit=20Example Response
{
"data": [
{
"topupId": 92,
"txHash": "6c1a7b4bfe2d7d84b4eb58a9f1e0f5bb0a5f1f9a9d406b6fd4c0f5e9f4f6a001",
"amountTrx": "25.00000000",
"status": "credited",
"senderAddress": "TT3m4Kx8s4bqWfQ2TzN9G17wF3yYhE3o6S",
"createdAt": "2026-04-15T12:00:00.000Z",
"creditedAt": "2026-04-15T12:03:00.000Z"
}
],
"total": 1,
"page": 1,
"limit": 20
}11. Reconcile a Top-Up
Attempts to reconcile a confirmed TRX transfer into the authenticated wallet balance.
Endpoint
POST /wallet/topups/reconcileRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
txHash | string | Yes | Confirmed TRON transfer transaction hash. |
Example Response
{
"topup": {
"topupId": 92,
"txHash": "6c1a7b4bfe2d7d84b4eb58a9f1e0f5bb0a5f1f9a9d406b6fd4c0f5e9f4f6a001",
"amountTrx": "25.00000000",
"status": "credited",
"senderAddress": "TT3m4Kx8s4bqWfQ2TzN9G17wF3yYhE3o6S",
"createdAt": "2026-04-15T12:00:00.000Z",
"creditedAt": "2026-04-15T12:03:00.000Z"
},
"wallet": {
"availableBalanceTrx": "40.000000",
"reservedBalanceTrx": "0.000000",
"amlCreditsBalance": 4,
"status": "active",
"currency": "TRX"
}
}12. Credit Catalog
Returns the AML credit-pack catalog, the wallet-balance per-check fee, and the currently available billing modes.
Endpoint
GET /credits/catalogExample Response
{
"feePerCheckTrx": "8.000000",
"walletBalanceBillingEnabled": true,
"creditPackBillingEnabled": true,
"planCatalog": [
{
"code": "pack_10",
"credits": 10,
"priceTrx": "80.000000",
"pricePerCreditTrx": "8.000000",
"expirationPolicy": {
"mode": "fixed_days",
"expiresInDays": 30
},
"active": true,
"pricingPreview": {
"listPriceTrx": "80.000000",
"finalPriceTrx": "72.000000",
"discountRatePercent": 10,
"discountAmountTrx": "8.000000",
"referralDiscountApplied": true
}
}
]
}13. Credit Summary
Returns current AML credit balances and expiration summary for the authenticated customer.
Endpoint
GET /credits/summaryExample Response
{
"amlCreditsBalance": 12,
"amlCreditsPurchased": 20,
"amlCreditsConsumed": 8,
"amlCreditsExpired": 0,
"amlCreditsBonus": 1,
"walletAvailableBalanceTrx": "32.000000",
"walletReservedBalanceTrx": "0.000000",
"expirationPolicy": {
"mode": "fixed_days",
"expiresInDays": 30
}
}14. Credit History
Returns AML credit purchase and consumption history.
Endpoint
GET /credits/history?page=1&limit=20&type=purchaseQuery Parameters
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number. Default: 1. |
limit | number | No | Page size. Default: 20. |
type | string | No | One of purchase, consumption, restore, bonus, expiry. |
Example Response
{
"data": [
{
"id": 301,
"type": "purchase",
"credits": 10,
"planCode": "pack_10",
"amountTrx": "80.00000000",
"checkRequestId": null,
"description": "AML credits were purchased and added to the account.",
"createdAt": "2026-04-15T12:01:00.000Z"
},
{
"id": 302,
"type": "consumption",
"credits": 1,
"planCode": "pack_10",
"amountTrx": "0.00000000",
"checkRequestId": 73,
"description": "AML credits were consumed by a wallet check.",
"createdAt": "2026-04-15T12:04:00.000Z"
}
],
"total": 2,
"page": 1,
"limit": 20
}15. Purchase Credits
Purchases an AML credit pack using the authenticated wallet balance.
Endpoint
POST /credits/purchasesRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
planCode | string | Yes | One of pack_1, pack_10, pack_50, pack_100. |
idempotencyKey | string | No | Recommended for retriable purchase calls. |
Example Response
{
"plan": {
"code": "pack_10",
"credits": 10,
"priceTrx": "80.000000",
"pricePerCreditTrx": "8.000000",
"expirationPolicy": {
"mode": "fixed_days",
"expiresInDays": 30
},
"active": true
},
"pricing": {
"listPriceTrx": "80.000000",
"finalPriceTrx": "72.000000",
"discountRatePercent": 10,
"discountAmountTrx": "8.000000",
"referralDiscountApplied": true
},
"purchasedCredits": 10,
"expiresAt": "2026-05-15T12:01:00.000Z",
"amlCreditsBalance": 14,
"walletAvailableBalanceTrx": "32.000000",
"walletReservedBalanceTrx": "0.000000",
"idempotencyStatus": "completed"
}16. Run a Wallet AML Check
Runs a wallet AML check for the authenticated customer and returns the terminal screening result.
Endpoint
POST /checksRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
targetWallet | string | Yes | Wallet address to screen. |
targetNetwork | string | Yes | Target blockchain network key, for example tron, ethereum, or bsc. |
requesterWallet | string | No | Optional requester wallet identifier. If omitted, targetWallet is used. |
billingMode | string | No | One of auto, credit_pack, wallet_balance. |
reportLanguage | string | No | One of en, fa, ru, zh, ur, tr, ar, ps. |
fingerprint | string | No | Optional client fingerprint for request attribution. |
idempotencyKey | string | No | Recommended for retriable screening calls. |
Example Request
curl --request POST \
--url 'https://back.2aml.com/external/aml-wallet-check/checks' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
"targetWallet": "TGzz8gjYiYRqpfmDwnLxfgPuLVNmpCswVp",
"targetNetwork": "tron",
"billingMode": "auto",
"reportLanguage": "en",
"idempotencyKey": "aml-check-0001"
}'Example Response
{
"checkId": 17,
"targetWallet": "TGzz8gjYiYRqpfmDwnLxfgPuLVNmpCswVp",
"targetNetwork": "tron",
"status": "completed",
"amlScore": 72,
"riskLevel": "high",
"isFlagged": true,
"checkedAt": "2026-04-15T12:04:00.000Z",
"billingMode": "credit_pack",
"servedFromCache": false,
"consumedCreditCount": 1,
"chargedAmountTrx": null,
"remainingAmlCredits": 13,
"walletAvailableBalanceTrx": "32.000000",
"downloads": {
"jsonUrl": "/external/aml-wallet-check/checks/17",
"reportUrl": "/external/aml-wallet-check/checks/17/report",
"summaryReportUrl": "/external/aml-wallet-check/checks/17/report-summary",
"reportLanguage": "en"
}
}17. List Wallet Check History
Returns paginated wallet-check request history for the authenticated customer.
Endpoint
GET /checks?page=1&limit=20Example Response
{
"data": [
{
"requestId": 73,
"checkId": 17,
"targetWallet": "TGzz8gjYiYRqpfmDwnLxfgPuLVNmpCswVp",
"targetNetwork": "tron",
"status": "completed",
"billingMode": "credit_pack",
"servedFromCache": false,
"amlScore": 72,
"riskLevel": "high",
"isFlagged": true,
"createdAt": "2026-04-15T12:04:00.000Z",
"completedAt": "2026-04-15T12:04:00.000Z",
"downloadsReady": true,
"downloads": {
"jsonUrl": "/external/aml-wallet-check/checks/17",
"reportUrl": "/external/aml-wallet-check/checks/17/report",
"summaryReportUrl": "/external/aml-wallet-check/checks/17/report-summary",
"reportLanguage": "en"
}
}
],
"total": 1,
"page": 1,
"limit": 20
}18. Get JSON Wallet Check Result
Returns the canonical JSON result for a completed wallet check owned by the authenticated customer.
Endpoint
GET /checks/:checkIdExample Response
{
"checkId": 17,
"requestId": 73,
"targetWallet": "TGzz8gjYiYRqpfmDwnLxfgPuLVNmpCswVp",
"targetNetwork": "tron",
"status": "completed",
"billingMode": "credit_pack",
"servedFromCache": false,
"amlScore": 72,
"riskLevel": "high",
"isFlagged": true,
"requestedAt": "2026-04-15T12:04:00.000Z",
"completedAt": "2026-04-15T12:04:00.000Z",
"checkedAt": "2026-04-15T12:04:00.000Z",
"consumedCreditCount": 1,
"chargedAmountTrx": null,
"downloads": {
"jsonUrl": "/external/aml-wallet-check/checks/17",
"reportUrl": "/external/aml-wallet-check/checks/17/report",
"summaryReportUrl": "/external/aml-wallet-check/checks/17/report-summary",
"reportLanguage": "en"
},
"signals": {
"lastActivity": "2026-04-10T09:00:00.000Z",
"balance": "1520.000000",
"transactions": 48,
"uniqueInteractors": 23,
"tags": [
"aml-flagged"
]
}
}19. Download the Full PDF Report
Downloads the full PDF report for a completed wallet check.
Endpoint
GET /checks/:checkId/reportExample Request
curl --request GET \
--url 'https://back.2aml.com/external/aml-wallet-check/checks/17/report' \
--header 'Authorization: Bearer <accessToken>' \
--output aml-report-17.pdf20. Download the Summary PDF Report
Downloads the summary PDF report for a completed wallet check.
Endpoint
GET /checks/:checkId/report-summaryExample Request
curl --request GET \
--url 'https://back.2aml.com/external/aml-wallet-check/checks/17/report-summary' \
--header 'Authorization: Bearer <accessToken>' \
--output aml-report-summary-17.pdfError Envelope
All non-file responses use the same error envelope.
Example Error Response
{
"statusCode": 400,
"timestamp": "2026-04-15T12:05:00.000Z",
"path": "/external/aml-wallet-check/checks",
"error": {
"message": "AML wallet check request is invalid."
}
}Common errors:
400 Bad Requestfor invalid request payloads, parameters, two-factor login challenges, or email verification tokens401 Unauthorizedwhen the bearer token is missing or invalid, or when login credentials are rejected403 Forbiddenwhen the requested billing mode is currently unavailable404 Not Foundwhen the requested wallet check does not exist for the authenticated customer409 Conflictwhen the same idempotency key is already in progress429 Too Many Requestswhen the rate limit is exceeded503 Service Unavailablewhen the service is temporarily unavailable

