Suggested
View this page as Markdown

parse_units

Converts human-readable token amounts to UINT256 raw values by multiplying by 10^decimals. Prefer VARCHAR inputs for capital-moving amounts. Negative values are rejected, fractional digits beyond decimals are rejected, and decimals must be between 0 and 77. String inputs trim surrounding whitespace, allow an optional leading plus sign, right-pad fractional digits with zeros, accept trailing fractional zeros, and reject scientific notation. Values that exceed UINT256 currently wrap modulo 2^256; treat that as compatibility behavior and validate untrusted amounts before parsing.

Scalar function TypesEVM

Example

Runs locally

-- Convert an exact human USDC amount to its 6-decimal onchain integer
SELECT parse_units('12.345678', 6)::VARCHAR AS raw_usdc;
-- => [{"raw_usdc":"12345678"}]

API reference

parse_units(14 types) #

Parse a non-negative amount with the default 18-decimal scale; prefer VARCHAR for capital-moving amounts.

Exact signatures (14)
  • parse_units(VARCHAR)
  • parse_units(DOUBLE)
  • parse_units(FLOAT)
  • parse_units(TINYINT)
  • parse_units(SMALLINT)
  • parse_units(INTEGER)
  • parse_units(BIGINT)
  • parse_units(HUGEINT)
  • parse_units(UTINYINT)
  • parse_units(USMALLINT)
  • parse_units(UINTEGER)
  • parse_units(UBIGINT)
  • parse_units(UHUGEINT)
  • parse_units(UINT256)

Inputs

Name Type Use
value VARCHAR | DOUBLE | FLOAT | TINYINT | SMALLINT | INTEGER | BIGINT | HUGEINT | UTINYINT | USMALLINT | UINTEGER | UBIGINT | UHUGEINT | UINT256

Use VARCHAR for exact decimal amounts. Non-string numeric overloads are convenience forms.

 required positional

Returns

Name Type
raw_amount UINT256

Raw token units. Returns a UINT256 integer amount scaled by 10^decimals, suitable for ERC-20 calldata and simulations.

parse_units(14 types, INTEGER | UTINYINT | UINT8) #

Parse a non-negative amount with an explicit scale between 0 and 77; prefer VARCHAR for capital-moving amounts.

Exact signatures (42)
  • parse_units(VARCHAR, INTEGER)
  • parse_units(VARCHAR, UTINYINT)
  • parse_units(VARCHAR, UINT8)
  • parse_units(DOUBLE, INTEGER)
  • parse_units(DOUBLE, UTINYINT)
  • parse_units(DOUBLE, UINT8)
  • parse_units(FLOAT, INTEGER)
  • parse_units(FLOAT, UTINYINT)
  • parse_units(FLOAT, UINT8)
  • parse_units(TINYINT, INTEGER)
  • parse_units(TINYINT, UTINYINT)
  • parse_units(TINYINT, UINT8)
  • parse_units(SMALLINT, INTEGER)
  • parse_units(SMALLINT, UTINYINT)
  • parse_units(SMALLINT, UINT8)
  • parse_units(INTEGER, INTEGER)
  • parse_units(INTEGER, UTINYINT)
  • parse_units(INTEGER, UINT8)
  • parse_units(BIGINT, INTEGER)
  • parse_units(BIGINT, UTINYINT)
  • parse_units(BIGINT, UINT8)
  • parse_units(HUGEINT, INTEGER)
  • parse_units(HUGEINT, UTINYINT)
  • parse_units(HUGEINT, UINT8)
  • parse_units(UTINYINT, INTEGER)
  • parse_units(UTINYINT, UTINYINT)
  • parse_units(UTINYINT, UINT8)
  • parse_units(USMALLINT, INTEGER)
  • parse_units(USMALLINT, UTINYINT)
  • parse_units(USMALLINT, UINT8)
  • parse_units(UINTEGER, INTEGER)
  • parse_units(UINTEGER, UTINYINT)
  • parse_units(UINTEGER, UINT8)
  • parse_units(UBIGINT, INTEGER)
  • parse_units(UBIGINT, UTINYINT)
  • parse_units(UBIGINT, UINT8)
  • parse_units(UHUGEINT, INTEGER)
  • parse_units(UHUGEINT, UTINYINT)
  • parse_units(UHUGEINT, UINT8)
  • parse_units(UINT256, INTEGER)
  • parse_units(UINT256, UTINYINT)
  • parse_units(UINT256, UINT8)

Inputs

Name Type Use
value VARCHAR | DOUBLE | FLOAT | TINYINT | SMALLINT | INTEGER | BIGINT | HUGEINT | UTINYINT | USMALLINT | UINTEGER | UBIGINT | UHUGEINT | UINT256

Use VARCHAR for exact decimal amounts. Non-string numeric overloads are convenience forms.

 required positional
decimals INTEGER | UTINYINT | UINT8

Decimal precision used by the token contract. Must be an integer between 0 and 77.

 required positional

Returns

Name Type
raw_amount UINT256

Raw token units. Returns a UINT256 integer amount scaled by 10^decimals, suitable for ERC-20 calldata and simulations.

Guidance

Raw units vs display strings

Use string literals for token amounts that may move value. The string parser is decimal-exact and rejects scientific notation, negative values, and excess fractional precision.

  • Use parse_units('2500', 6) for 2,500 USDC-style tokens.
  • Use parse_ether for ETH and WETH amounts with the fixed 18-decimal scale.
  • Use format_units or format_ether when you need display strings from raw integer balances.
  • Do not pass FLOAT or DOUBLE values for capital-moving token amounts; those overloads are convenience-only and inherit floating point ambiguity before conversion.

Runs locally

SELECT
  parse_units('2500', 6) AS raw_usdc,
  parse_ether('1.25') AS raw_eth;

Examples

Runs locally

-- Decimal strings preserve digits that a binary DOUBLE cannot represent exactly
SELECT
  parse_units('0.100000000000000001', 18)::VARCHAR AS exact_string,
  parse_units(0.100000000000000001::DOUBLE, 18)::VARCHAR AS floating_input;
-- => [{"exact_string":"100000000000000001","floating_input":"100000000000000006"}]