Money & Amounts

How monetary values are represented across the Ezys API. This convention applies to every amount-bearing field in requests, responses, webhooks, and reconciliation data.

Where an individual field uses a different shape (e.g. a plain decimal string on some quote/intent fields), its endpoint page documents that explicitly — the per-endpoint pages are authoritative for exact field types.

Representation

All monetary values are exchanged as an integer amount in the currency's smallest (minor) unit, encoded as a JSON string, together with the currency code and its exponent:

{ "amountMinor": "1523456", "currency": "USD", "exponent": 2 }   // = USD 15,234.56

Field	Type	Description
amountMinor	string	Integer amount in the currency's minor unit. Always a string (see String encoding).
currency	string	Currency/asset code. ISO 4217 for fiat (KRW, USD); registered ticker for stablecoins (USDC).
exponent	number	Number of minor-unit digits. major = amountMinor / 10^exponent.

Minor unit & exponent

The exponent follows ISO 4217 for fiat, and the token's decimals for on-chain assets:

Currency	Exponent	Minor unit	Example (major → amountMinor)
KRW	0	1 won	1,500,000 → "1500000"
USD	2	cent	15,234.56 → "1523456"
USDC	6	micro-USDC	10,000 → "10000000000"
JPY	0	1 yen	100,000 → "100000"

Conversion is deterministic in both directions:

amountMinor = major × 10^exponent
major        = amountMinor / 10^exponent

currency and exponent are always sent together so the two sides never disagree on scale.

String encoding

amountMinor is always a JSON string, never a JSON number.

A minor-unit amount can exceed 2^53, which is the largest integer a JSON/JavaScript number can hold exactly. Sending it as a number would silently corrupt large values (e.g. high-value KRW or USDC micro amounts). Encoding as a string preserves every digit.

Rounding

Currency conversions are computed at full precision and then rounded down (floor) to the target currency's minor unit — in a single step, at the point the amount is finalized.

• Rounding direction is floor (toward the smaller amount). Never half-up or half-even.
• No sub-minor-unit value is silently dropped; the residual is accounted for internally, so settled amount + residual = exact amount always holds.
• Currencies with no registered scale are rejected explicitly rather than defaulting.

Example. Converting 1,500,000 KRW at 0.00076543 USD/KRW yields 1148.145 USD exactly; the API returns amountMinor: "114814" (floor to cents), not "114815".

On-chain assets

18-decimal on-chain assets exceed a 64-bit integer, so they are not represented with the int64 amountMinor field. On-chain amounts are carried as uint256 decimal strings in their native base unit (e.g. wei). Off-chain fiat and USDC use amountMinor; on-chain legs use the uint256 string form.

Display

Decimal points, thousands separators, and currency symbols are a client (UX) concern only. The API always exchanges minor-unit integers plus a currency code — clients format for display using exponent.

See also

• Quote API · Intent API — per-endpoint amount fields
• Overview → Conventions