Token Migration Guide: Moving to a New Contract or Mainnet

Your new contract is ready. However, one exchange still accepts the old token, a wallet shows the wrong address, and staked holders cannot claim. This token migration guide helps you prevent that split. It explains how to move to a new contract or mainnet while keeping holder balances, trading venues, and public information aligned.

The central question is simple: how will every eligible holder receive the right asset, through the right route, exactly once? Start with that question before you announce a date. Then use the holder matrix, exchange checklist, and migration register below to turn a technical change into a coordinated transition.

First, choose the right type of token migration

A new address, a new blockchain, and an extra network create different jobs. Therefore, write down which change you are making before asking partners to update anything. A shared name or ticker does not prove that two assets are interchangeable.

An upgrade does not always require holders to move. For example, the OpenZeppelin proxy pattern keeps a stable access address while changing the implementation. However, storage and permission errors can still cause harm. Ask your engineers whether a replacement token is necessary before creating a swap process.

A mainnet needs more than a new logo

For a native coin, there may be no token contract address. Instead, partners may need the network identifier, node software, RPC endpoints, explorer, native units, and address format. They must also understand fees, finality, and any memo or destination-tag requirements. If genesis balances form part of the transition, document how eligible holdings map into that allocation.

Next, test destination addresses and small transfers with each integration partner. Do not assume an Ethereum-style address works on a different chain. Likewise, a wallet that stores the old token may not support the new network. Plan how users will obtain any gas needed to use their new funds.

Adding a chain does not automatically retire the old token

If both networks remain live, explain the relationship between their assets. A lock-and-mint bridge, for example, holds backing on one side and issues a representation on the other. Consequently, simply adding both balances can count the same economic units twice. Publish the supply model, backing addresses, and treatment of transfers still in progress.

A second network can also divide liquidity across more pools and venues. Therefore, decide where users should trade and how they can move between supported networks. Describe separate assets as separate assets if they have no enforceable conversion relationship.

Map holders before choosing a token swap method

An explorer holder list shows addresses, not always the people entitled to the funds. Exchanges, pools, and contracts can hold tokens for many users. As a result, a blanket airdrop to every address can miss beneficiaries or credit the wrong recipient.

Personal wallets and exchange custody need different instructions

For self-custody, define whether users receive an allocation, claim from a snapshot, or exchange old tokens. Also, check smart-contract wallets and accounts controlled by applications. Not every address can sign a claim or accept the destination asset in the same way.

On Solana, one owner can have multiple token accounts for the same mint. Therefore, counting only the associated token account can omit eligible balances. Your ledger should identify the owner, mint, and relevant accounts, with separate handling for program-controlled funds.

For exchange custody, an on-chain wallet can represent many customers. The exchange must reconcile its internal accounts. Agree whether it performs the conversion or asks users to withdraw through an announced route. Never tell those users to claim separately if their exchange is already settling the same entitlement.

LP, staking, and vesting balances need explicit treatment

Liquidity providers own positions, not a simple slice determined by the token holder list. Uniswap uses tokens or NFTs to represent liquidity positions. Consequently, identify position owners, underlying assets, accrued fees, and any locked positions at the agreed record point. Do not assume the project can withdraw liquidity owned by other people.

For staking, reconcile principal and rewards separately. Then decide how receipt tokens and pending withdrawals affect eligibility. For vesting, preserve the beneficiary and economic release terms. Test both released and unreleased amounts. Simply sending replacement tokens into an existing vesting contract can produce an unintended release, depending on its design.

Finally, reconcile all holder groups against the replacement allocation. The address-level supply mapping approach can help organize the evidence. Mark escrow and beneficiary records as related, so the same underlying tokens appear only once in the settlement total.

Set the snapshot, swap ratio, and eligibility rules

A snapshot records state at a chosen point. It does not freeze transfers or stop another claim route. Therefore, your policy must explain who keeps the entitlement when old tokens move after that point.

