Use virtual addresses for deposits

Virtual addresses let you issue a distinct deposit address for each customer without creating a separate onchain TIP-20 balance for each one. The deposit is attributed to the virtual address, but the balance is credited directly to the registered master wallet.

This page is intentionally about the operator flow rather than the spec. In preview environments the demo may run against pre-release infrastructure, but the flow is the same one operators will use on public testnet.

How virtual address deposits work

The important behavior is:

• the sender pays the virtual address
• TIP-20 resolves that address to the registered master wallet
• the master wallet receives the balance
• the virtual address still appears in events, so you can attribute the deposit correctly

Virtual address live demo

This walkthrough shows the full flow:

1. sign in with a passkey and get a Tempo address
2. register a master id for that address
3. send pathUSD from a second address to a virtual address derived from that master id
4. confirm that the balance lands in the registered wallet

What to verify in virtual address deposits

When the demo succeeds, you should see all of the following:

• the passkey wallet is shown as the registered master wallet
• the virtual address is distinct from the master wallet
• the sender transfers pathUSD to the virtual address
• the master wallet balance increases
• the virtual address TIP-20 balance remains 0
• the receipt shows the expected two-hop Transfer events

Derive deposit addresses offchain

Once a master is registered, operators derive virtual addresses offchain from the masterId and their own customer tag.

import { VirtualAddress } from 'ox/tempo'
 
const virtualAddress = VirtualAddress.from({
  masterId,
  userTag: '0x000000000001',
})

In practice, the userTag is the operator's internal routing value for a customer, account, or payment reference.

Operational notes

A few things matter in production:

• virtual forwarding applies only to TIP-20 transfer and mint paths
• balanceOf(virtualAddress) stays 0; use events and your own userTag mapping for attribution
• policy checks apply to the resolved master wallet, not the literal virtual address
• avoid using virtual addresses in reward protocols (lending pools, DEX rewards, etc) unless explicitly supported, as they can't track or hold funds

Learn more about TIP-20 virtual addresses