Docs

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-check

Authentication

Public authentication endpoints:

  • POST /auth/register
  • POST /auth/login
  • POST /auth/login/2fa
  • POST /auth/verify-email/request
  • POST /auth/verify-email/confirm

Protected endpoints require the bearer token returned by one of the following successful flows:

  • POST /auth/register
  • POST /auth/login when status=authenticated
  • POST /auth/login/2fa

POST /auth/login is branch-aware. A successful credential check can return one of the following statuses:

  • authenticated
  • two_factor_required
  • email_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_identifier

If 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 status field when you call POST /auth/login.
  • requestId identifies one customer screening request in history.
  • checkId identifies the canonical completed screening result and is used for JSON and PDF retrieval.
  • idempotencyKey is recommended for retriable credit purchases and wallet-check creation calls.
  • billingMode=auto first uses available AML credits and otherwise charges the wallet balance when wallet-balance billing is available.
  • servedFromCache=true means the request reused an existing completed screening result and the request itself did not create a new screening charge.

Integration Flow

Recommended integration sequence:

  1. Call POST /auth/register or POST /auth/login.
  2. If POST /auth/login returns two_factor_required, call POST /auth/login/2fa.
  3. If POST /auth/login returns email_verification_required, complete the email verification flow and then sign in again.
  4. Call GET /auth/profile to load the authenticated account state.
  5. Call GET /wallet/summary.
  6. If the wallet balance is low, call GET /wallet/deposit-instructions and transfer TRX to the returned address.
  7. Optionally call POST /wallet/topups/reconcile after the on-chain transfer is confirmed.
  8. Call GET /credits/catalog and GET /credits/summary.
  9. If you want prepaid screening credits, call POST /credits/purchases.
  10. Call POST /checks to run a wallet AML check.
  11. Use GET /checks to read request history.
  12. Use GET /checks/:checkId for the canonical JSON result.
  13. Use GET /checks/:checkId/report or GET /checks/:checkId/report-summary for PDF downloads.

Wallet Check Status

StatusTerminalDescription
processingNoThe request is accepted and processing is not yet finalized.
completedYesThe AML wallet check completed successfully.
failedYesThe AML wallet check could not be completed.
expiredYesThe request expired before it could be completed.

Integration rules:

  • stop polling after a terminal status is returned
  • use requestId for history correlation and checkId for JSON or PDF retrieval
  • preserve checkId exactly as returned

Billing Modes

Request billing modes:

ValueDescription
autoUses AML credits when available, otherwise uses wallet balance when enabled.
credit_packRequires at least one available AML credit.
wallet_balanceCharges the per-check TRX fee from the internal wallet balance.

Response billing modes:

ValueDescription
freeThe request consumed a free screening allowance.
credit_packThe request consumed one AML credit.
wallet_balanceThe request charged the internal TRX wallet balance.
payment_creditThe request consumed a previously confirmed payment credit.

Endpoint Summary

MethodPathPurpose
POST/auth/registerRegister a new customer account, return a bearer token, and send an account verification email
POST/auth/loginAuthenticate a customer and return the next sign-in step
POST/auth/login/2faComplete a pending two-factor sign-in challenge
POST/auth/verify-email/requestRequest a new account verification email
POST/auth/verify-email/confirmConfirm an email verification token
GET/auth/profileGet the authenticated customer profile and security state
GET/wallet/summaryGet the authenticated wallet balance and AML credit balance
GET/wallet/deposit-instructionsGet the TRX deposit address for wallet top-up
GET/wallet/historyList AML-related wallet balance activity
GET/wallet/topupsList wallet top-up records
POST/wallet/topups/reconcileReconcile a confirmed TRX transfer into the wallet
GET/credits/catalogGet the AML credit-pack catalog and available billing modes
GET/credits/summaryGet AML credit balances and expiration summary
GET/credits/historyList AML credit purchase and consumption history
POST/credits/purchasesPurchase an AML credit pack from wallet balance
POST/checksRun an AML wallet check
GET/checksList AML wallet check history
GET/checks/:checkIdGet the canonical JSON result for a completed check
GET/checks/:checkId/reportDownload the full PDF report
GET/checks/:checkId/report-summaryDownload the summary PDF report

1. Register

Creates a customer account, starts a session, and sends an account verification email.

Endpoint

POST /auth/register

Request Body

FieldTypeRequiredDescription
emailstringYesCustomer email address.
passwordstringYesPassword with at least 6 characters.
referralCodestringNoOptional 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/login

Request Body

FieldTypeRequiredDescription
emailstringYesCustomer email address.
passwordstringYesCustomer 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/2fa

Request Body

FieldTypeRequiredDescription
challengeTokenstringYesChallenge token returned by POST /auth/login.
codestringYesCurrent 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/request

Request Body

FieldTypeRequiredDescription
emailstringYesAccount 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/confirm

Request Body

FieldTypeRequiredDescription
tokenstringYesVerification 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/profile

Example 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/summary

Example 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-instructions

Example 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=20

Example 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=20

Example 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/reconcile

Request Body

FieldTypeRequiredDescription
txHashstringYesConfirmed 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/catalog

Example 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/summary

Example 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=purchase

Query Parameters

FieldTypeRequiredDescription
pagenumberNoPage number. Default: 1.
limitnumberNoPage size. Default: 20.
typestringNoOne 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/purchases

Request Body

FieldTypeRequiredDescription
planCodestringYesOne of pack_1, pack_10, pack_50, pack_100.
idempotencyKeystringNoRecommended 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 /checks

Request Body

FieldTypeRequiredDescription
targetWalletstringYesWallet address to screen.
targetNetworkstringYesTarget blockchain network key, for example tron, ethereum, or bsc.
requesterWalletstringNoOptional requester wallet identifier. If omitted, targetWallet is used.
billingModestringNoOne of auto, credit_pack, wallet_balance.
reportLanguagestringNoOne of en, fa, ru, zh, ur, tr, ar, ps.
fingerprintstringNoOptional client fingerprint for request attribution.
idempotencyKeystringNoRecommended 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=20

Example 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/:checkId

Example 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/report

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/aml-wallet-check/checks/17/report' \
  --header 'Authorization: Bearer <accessToken>' \
  --output aml-report-17.pdf

20. Download the Summary PDF Report

Downloads the summary PDF report for a completed wallet check.

Endpoint

GET /checks/:checkId/report-summary

Example 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.pdf

Error 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 Request for invalid request payloads, parameters, two-factor login challenges, or email verification tokens
  • 401 Unauthorized when the bearer token is missing or invalid, or when login credentials are rejected
  • 403 Forbidden when the requested billing mode is currently unavailable
  • 404 Not Found when the requested wallet check does not exist for the authenticated customer
  • 409 Conflict when the same idempotency key is already in progress
  • 429 Too Many Requests when the rate limit is exceeded
  • 503 Service Unavailable when the service is temporarily unavailable
2AML2AML

2AML is a technology and integration platform for digital asset workflows, built to provide clear service flows, transaction visibility, and support tools.

© 2026 2AML. All rights reserved. Use of this platform is subject to our Terms of Service.

Trustpilot