USDC / Token Base-Unit Converter

Why on-chain amounts are stored as base units

Blockchains don't store fractional numbers. An ERC-20 token contract — and every protocol built on top of one, including x402 — keeps balances and transfer amounts as plain integers measured in the token's smallest indivisible unit, the base unit. The human-friendly number you see in a wallet is just a display convenience produced by dividing by 10decimals.

So to put a price on-chain you do the reverse — multiply by 10decimals:

base_units = human_amount × 10^decimals
human_amount = base_units ÷ 10^decimals

Doing this with floating-point numbers is a classic source of bugs: 0.1 + 0.2 isn't exactly 0.3 in IEEE-754, and at 18 decimals those tiny errors become real lost (or extra) tokens. That's why this converter uses exact string/integer math instead of JavaScript floats, and why on-chain code uses BigInt / uint256 everywhere.

Token decimals reference

"How many decimals does this token have?" decides every conversion. Here are the common ones. When in doubt, read the token contract's decimals() function on a block explorer — never assume.

Base units in x402 maxAmountRequired

If you're building an HTTP 402 paywall, the maxAmountRequired field is exactly a base-unit value — as a string. Get it wrong and clients either overpay, underpay, or reject the challenge. Worked examples for USDC (6 decimals):

Do it in code

For production, convert with big-integer math, not Number. JavaScript / TypeScript with viem:

import { parseUnits, formatUnits } from 'viem'

// human -> base units (returns a bigint)
const amount = parseUnits('0.01', 6)   // 10000n  (USDC)

// base units -> human string
const human = formatUnits(10000n, 6)   // "0.01"

Plain JS without a library:

// human -> base units, exact (no float drift)
function toBaseUnits(amount, decimals) {
  const [int, frac = ''] = String(amount).split('.')
  return BigInt(int + frac.padEnd(decimals, '0').slice(0, decimals))
}
toBaseUnits('1.5', 6) // 1500000n

Python (use Decimal, never float):

from decimal import Decimal
base = int(Decimal("0.01") * (10 ** 6))   # 10000

Common pitfalls

• Assuming 18 decimals. USDC and USDT use 6, WBTC uses 8. Multiplying a USDC price by 10¹⁸ overcharges by a trillion ×.
• Using floats. 0.07 * 1e6 can yield 70000.00000000001. Always use integer/BigInt math or a decimal library.
• Passing a number where a string is expected. JSON-based protocols like x402 want maxAmountRequired as a string to preserve precision for large values.
• Trusting a hard-coded decimals value across chains. The same token symbol can have different decimals on different networks; read decimals() from the contract.
• Too many decimal places. You can't express $0.0000001 in USDC (only 6 decimals). This tool flags that instead of silently truncating.

Frequently asked questions