Choose how entitlement is established

• Snapshot allocation: eligibility follows the approved record point. Later possession of old tokens does not automatically create a second entitlement.
• Surrender-based swap: eligibility depends on a validated exchange of old tokens under the approved mechanism. The implementation must prevent their reuse for another claim.
• Partner settlement: a custodian or protocol reconciles its users and settles the agreed allocation. Exclude that same allocation from overlapping public claims.

These are design choices, not interchangeable instructions. A project may use more than one route for different groups. However, each entitlement must belong to one route, with a clear rule preventing duplicate payment.

Consider an illustrative error: Alice holds 100 OLD at the snapshot, then sells those tokens to Bob. If Alice receives a snapshot allocation and Bob can also swap the same 100 OLD, the project pays twice. The policy and implementation must resolve that conflict before launch. Publish the post-snapshot trading risk clearly.

Record more than a calendar date

• Identify the old network and asset, plus the block height or slot and block hash where applicable.
• State the finality or confirmation policy. Add a UTC timestamp for coordination, not as a substitute for an exact chain record.
• Define eligible balances, exclusions, and treatment of rewards, pending transfers, and bridge messages.
• Agree how each exchange ledger cutoff relates to the on-chain record point.
• Assign an owner to disputed balances, late claims, and destination-address corrections.

Finality rules vary by network. For example, Solana distinguishes processed, confirmed, and finalized state. Avoid selecting one universal confirmation count for every blockchain. Instead, have the technical team document and test the record point it will use.

Keep the swap ratio separate from decimals

Write the ratio in plain English. For example, 100 OLD converts into 1 NEW. In this illustrative case, 125 eligible OLD becomes 1.25 NEW before any stated rounding rule. That changes the unit count; it does not guarantee a market value or price increase.

Also, record the decimals of both assets. A 1:1 conversion in displayed tokens may use different raw integer amounts. Engineers should calculate in base units and test rounding, very small balances, minimum claims, and leftover reserves. Publish those rules before users choose a route.

Before committing funds, review the new asset and the migration mechanism, including permissions, claim limits, and emergency controls. Use the smart contract audit provider guide to frame that review. An audit is useful evidence, but it cannot replace custody reconciliation and partner testing.

Coordinate the token migration with every exchange

Start with the exchange listing or asset-support team through a verified contact. Supply one versioned migration package, then keep a separate status for each venue. A notice from one exchange does not establish support elsewhere. Coinbase migration guidance illustrates why handling can differ by asset and platform.

Ask every exchange to confirm these items in writing:

1. Support: destination network, asset identifier, ratio, decimals, and which customer balances it will convert.
2. Funding cutoffs: separate UTC times for old-network deposits and withdrawals, including pending transactions.
3. Trading: whether orders remain open, get cancelled, or pause, and how the replacement pair will work.
4. Accounting: snapshot or ledger cutoff, allocation evidence, funding destination, and reconciliation contact.
5. Reopening: checks required for new deposits, withdrawals, and trading to resume.
6. Exceptions: late deposits, unsupported networks, disputed balances, and the escalation process.

Next, share the official announcement, technical documentation, explorer links, and security review. For a mainnet, include node and wallet integration requirements. Confirm any address mapping or memo rules before sending a test transfer. Never assume a token-page update means funding is ready.

If a venue declines support, publish that fact and its official withdrawal instructions while users can still act. Do not invent a recovery promise for deposits sent after a cutoff. Meanwhile, keep that venue marked as unsupported or unresolved until you have evidence of a different outcome.

Plan liquidity and trading pairs as a separate workstream

An old DEX pool does not automatically become a market for the new asset. Decide which new pools or pairs will exist, who supplies their inventory, and when they can open. Also, clarify what happens to project-owned liquidity and third-party LP positions. Locked liquidity may limit what the team can move.

