> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tender.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Subwallets

> Create and manage crypto wallets for your end-users — deposits, addresses, and transfers, all under your merchant account

<Warning>
  This feature is currently only available in the sandbox environment.
</Warning>

Tender's subwallet offering lets you provision and manage a full wallet infrastructure for each of
your end-users. You create a wallet per user, assign blockchain addresses, watch those addresses
for incoming deposits, and initiate outbound transfers — all via your merchant API credentials,
without your users ever touching Tender directly.

***

## How it works

<Steps>
  <Step title="Create a wallet">
    Provision a wallet tied to a unique reference you supply — typically your own user ID. Tender
    returns the wallet's initial set of blockchain addresses.
  </Step>

  <Step title="Add addresses">
    Create additional addresses on specific networks for an existing wallet. You can group
    addresses under a named reference to represent separate deposit slots or assets.
  </Step>

  <Step title="Watch for deposits">
    Register each address with Tender's deposit monitor. When a deposit arrives, Tender fires a
    `SUB_USER_WALLET_TRANSACTION_DETECTED` webhook to your server with the full transaction
    details.
  </Step>

  <Step title="Initiate transfers">
    Send funds from a subwallet address to any destination. Pass `chain` and `currency` — Tender
    resolves whether to use a native coin or token transfer internally. Tender confirms the
    on-chain transaction and fires a `SUB_USER_WALLET_TRANSFER_CONFIRMED` webhook when it settles.
  </Step>
</Steps>

***

## Prerequisites

<Card title="Authentication guide" icon="lock" href="/api-reference/authentication">
  These endpoints use Signed (HMAC) authentication — an HMAC-SHA256 signature is required on every request. See the authentication guide for code examples.
</Card>

***

## Step 1 — Create a wallet

Call `POST /wallet` with a `reference` that uniquely identifies the end-user within your
merchant account. Tender provisions a wallet and returns its blockchain addresses immediately.
Store the `reference` — you will use it in every subsequent call for that user.

<Card title="Create Wallet" icon="wallet" href="/api-reference/endpoint/subwallets/create-wallet">
  Full parameters and response schema for `POST /wallet`
</Card>

***

## Step 2 — Add addresses to the wallet

Call `POST /wallet/address` with the `wallet_reference`, an `address_reference` label of your
choice, and the list of `networks` you want addresses on. The new addresses are merged into the
wallet alongside any existing ones.

<Card title="Create Address" icon="circle-plus" href="/api-reference/endpoint/subwallets/create-address">
  Full parameters and response schema for `POST /wallet/address`
</Card>

***

## Step 3 — Watch for deposits

Call `POST /wallet/filter` with the address and the chains to monitor. Once registered, Tender
watches that address on-chain and fires a `SUB_USER_WALLET_TRANSACTION_DETECTED` webhook to your
server whenever a deposit is detected.

**Webhook payload fields:**

| Field                   | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `depositKey`            | Unique key for the deposit event (`chain:txHash:index`)                  |
| `transactionId`         | Tender's internal transaction ID                                         |
| `walletReference`       | The wallet this deposit belongs to                                       |
| `addressReference`      | The address slot label                                                   |
| `chainId`               | The network the deposit arrived on                                       |
| `symbol`                | Token symbol (e.g. `ETH`, `USDT`)                                        |
| `address`               | The receiving address                                                    |
| `txHash`                | On-chain transaction hash                                                |
| `amount`                | Amount in the token's smallest unit (e.g. wei for ETH)                   |
| `decimals`              | Decimal places — divide `amount` by `10 ** decimals` for the human value |
| `confirmed`             | `false` on first detection; `true` once fully confirmed                  |
| `confirmations`         | Current confirmation count                                               |
| `confirmationsRequired` | Confirmations needed to consider the deposit settled                     |
| `occurredAt`            | ISO 8601 timestamp of the event                                          |

<Warning>
  Treat a deposit as settled only when `confirmed` is `true` or
  `confirmations >= confirmationsRequired`.
</Warning>

<Card title="Add Deposit Filter" icon="eye" href="/api-reference/endpoint/subwallets/add-filter">
  Full parameters and response schema for `POST /wallet/filter`
</Card>

***

## Step 4 — Initiate a transfer

Call `POST /wallet/transfer` with `chain`, `currency`, `sender`, `receiver`, `amount`, and your
own `merchant_reference`. Tender automatically routes to a native coin or token transfer based on
the currency. The response returns a `tx_id` immediately; the transfer settles asynchronously.

**Supported chains:** `ethereum`, `tron`, `bitcoin`

<Card title="Transfer Funds" icon="arrow-right-arrow-left" href="/api-reference/endpoint/subwallets/transfer">
  Full parameters and response schema for `POST /wallet/transfer`
</Card>

When the transfer confirms on-chain, Tender fires a `SUB_USER_WALLET_TRANSFER_CONFIRMED`
webhook to your server.

***

## Utility operations

| Operation        | Endpoint                                                                                      | What it does                                                              |
| ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| List wallets     | [`GET /wallet`](/api-reference/endpoint/subwallets/list-wallets)                              | Paginated list of all wallets under your merchant account                 |
| List addresses   | [`GET /wallet/:walletReference/addresses`](/api-reference/endpoint/subwallets/list-addresses) | All addresses belonging to a specific wallet                              |
| Get balance      | [`GET /wallet/balance/:address`](/api-reference/endpoint/subwallets/get-balance)              | Native, USDC, and USDT balances for an address on a specific chain        |
| Validate address | [`POST /wallet/validate`](/api-reference/endpoint/subwallets/validate-address)                | Check whether an address is valid on a given set of networks              |
| Check watched    | [`GET /wallet/watch/:address`](/api-reference/endpoint/subwallets/check-watched)              | Check whether an address is currently registered with the deposit monitor |

***

## Webhook events

| Event                                  | Fired when                             |
| -------------------------------------- | -------------------------------------- |
| `SUB_USER_WALLET_TRANSACTION_DETECTED` | A deposit arrives on a watched address |
| `SUB_USER_WALLET_TRANSFER_CONFIRMED`   | An outbound transfer confirms on-chain |

See [Webhooks](/get-started/webhooks) for how to configure your endpoint and verify payloads.