> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-embedded-wallet-service/wallet-management-apis.md).

# Wallet Management APIs

The Wallet Management APIs allow merchants to retrieve an end user’s wallet balances, asset holdings, supported tokens, supported networks, wallet addresses, transaction history, reports, and Travel Rule counterparty information.

These APIs are read-only and must be called from the merchant’s secure backend.

### Available APIs

| Category     | Method | Endpoint                                            | Purpose                                       |
| ------------ | ------ | --------------------------------------------------- | --------------------------------------------- |
| Wallet       | `GET`  | `/whitelabel/wallet/getHoldings`                    | Retrieve the user’s asset holdings            |
| Wallet       | `GET`  | `/whitelabel/wallet/getBalance`                     | Retrieve the balance of a specific asset      |
| Wallet       | `GET`  | `/whitelabel/wallet/getTokenList`                   | Retrieve supported tokens                     |
| Wallet       | `GET`  | `/whitelabel/wallet/getNetworksList`                | Retrieve supported blockchain networks        |
| Wallet       | `GET`  | `/whitelabel/wallet/getWalletAddress`               | Retrieve a deposit wallet address             |
| Transactions | `GET`  | `/whitelabel/transactions/getHistory`               | Retrieve transaction history                  |
| Transactions | `GET`  | `/whitelabel/transactions/getDetails`               | Retrieve a specific transaction               |
| Transactions | `GET`  | `/whitelabel/transactions/getReport`                | Generate a transaction report                 |
| Transactions | `GET`  | `/whitelabel/transactions/getLedgerReport`          | Generate a wallet-ledger report               |
| Transactions | `GET`  | `/whitelabel/transactions/validate`                 | Validate a transaction                        |
| Compliance   | `GET`  | `/whitelabel/compliance/travelRule/getCounterparty` | Retrieve Travel Rule counterparty information |

***

## Authentication

Every request must include:

```http
x-tlp-apikey: <api-key>
x-tlp-signature: <hmac-signature>
```

For `GET` requests, the HMAC signature is calculated over the complete query object:

```
HMAC_SHA256(apiSecret, JSON.stringify(query))
```

The query parameters must be sent exactly as they were signed, including the same:

* Field names
* Field order
* Values
* Data types

All requests are also subject to the merchant’s configured IP whitelist.

***

## End-User Identification

Every user-level request must identify the end user using one of:

| Field            | Type   | Description                         |
| ---------------- | ------ | ----------------------------------- |
| `endUserEmail`   | String | End user’s registered email address |
| `endUserId`      | Number | Tylt end-user ID                    |
| `externalUserId` | String | Merchant’s own user identifier      |

Only one identifier is required.

The recommended identifier is:

```
externalUserId
```

Example query object:

```json
{
  "externalUserId": "user-10021"
}
```

A client-supplied `merchantId` is ignored or removed by Tylt to prevent cross-merchant access.

***

## Common Access Requirements

The Wallet Management APIs require:

* A valid API key
* A valid HMAC signature
* A whitelisted source IP address
* A valid end user belonging to the authenticated merchant
* An active and unsuspended end-user account
* Approved KYC
* Wallet operations to be enabled for the user

These endpoints do not require:

* Replay-protection timestamps
* Nonces
* Email OTPs
* Authenticator codes

Those controls apply only to mutating wallet operations.

***