Coordinate market makers with the exchanges so their asset identifiers, balances, and quoting systems match the new markets. Then test deposit and withdrawal paths before announcing normal trading. Monitor spreads, depth, and price feeds after reopening. Neither a swap ratio nor a successful contract deployment guarantees a market price or liquidity.

Update CoinGecko, CoinMarketCap, wallets, and explorers

Keep one canonical record of the old and new asset identities. Reuse it across applications, but track each platform independently. A support ticket, approved metadata change, visible logo, working wallet, and live price are different milestones.

CoinGecko: submit the correct migration request

Use CoinGecko’s contract migration or rebranding process. Prepare an official announcement, old and new identities, the old:new ratio, UTC date, explorer links, supported markets, and supply information. Explain whether the old asset is being retired or both networks will remain valid.

CoinGecko generally updates the existing page for a 1:1 migration and creates a new page for a non-1:1 migration. However, it retains discretion over the final treatment. Do not promise unchanged charts, rankings, or listing status to your community.

Prepare evidence early, but check submission timing. CoinGecko says migration requests are assumed to take effect soon, so an early request does not automatically schedule a future update. For broader listing preparation, use the CoinGecko listing guide.

CoinMarketCap: separate swap, supply, and market updates

The official CoinMarketCap request form guidance includes an existing-asset Coin/Token Swap route. It also separates market additions, supply updates, and general information changes. Select the routes that fit your case and cross-reference related tickets. One submission should not be treated as proof that all fields have changed.

After review, check the contract or native-chain identity, supply, announcement, and market links on the public page. Then confirm that each market points to the intended asset. The CoinMarketCap listing and market-update guide provides additional context for preparing those records.

Wallets and explorers: verify identity before appearance

Update token-list records by network and contract or mint, not by ticker alone. Trust Wallet’s asset repository guidance describes separate network folders and asset records. Its deprecation process applies when an old asset is actually being retired. Adding a legitimate second network is not, by itself, a reason to mark the first one abandoned.

Next, test logo, balance, network selection, and price display separately. Include the old and new asset details in support requests. For the relevant submission workflow, see the Trust Wallet token information guide. A merged metadata update does not move funds or guarantee price coverage.

For Ethereum tokens, Etherscan’s migration procedure asks for verified ownership of the new contract and an official announcement with both addresses. Request the appropriate migration notices. For another explorer, follow its own verified-owner process. Preserve the old page’s historical context so holders can recognize the transition.

Finally, check whether the destination blockchain itself has support. CoinGecko has a separate new-chain integration process. Likewise, a wallet may need network support before it can display or transfer your native coin. Contract metadata alone cannot supply that integration.

Publish clear instructions and block common migration scams

Create one migration information page on your established project domain. Link to it from your existing website and verified channels. Then publish separate instructions for self-custody, supported exchanges, unsupported venues, and locked or staked positions. Give every revision a timestamp and explain what changed.

The notice should state the purpose, affected networks, exact asset identifiers, ratio, eligibility, record point, deadlines, expected user actions, and support route. Also, specify whether a user must do nothing, claim, or follow an exchange announcement. Never hide important exceptions inside a chat thread.

A migration announcement template

Purpose: We are moving [old asset and network] to [new asset and network] because [reason]. The conversion is [OLD amount] to [NEW amount]. Eligibility follows [record point and rules].

Choose your route: Holders in personal wallets should [verified action or no action]. Customers of [confirmed supporting venues] should follow each venue’s notice. LP, staking, vesting, and unsupported-exchange holders should use their dedicated instructions at [official information page].

Timing and support: The confirmed cutoffs are [UTC times]. Our official support route is [verified channel]. We will never ask for a recovery phrase or private key. Check the destination, permissions, and expected result before signing anything.

Before publishing, replace every bracketed field and verify every link. If a partner has not confirmed a date, say that its schedule remains pending. Keep old official announcement URLs available, with a clear link to the current instructions.

Give holders checks they can actually use

