> Feedback: If these docs are stale, missing, or confusing, post sanitized feedback to `https://docs.tempo.xyz/api/feedback` with `source: "mcp"`, a short `message`, and any relevant `toolName`, `relatedResource`, or `client`.
# 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.

## What happens

<MermaidDiagram
  chart={`sequenceDiagram
  participant Sender
  participant TIP20 as TIP-20
  participant Registry as Virtual registry
  participant Master as Registered wallet

  Sender->>TIP20: transfer(virtualAddress, amount)
  TIP20->>Registry: resolve(masterId)
  Registry-->>TIP20: master wallet
  TIP20->>Master: credit balance
  Note over TIP20: emits Transfer(sender → virtual, amount)
  Note over TIP20: emits Transfer(virtual → master, amount)
`}
/>

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

## 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

<Tabs stateKey="virtual-address-demo-mode">
  <Tab title="Fast demo">
    <div className="h-4" />

    Use a docs-managed master with a pre-mined valid salt so you can skip the wait and jump straight to the forwarding flow.

    <div className="h-6" />

    <Demo.Container name="Virtual addresses" footerVariant={undefined}>
      <VirtualAddressesFastDemo />
    </Demo.Container>
  </Tab>

  <Tab title="Real registration">
    <div className="h-4" />

    Use `VirtualMaster.mineSaltAsync` to register a master id for the passkey account you create in the demo.

    <div className="h-4" />

    :::info
    Mining the TIP-1022 salt can take 30+ seconds depending on your browser, hardware, and available worker parallelism.
    :::

    <div className="h-6" />

    <Demo.Container name="Virtual addresses" footerVariant={undefined}>
      <VirtualAddressesLiveDemo />
    </Demo.Container>
  </Tab>
</Tabs>

## What to look for

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.

:::code-group

```ts [virtualAddress.ts]
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

<Cards>
  <Card title="Virtual addresses overview" description="Start with the conceptual model for routing, attribution, and treasury operations." to="/docs/protocol/tip20/virtual-addresses" icon="lucide:route" />

  <Card title="TIP-1022 specification" description="Read the full protocol definition, including derivation rules, transfer paths, and invariants." to="https://github.com/tempoxyz/tempo/blob/main/tips/tip-1022.md" icon="lucide:file-text" />

  <Card title="T3 network upgrade" description="See when virtual addresses activate and what else ships with T3." to="/docs/protocol/upgrades/t3" icon="lucide:rocket" />
</Cards>