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

# Tempo Virtual Addresses (TIP-1022)

> Give each customer a Tempo deposit address that forwards TIP-20 deposits to one master vault account, with nothing to sweep and no per-customer wallet to fund.

> [!NOTE]
>
> Every Tempo feature in this section is in beta and available through the API only. To get access, contact your Customer Success Manager (CSM).

A virtual address is a deposit address that belongs to one registered master wallet. When a TIP-20 token is sent to it, Tempo forwards the funds to the master wallet in the same transaction. Nothing is held at the virtual address, so there's nothing to sweep and no per-customer wallet to fund. You can give each customer their own deposit address while keeping all funds in one vault account.

> [!WARNING]
>
> Never send ERC-20 tokens, or any non-TIP-20 asset, to a virtual address. Forwarding happens only inside TIP-20 transfers. Any other token contract records the deposit against the virtual address itself, and no private key controls that address. **Those funds can't be recovered.** The same applies if a virtual address is used on any other EVM network.

## How it works

A virtual address is a normal 20-byte address with a fixed layout:

```text theme={"system"}
0x | masterId (4 bytes) | marker 0xFDFD…FD (10 bytes) | userTag (6 bytes)
```

* `masterId` identifies the registered master wallet.
* The 10-byte marker is how Tempo recognizes the address as virtual.
* `userTag` is a value you choose, for example a customer ID. One master supports about 2.8 × 10^14 tags.

Only the master wallet registers on-chain, once. You build virtual addresses off-chain from `masterId` and a `userTag`. Creating one needs no transaction and costs nothing.

Also keep in mind:

* `balanceOf(virtualAddress)` is always 0. The balance shows on the master wallet.
* Receive policies and compliance checks run against the master wallet.
* If you mint an LP position or another protocol-recorded asset to a virtual address, it can be stranded unless that protocol supports virtual addresses.

See Tempo's [virtual addresses guide](https://tempo.xyz/developers/docs/protocol/tip20/virtual-addresses) for the protocol rules.

## Register a vault account as a master wallet

Call the register endpoint with the vault account and the Tempo asset:

```http theme={"system"}
POST /v1/vault/accounts/{vaultAccountId}/omnibus/tempo/{assetId}/register
```

Registration sends a one-time on-chain transaction that includes a proof-of-work salt, which Fireblocks mines for you. The first call returns `202` with the wallet status `PENDING_ACTIVATION`. Call it again to check progress. Once the wallet is `READY`, the call returns `200`.

```json Response theme={"system"}
{ "txId": "b7e1c2d4-…", "status": "PENDING_ACTIVATION" }
```

## Receive deposits

Fireblocks credits a TIP-20 deposit to one of your virtual addresses to the master vault account. The transaction's `blockchainInfo` tells you which virtual address received it:

```json theme={"system"}
"blockchainInfo": {
  "virtualAddress": "0x1a2b3c4dFDFDFDFDFDFDFDFDFDFDaabbccddeeff",
  "masterId": "0x1a2b3c4d",
  "userTag": "0xaabbccddeeff"
}
```

Match `userTag` against your own records to credit the right customer.

## Send to a virtual address

A virtual address is accepted as a destination like any other Tempo address. Use a `ONE_TIME_ADDRESS` destination or a whitelisted address. You can't send from a virtual address, because no key controls it. Always send from the master vault account.