• Open the migration page from the project’s established website, not a direct message or search advertisement.
• Check the full domain, network, asset address, and claim contract against the official notice.
• Never enter a seed phrase or private key into a website or send it to support.
• Review the requested approval or signature. Unexpected permissions or an unexplained transaction are reasons to stop.
• Use the published support route to report a conflicting link or notice. Do not rush because a stranger claims the deadline changed.

A legitimate claim can require a transaction and network gas. However, a signature can also grant dangerous permissions. Explain the expected interaction in your own instructions and verify it in testing. MetaMask’s recovery-phrase guidance reinforces the central rule: anyone with that secret can control the wallet.

Use this token migration checklist before launch

Keep a migration register that your operations, engineering, and support teams can review together. Use these column headings in a spreadsheet: holder group or platform; old identity; new identity; record point; ratio and decimals; entitlement evidence; settlement route; owner; written confirmation; status; evidence link; next action. Maintain private customer data and credentials separately.

For example, an exchange row should identify its confirmed conversion route and the evidence needed before reopening. An LP row should identify the position records and the person responsible for reconciling them. These are planning examples, not completed approvals.

1. Reconcile: eligible liabilities, exclusions, settled amounts, and funded replacement reserves match the approved model.
2. Prevent duplicate claims: exchange, wallet, LP, staking, vesting, and bridge routes cannot pay the same entitlement twice.
3. Test: representative account types, decimals, small balances, funding paths, and destination addresses behave as expected.
4. Confirm partners: each material venue has a supported route or a clearly communicated exception.
5. Check communication: the official page, support scripts, and partner notices agree.
6. Prepare a stop plan: responsible people know which controls they can pause, whom to contact, and how to preserve evidence.

Pause the launch if an allocation mismatch, unsupported destination, or unresolved custody route could strand holders. Also, avoid promising a universal rollback. Completed claims, burns, and third-party settlements may be irreversible. A tested stop and recovery plan is more useful than an assumed undo button.

After launch, reconcile claimed and unclaimed allocations, pending exceptions, vesting, and partner balances. Test public market links, logos, prices, deposits, and withdrawals. Finally, keep monitoring the old contract and information page for mistaken transfers and support requests under your published policy.

Token migration FAQ

Does a token migration require every holder to act?

No. The correct action depends on custody, network, and the chosen conversion route. An exchange may handle its own customers, while personal-wallet holders may need a claim. Therefore, publish instructions for each group and rely on confirmed partner notices.

Can the old token keep trading after the snapshot?

Yes, if its contract and venues still allow transfers and trading. A snapshot alone changes neither. Consequently, explain whether later buyers receive any migration entitlement and how the design prevents duplicate claims.

Will a 1:1 swap preserve the token price?

No. A 1:1 ratio specifies how many new units replace eligible old units. Market prices depend on trading and other conditions. It also does not guarantee unchanged liquidity, rankings, or price history on tracking platforms.

How long does a migration take?

There is no universal timeline. Scope, security review, custody reconciliation, network integration, and partner support determine readiness. Therefore, plan around confirmed milestones rather than a date that assumes all platforms will update together.

What happens to tokens in liquidity pools or vesting contracts?

They need dedicated treatment. LP ownership and underlying amounts must be reconciled, while vesting rights and past releases must remain consistent. Do not count both escrow balances and beneficiary entitlements as separate allocations.

Can the project guarantee that all listings will continue?

No. Exchanges, trackers, wallets, and explorers control their own support and review processes. Obtain confirmations, track exceptions, and check the visible result. A deployed contract or completed swap does not establish support everywhere.

Prepare your exchange transition before announcing the date

If your migration involves a new Tokpie market or destination network, review the Tokpie token and coin listing requirements and discuss the integration with the team. Bring the asset identities, holder treatment, ratio, proposed schedule, and test evidence. Then confirm the supported route and timing before telling holders what to do.