> For the complete documentation index, see [llms.txt](https://docs.nftx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nftx.io/how-it-works/migrating-from-legacy.md).

# Migrating from NFTX v2/v3

How to move NFTX v1–v3 vault tokens into v4 — whole NFTs migrate in one transaction, and sub-unit "dust" balances get a 1:1 swap path.

NFTX pioneered fungible NFT liquidity in 2020, and plenty of vault tokens from those earlier generations are still out there. If you hold v2 or v3 vault tokens (vTokens), the **Migrator Zap** moves you into v4 in a single transaction: it redeems whole NFTs from the legacy vault, deposits them straight into the v4 vault, and mints you the collection's [floor token](https://docs.nftx.io/how-it-works/floor-tokens.md) 1:1.

Behind the scenes, one migration call does three things: it pulls your legacy vault tokens, burns them against the legacy vault to withdraw the specific NFTs you named, and deposits those NFTs into the v4 Locker — which mints fresh floor tokens directly to whichever address you choose. The NFTs only pass through the zap for the length of the transaction; nothing is held.

{% hint style="info" %}
Migration runs on **Ethereum Mainnet only** — the legacy v2/v3 vaults were never deployed anywhere else.
{% endhint %}

## Whole units migrate instantly

One NFT costs exactly `1.0` legacy vault tokens, so migration works in whole units: `N` vault tokens → `N` NFTs → `N` floor tokens. The two legacy generations charge for the redeem differently:

* **From v2**, the vault's redeem fee is paid in vault tokens on top of the principal — unless the zap has been fee-excluded by the legacy factory owners, in which case you pay the principal alone. `quoteV2` tells you the exact cost before you commit.
* **From v3**, the redeem fee and any premium are paid in ETH. Premiums apply to recently deposited items and can be significant — `quoteV3Eth` prices your exact token IDs, and any ETH the vault doesn't take is refunded in the same transaction.

For example: Alice holds `3.4 MILADY` from NFTX v2. She calls `migrateFromV2` with three token IDs, spends `3.0` vault tokens (plus the v2 redeem fee if the zap isn't fee-excluded yet), and receives `3.0` v4 MILADY floor tokens. The `0.4` left over can never redeem an NFT on its own — that remainder is what we call **dust**.

## The dust swap

Dust is a legacy balance below `1.0` — too small to redeem an NFT, and often too small to be worth selling. Rather than leave it stranded, the Migrator Zap carries a simple escrow:

{% stepper %}
{% step %}

## We register the pair

For each legacy vault token being retired, we register which v4 token replaces it. Deposits are only accepted for registered pairs.
{% endstep %}

{% step %}

## You deposit your dust

Call `depositDust` with the legacy token and amount. The zap escrows it and records the deposit under an ID that's yours alone.
{% endstep %}

{% step %}

## We fill the swap — always at 1:1

We settle deposits in batches. When yours is filled you receive exactly the amount you deposited, in the replacement token, and the swap is closed. Deposit `0.4`, receive `0.4`.
{% endstep %}
{% endstepper %}

Changed your mind, or tired of waiting? Call `withdrawDust` and your legacy tokens come straight back. Cancelling works at any time before the fill — even while the zap is paused, and even if the pair has since been retired.

## Being straight about the trust assumptions

The dust swap is an escrow with a manual fill, and you should understand exactly what that means before depositing:

* **Fill timing is at our discretion.** Deposits are settled in batches, and nothing on-chain guarantees *when* a batch is filled. The payout also comes from replacement tokens we fund onto the contract ahead of settlement.
* **Your exit is never at our discretion.** Withdrawal is the one path that can't be paused, and escrowed deposits are excluded from every owner-recovery function — the contract cannot sweep your dust out from under you. Until the moment your swap is filled, your tokens are one transaction away.

That's the whole deal: we control when the swap completes; you control whether your tokens stay in it.

The full function reference lives in the [Migrator Zap](https://docs.nftx.io/contracts/migrator-zap.md) contract page.
