Documentation

Public docs for project teams and token holders

Use the audience guides if you want the shortest path, or open the deeper reference pages for fees, how migration works, security, FAQ, and glossary.

For Projects

Project admin guide

Use this guide if you are evaluating whether w3Swap fits your migration, budgeting for it, or preparing the admin-side launch flow from project creation through finalization.

Why teams use w3Swap

w3Swap is built for projects that want a more structured migration and clearer ownership of post-migration liquidity.

Migrate a legacy token to a new token without relying on bespoke claim forms or informal wallet tracking.
Capture value from old-token liquidity or sell pressure and use part of it to deepen liquidity for the new token.
Set clear eligibility rules, global ratios, or special per-wallet ratios before the migration opens.
Lock liquidity and unclaimed assets behind protocol rules instead of leaving everything to manual post-launch promises.
Give the community a more transparent narrative around migration mechanics, timing, and settlement.

Admin flow from setup to finalization

This is the end-to-end operating flow for a project team using w3Swap.

1
Create a new token first if the migration needs a fresh mint or upgraded token standard.
2
Create the project and configure old token, new token, base ratio, migration timing, and optional allowlist or special-ratio data.
3
Fund the project with the new-token supply allocated to the migration.
4
Create an ALT if the project uses a large allowlist and the client flow requires account-key compression.
5
Create or prepare the LP for the new token and seed it with at least the committed amount of SOL.
6
Activate the project so token holders can begin migrating during the configured window.
7
End the project after the migration window has passed so settlement and liquidation flows can proceed.
8
Liquidate collected old tokens into WSOL or SOL through the supported settlement path.
9
Add at least the required share of liquidation proceeds back into LP; the minimum is 25%.
10
Complete settlement, which starts the LP lockup period and records the settlement event on chain.
11
After the lockup period, finalize the project and reclaim remaining balances such as new tokens, old tokens, SOL, WSOL, and the LP position according to the finalization flow.
12
Deactivate and close the ALT if one was used and the project no longer needs it.

Configuration knobs per project

These are the main choices a project team makes before launch.

Token pair and ratio

Select the old token and new token, then define the base exchange ratio. If no special ratio is enabled, that base ratio applies to eligible holders.

Timing

Choose when the migration opens and closes. The platform config enforces the allowed duration bounds on chain.

Eligibility

Optionally enable an allowlist and optionally enable special per-wallet ratios. Both rely on Merkle roots plus an artifact URI.

Liquidity and lockup

Set the SOL commitment for the new LP and choose a lockup period that meets or exceeds the platform-configured minimum.

Lifecycle states

The on-chain project moves through a defined state machine rather than a loose checklist.

Created: the project metadata and configuration have been initialized.
Funded: the project has received the required funding for the migration flow.
Active: holders can migrate during the active migration window.
Ended: the migration window has closed and the project can move into liquidation and settlement.
Migrated / Liquidating / LiquidationComplete: intermediate post-window states used while processing old-token liquidation.
Finalized: settlement is complete, the LP lock timer is set, and final asset recovery can proceed after lockup ends.

What teams pay attention to after the window closes

The public launch is only part of the migration. The post-window steps matter just as much.

Liquidation and LP funding

Collected old tokens do not simply disappear. The project completes liquidation and then uses part of the resulting WSOL to deepen liquidity for the new token.

Settlement and lockup

Completing settlement starts the LP lock timer. The minimum LP lock duration is 30 days.

Unclaimed tokens

Unclaimed new tokens remain in controlled vaults until finalization. They are not meant to be instantly reclaimed at the end of the active migration window.

Finalization and rent recovery

After lockup ends, the project can recover remaining balances and reclaim rent from subordinate accounts that are closed as part of cleanup.

Limits and decision points

w3Swap can structure the migration, but it does not remove the need for project judgment.

Use careful public wording

The protocol can make behavior more visible and enforceable, but you should still message the migration as a live launch with market, execution, and community-trust risk.

Teams still need to communicate token addresses, timing, and expectations clearly to the community.
A strong allowlist or ratio design improves clarity, but the choices themselves are still made by the project.
Strong migrations clearly explain what happens to surrendered old tokens, unclaimed new tokens, and LP after settlement.

Next steps

Most teams read these pages next.

Review fees and costs Review trust model