Client Wallet Balances & Transactions

1. Overview

Customer Wallet Balances & Transactions is an API for obtaining a complete financial picture of a merchant's customer. The API returns a single JSON object containing information about all customer wallets (including old and blocked ones), their current balances, USD equivalents, and transaction history with AML data.

Key Features:

• Retrieve balances of all customer wallets (across all currencies and networks)
• Current balance + USD equivalent at the current exchange rate
• Transaction history with filtering by period
• Historical USD amounts at the time of each transaction
• AML score and status for each transaction
• Pagination support for large data volumes
• Inclusion of blocked and old wallets

2. Business Context

Why This Feature Is Needed

Problem:

Merchants and their customers need a centralized way to obtain complete financial history for a customer:

• A customer may have multiple wallets (different currencies, networks)
• Old wallets after AML blocking remain in the system
• Transactions are scattered across different wallets
• There is no single place to view all balances and history

Solution:

A single API endpoint that aggregates:

• All customer wallets (OPEN, LOCKED, BLOCKED)
• Current balances in native currency + USD
• Transaction history with AML data
• Ability to filter by period for reporting

Use Cases

1. Financial report for customer — show the customer all their balances and transactions
2. Audit and compliance — merchant can review customer's transaction history
3. Customer support — quickly find customer information to resolve issues
4. Analytics — data aggregation for merchant's internal reports

3. API Endpoints

GET /api/v2/merchants/wallets/info?clientId=&dateFrom=dateTo=

4. API Specification

Request

HTTP Method: GET

Endpoint:

/api/v2/merchants/wallets/info?clientId=<clientId>&dateFrom=<dateFrom>&dateTo=<dateTo>

Query Parameters

Query Parameter Details

dateFrom / dateTo:

• Format: Unix timestamp
• Optional: if not specified — all transactions are returned
• If dateFrom is specified but dateTo is missing → ignore
• If dateTo is specified but dateFrom is missing → ignore
• Period affects only the transaction list, not balances

page:

• Used for pagination

pageSize:

• Used for page size

limit:

• Number of transactions per request
• Default: 100
• Max: 1000
• Pagination triggers when transactions exceed limit

sort:

• desc (default) — from newest to oldest (by createdAt)
• asc — from oldest to newest

blocked (locked wallets are also included in response by default):

• true (default) — includes blocked wallets (after AML_CHECK_DANGER)
• false — only active wallets

zeroBalance:

• true (default) — includes wallets with balance = 0
• false — only wallets with balance > 0

Response

HTTP Status: 200 OK

Response Body:

{
  "clientId": "client-12345",
  "createdAt": "2025-12-22T10:30:45Z",
  "wallets": [
    {
      "address": "TXyz123ABCdefGHIjklMNOpqrSTUvwx",
      "assetShort": "USDT",
      "assetNetwork": "tron",
      "status": "ACTIVE",
      "isBlocked": false,
      "balance": {
        "amount": "1000.50",
        "amountUsd": "1000.50",
        "updatedAt": "2025-12-22T10:30:00Z"
      },
      "payments": [
        {
          "id": "d4c87981-92c2-403e-b91b-a4f02a323a48",
          "totalReceivedAmount": "500.00",
          "totalReceivedAmountUsd": "500.00",
          "confirmsNeeded": 30,
          "checkoutUrl": "",
          "status": "EXPIRED",
          "displayStatus": "COMPLETED",
          "customerId": 0,
          "customerName": "Unknown",
          "customerEmail": "unknown",
          "invoice": "INVOICEid",
          "createdAt": "2025-09-01T15:02:20.382627+03:00",
          "type": "api",
          "fixedFee": "0",
          "fixedFeeUsd": "0",
          "transactions": [
            {
              "txnId": "0x1234abcd...",
              "amount": "500.00",
              "createdAt": "2025-12-15T14:25:30Z",
              "aml": {
                "riskScore": 15,
                "isDanger": false,
                "checkedAt": "2025-12-15T14:26:00Z",
                "amlPriceUsd": "0.50"
              },
              "fees": {
                "networkFee": {
                  "amount": "0.5",
                  "amountUsd": "0.15"
                },
                "percentFee": {
                  "amount": "0.5",
                  "amountUsd": "0.15"
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "hasNext": true,
    "hasPrev": false,
    "total": 156
  }
}

5. Response Fields Specification

Top-Level Fields

Wallet Object

Balance Object

Payment Object

Transaction Object

AML Object

Fees Object

Fee Object

Pagination Object