Subwallets

This feature is currently only available in the sandbox environment.

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

Create a wallet

Provision a wallet tied to a unique reference you supply — typically your own user ID. Tender returns one address per supported network.

Add addresses

Create additional address slots on specific networks for an existing wallet. Each slot has an address_reference you choose.

Watch for deposits

Register addresses with Tender’s deposit monitor. When a deposit arrives, Tender sends a sub_user_wallet_transaction_detected webhook to your server.

Initiate transfers

Send funds from an address slot to any destination. Tender picks a native coin, token or gasless token transfer from the currency and network, and sends sub_user_wallet_transfer_confirmed (or sub_user_wallet_transfer_failed for a failed gasless transfer) when it settles.

Prerequisites

Authentication guide

These endpoints use Signed (HMAC) authentication — an HMAC-SHA256 signature is required on every request. See the authentication guide for code examples.

All subwallet endpoints share a limit of 120 requests per minute per merchant; GET /wallet/balance/:address is further limited to 30 per minute. See Rate limits.

Step 1 — Create a wallet

Call POST /wallet with a reference for the end-user. References are globally unique across Tender, so prefix them with something specific to your platform. Tender provisions the wallet and returns one address per supported network (EVM, TRON, BTC), each with its own generated address_reference and, where the network supports it, a gasless_address. Store the reference: it is the wallet_reference (and the transfer’s merchant_reference) in every later call for that user.

Create Wallet

Full parameters and response schema for POST /wallet

Step 2 — Add addresses to the wallet

Call POST /wallet/address with the wallet_reference, an address_reference of your choice (also globally unique), and the networks you want addresses on (EVM, TRON, BTC). All addresses from one call share that address_reference.

Create Address

Full parameters and response schema for POST /wallet/address

On networks where token transfers run gasless, tokens are spent from the slot’s gasless_address, not its address. Ask users to deposit tokens to the gasless_address when one is present.

Step 3 — Watch for deposits

Call POST /wallet/filter with the address and the network types to monitor (EVM, TRON, BTC). Once registered, Tender watches that address on-chain and sends a sub_user_wallet_transaction_detected webhook whenever a deposit is detected. The same deposit can be reported more than once as confirmations increase. Every webhook uses the envelope {"eventId": "<uuid>", "event": "<name>", "data": {…}}. sub_user_wallet_transaction_detected data fields:

Field	Description
`depositKey`	Unique key for the deposit (`chainId:txHash:index`). Use it to deduplicate.
`transactionId`	Tender’s ID for the deposit record
`walletReference`	The wallet this deposit belongs to
`addressReference`	The address slot’s reference
`addressId`	Tender’s ID for the receiving address
`chainId`	The chain the deposit arrived on (for example `ethereum`)
`network`	Network type of the receiving address (for example `EVM`)
`symbol`	Token symbol (for example `ETH`, `USDT`)
`address`	The receiving address
`txHash`	On-chain transaction hash
`index`	Position of the transfer within the transaction
`amount`	Amount in the token’s smallest unit (for example wei for ETH)
`decimals`	Decimal places — divide `amount` by `10 ** decimals` for the human value
`confirmed`	`false` on first detection; `true` once fully confirmed
`blockNumber`	Block the transaction was included in
`confirmations`	Current confirmation count
`confirmationsRequired`	Confirmations needed to consider the deposit settled
`occurredAt`	ISO 8601 timestamp of the event

{
  "eventId": "2b9c3f0e-5d1a-4e7b-9a62-0c8d4f1e7a35",
  "event": "sub_user_wallet_transaction_detected",
  "data": {
    "depositKey": "ethereum:0xabc...:0",
    "transactionId": "6710a1f2c3d4e5f601234567",
    "walletReference": "acme-user-8821",
    "addressReference": "acme-user-8821-slot-2",
    "addressId": "6710a0e1b2c3d4e5f6012345",
    "chainId": "ethereum",
    "network": "EVM",
    "symbol": "USDT",
    "address": "0x7d8e9f...",
    "txHash": "0xabc...",
    "index": 0,
    "amount": "1000000",
    "decimals": 6,
    "confirmed": false,
    "blockNumber": 21034567,
    "confirmations": 1,
    "confirmationsRequired": 12,
    "occurredAt": "2026-10-15T09:00:00Z"
  }
}

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

Add Deposit Filter

Full parameters and response schema for POST /wallet/filter

Step 4 — Initiate a transfer

Call POST /wallet/transfer with:

chain and currency (for example tron and usdt);
receiver and amount (human-readable units);
merchant_reference: the wallet reference to send from;
address_reference: the address slot to send from;
payment_reference: your own reference for this transfer, echoed in webhooks and the transaction list.

sender is optional; the source address is resolved from the two references. Supported chains: ethereum, tron, bitcoin The response depends on the transfer type:

