A project moves to a new contract, publishes a ratio, and opens a swap window. Your wallet still shows the legacy balance, and the number you will end up holding is printed nowhere. Turning an announced ratio into a credited balance takes three separate checks, and the one that goes wrong is rarely the multiplication you were expecting.
What a conversion ratio actually states
A conversion ratio is a fixed exchange rate between two ledgers: how many units of the new token each unit of the legacy token buys. The project sets it, the swap contract enforces it, and it does not move with the market. Whatever the two tokens change hands at on the day you swap, the ratio you receive is the ratio that was written down.
Direction is the first thing to settle, because a ratio quoted as one to four reads two ways. It can mean one new unit for every four legacy units, or four new units for every one legacy unit, and those two readings differ by a factor of sixteen. Anchor the reading to something you can check independently: compare the new total supply against the legacy one. If the new supply is the smaller of the two, each legacy unit has to convert into less than one new unit, and any reading that says otherwise is inverted.
The second thing to settle is which balance the ratio applies to. A migration names an eligible set: balances held at a snapshot, balances still sitting in the legacy contract, or balances presented to the swap contract before it stops paying out. The ratio is identical for everyone inside that set, so everything below assumes your balance is in it. Whether the swap window is still open is a separate question from what the ratio would pay if it were.
Where the number comes from
The ratio is a decision, and the decision has an arithmetic backbone. A project fixes the size of the new ledger first, then divides it by the legacy units the migration has to absorb. The quotient is the ratio, which is why the ratio and the two supply figures reconcile: multiply the eligible legacy supply by the ratio and you get back the new supply reserved for the swap.
Take a project that fixes a new supply of 400,000,000 units and has 1,000,000,000 legacy units eligible to migrate. The ratio is the first figure divided by the second, so each legacy unit converts into 40% of one new unit. Read the other way round, it takes five legacy units to produce two new ones.
That derivation gives you a check you can run on any announcement. If a project publishes both supply figures and a ratio, the three have to agree. When they do not, either one of the three is wrong or the eligible set is narrower than you assumed, and finding out which matters more than recomputing your own balance from a figure that does not reconcile.
Working out your own entitlement
With direction and ratio settled, your own figure is one multiplication: legacy balance times the ratio. A balance of 12,500 legacy units at a ratio of 40% converts into 5,000 new units. Nothing in that step depends on price, and nothing in it depends on when inside the window you swap.
Do that multiplication in the units your wallet displays, because that is the form you can hold up against the announcement. The contract performs the same multiplication in a different unit system, and the two agree only when the decimals line up. That is the next check, and it is the one that produces answers off by whole powers of ten.
| What you need | Where to read it | What goes wrong without it |
|---|---|---|
| The ratio and which way it runs | The announcement, reconciled against the two supply figures | The result comes out inverted |
| The decimals of both tokens | The decimals function on each token contract | The result is off by a power of ten |
| The rounding rule | The integer arithmetic inside the swap function | A remainder stays in the legacy contract |
| Which balance is eligible | The announcement, and what the contract will accept | You count units the swap will not take |
Decimals are a second conversion, and they are the easy one to skip
Token contracts do not store fractional amounts. They store integers, and a separate value records where the decimal point belongs. In the ERC-20 standard, the optional decimals function returns the number of decimals the token uses; the specification illustrates it with a token whose value of eight means the stored amount is divided by one hundred million to reach its user representation.
Because that function is optional, the standard states that interfaces and other contracts must not expect the value to be present. When it is absent, the number of decimals is a convention you have to establish some other way, and filling the gap with a default you assume is how a balance gets misread by orders of magnitude.
A migration between two tokens with different decimals carries this scaling on top of the ratio. If the legacy token uses eighteen decimals and the new one uses six, the same displayed quantity is stored as integers that differ by a factor of 1,000,000,000,000. The swap contract carries that scaling internally, so a wallet holding both decimals values shows you the right number. Raw integers copied out of a block explorer are a different matter: a value read straight from a contract call is in base units, and setting a base-unit figure from one token beside a base-unit figure from the other compares two different scales.
Reading the ratio out of the contract rather than the announcement
An announcement is prose, and the swap contract is what pays. Open its verified source and find the two constants the swap function multiplies and divides by. Those constants are the ratio in its enforced form. If they disagree with the announcement, the constants are what your balance will be run through.
Read the decimals value off both token contracts while you are there. Two constants and two decimals values are the entire calculation, and all four are public reads that cost nothing to make.
Then confirm the result before you commit the balance. A swap contract needs a token approval before it can move your legacy tokens, and an approval can be granted for a small amount instead of the whole balance. Swapping a small amount, checking what arrives against your own arithmetic, and only then approving the rest turns the calculation into something you have observed rather than something you have derived.
Rounding, and the units that stay behind
The contract works in integers, and integer division truncates. When your legacy amount is not an exact multiple of the ratio's denominator, the division discards the remainder rather than rounding it up. At eighteen decimals the discarded piece is a fraction too small to have a display representation, and it is real all the same.
The remainder becomes visible when the payout is quantised more coarsely. A balance of 12,502 legacy units at the same 40% ratio computes to 5,000 new units and a fraction; a contract that credits whole units credits 5,000 and the fraction stays where it was. Work out in advance whether the leftover is a rounding remainder you can ignore or a legacy balance you will still be holding after the window shuts.
What the ratio does not tell you about value
A conversion ratio fixes quantities and makes no claim about worth. The number of units you hold changes, and that is the whole of what the ratio guarantees. Reading a ratio below one as a loss, or a ratio above one as a gain, treats an arithmetic conversion as a price movement.
What a migration does change is which ledger the market prices. Once both tokens exist, they trade separately, and their prices come from whatever demand meets them rather than from the ratio linking their supplies. The ERC-20 token you receive is a new contract with its own market, and the ratio is the one fixed thing carried across.
| What the ratio fixes | What it leaves to the market |
|---|---|
| How many new units your balance converts into | What one new unit is worth |
| The relationship between the two supply figures | Whether the new token trades above or below the old one |
| The arithmetic the swap contract performs | The value of your position after the swap |
The bottom line
A conversion ratio is one multiplication wrapped in three checks. Settle which direction the ratio runs by reconciling it against the two supply figures, read the decimals of both tokens so the scaling does not shift your answer by a power of ten, and find the rounding rule so you know what stays behind.
Then verify instead of trusting: the constants inside the swap contract are the ratio that will actually be applied, and a small test swap turns your arithmetic into an observation. To keep learning the fundamentals, follow more from Bitbase Academy.
Related reading
Other Bitbase articles on this topic:
- How to Revoke a Governance Delegation
- Why a Token Migration Asks for a Wallet Approval
- Token Migration Completed but New Tokens Are Not in Your Wallet
- NFT Wash Trading Warning Signs Explained
- ADX Indicator: How to Measure Trend Strength
Disclaimer: This article is educational content from Bitbase Academy, provided for information only. It does not constitute investment, trading, tax, or financial advice. Crypto assets are volatile; assess your own risk. Written as of September 2026; refer to the latest official information.
References
[1] Ethereum Improvement Proposals, ERC-20: Token Standard (EIP-20, Final), decimals method eips.ethereum.org
[2] ethereum.org Developer Documentation, ERC-20 Token Standard ethereum.org