Coin or on-chain token transfer: 200 with a tx_id. Tender sends sub_user_wallet_transfer_confirmed once the transaction confirms.
Gasless token transfer: 202 with an operation_id. Poll POST /wallet/transfer/status or wait for sub_user_wallet_transfer_confirmed / sub_user_wallet_transfer_failed.

Transfer Funds

Full parameters and response schema for POST /wallet/transfer

sub_user_wallet_transfer_confirmed data fields (on-chain transfers):

Field	Description
`transactionId`	Tender’s ID for the transfer record
`txHash`	On-chain transaction hash
`transferKey`	Unique key for this transfer; equals `txHash`
`walletReference`	Wallet the transfer was sent from
`addressReference`	Address slot the transfer was sent from
`network`	Network type, returned as-is (for example `tron`)
`type`	`coin` or `asset`
`sender` / `receiver`	Source and destination addresses
`amount`	Amount in human-readable units, as a string
`asset`	Currency symbol (for example `USDT`)
`paymentReference`	The `payment_reference` you sent
`blockNumber`	Block the transaction was included in

For gasless transfers, sub_user_wallet_transfer_confirmed and sub_user_wallet_transfer_failed carry the same fields without blockNumber, plus:

Field	Description
`operationId`	The `operation_id` returned by the transfer call
`transferKey`	Equals `operationId`
`status`	Final operation status, as returned by the gasless network (`succeeded` or `succeed` on success; `failed` on failure)
`txHash`	On-chain hash, if one was produced

{
  "eventId": "9f4e1c2a-7b3d-4a8e-b5c6-1d2e3f4a5b6c",
  "event": "sub_user_wallet_transfer_confirmed",
  "data": {
    "transactionId": "6710b3a4c5d6e7f801234567",
    "txHash": "7c1e9a...",
    "transferKey": "f3b0c2d1e4a5...",
    "operationId": "f3b0c2d1e4a5...",
    "status": "succeed",
    "walletReference": "acme-user-8821",
    "addressReference": "acme-user-8821-slot-2",
    "network": "tron",
    "type": "asset",
    "sender": "TLq9...",
    "receiver": "TABCef...",
    "amount": "50",
    "asset": "USDT",
    "paymentReference": "payout-9922"
  }
}

Utility operations

Operation	Endpoint	What it does
List wallets	`GET /wallet`	Paginated list of all wallets under your merchant account
List addresses	`GET /wallet/:walletReference/addresses`	Addresses belonging to a specific wallet
List transactions	`GET /wallet/:walletReference/transactions`	Deposits and transfers of a wallet, newest first
Get balance	`GET /wallet/balance/:address`	Native, USDT and USDC balances of an address
Transfer status	`POST /wallet/transfer/status`	Status of a gasless transfer by `operation_id`
Validate address	`POST /wallet/validate`	Check whether an address is valid on a network
Check watched	`GET /wallet/watch/:address`	Check whether an address is registered with the deposit monitor

Webhook events

Event	Sent when
`sub_user_wallet_transaction_detected`	A deposit is detected on a watched address, and again as it gains confirmations
`sub_user_wallet_transfer_confirmed`	An outbound transfer confirms on-chain, or a gasless transfer succeeds
`sub_user_wallet_transfer_failed`	A gasless transfer fails

Webhooks are delivered once, without retries. Use depositKey and transferKey to deduplicate, and use List Wallet Transactions to reconcile anything you missed. See Webhooks for how to configure your endpoint.

When the wallet service is unavailable

Any subwallet endpoint that talks to the blockchain can return 503 with Wallet service is temporarily unavailable. Please try again. Retry with backoff. For POST /wallet and POST /wallet/transfer, a 503 doesn’t tell you whether the action happened: check List Wallets or List Wallet Transactions before retrying.

Getting started

Online payments

Webhooks

Subwallets

How it works

Prerequisites

Authentication guide

Step 1 — Create a wallet

Create Wallet

Step 2 — Add addresses to the wallet

Create Address

Step 3 — Watch for deposits

Add Deposit Filter

Step 4 — Initiate a transfer

Transfer Funds

Utility operations

Webhook events

When the wallet service is unavailable

​How it works

​Prerequisites

Authentication guide

​Step 1 — Create a wallet

Create Wallet

​Step 2 — Add addresses to the wallet

Create Address

​Step 3 — Watch for deposits

Add Deposit Filter

​Step 4 — Initiate a transfer

Transfer Funds

​Utility operations

​Webhook events

​When the wallet service is unavailable

How it works

Prerequisites

Step 1 — Create a wallet

Step 2 — Add addresses to the wallet

Step 3 — Watch for deposits

Step 4 — Initiate a transfer

Utility operations

Webhook events

When the wallet service is unavailable