Scaled Integers

Scaled integers are how Polyester represents decimal values in typed protobuf API contracts.

These fields represent prices, quantities, balances, fees, and chart series as integer values. Direct protobuf clients must determine which scale applies before parsing or encoding values.

If you use the official Polyester TypeScript, Python, or Go SDK, normal amount conversion is handled by the SDK. This guide is mainly for developers who work with protobuf contracts directly or build lower-level ConnectRPC tooling.

The short version

Use this mental model:

• Trading prices use 6-decimal ticks: fields named *_ticks make this explicit; market-data OHLC fields such as open, high, low, and close use the same scale without the suffix.
• Quantities use asset scale: trading pair quantities use base_quantity_scale or quote_quantity_scale from GetSpotConfigResponse.pairs; asset-only APIs use quantity_scale from GetSpotConfigResponse.assets.
• Ledger and chain canonical amount fields use 18 decimals: U128 ledger balance fields and fields named amount_e18 are 18-decimal integer values. Non-amount U128 identifiers are not decimals.
• Chart series may use their own scale: *_q fields are compact chart values and must be read from the field's API documentation. Do not use them as authoritative balances.
• Basis points are not scaled decimals: *_bps fields are direct integer basis points.

Why APIs use scaled integers

Scaled integers avoid floating-point drift, keep protobuf payloads compact, reduce serialization and deserialization work, and make matching, balance, and settlement calculations deterministic. For trading activity, those encoding costs matter because busy clients may send and receive many prices, quantities, fills, balances, and book levels per second.

The conversion rule is:

scaled integer = decimal value * 10^scale
decimal value = scaled integer / 10^scale

For example, if BTC has quantity_scale = 8, then 0.001 BTC is encoded as:

0.001 * 10^8 = 100000

Transport behavior

ConnectRPC clients use generated integer types and decode using the field's scale. REST amount strings are decimals, while non-amount U128 identifiers such as withdraw nonce are unsigned integer strings.

If you build directly on generated protobuf types in TypeScript or JavaScript, do not store 64-bit scaled values in Number. Use your generated protobuf type, bigint, or string-backed helpers. For U128 values, ConnectRPC JSON/protojson uses { "hi": "...", "lo": "..." }.

Scale registry

The suffix alone is not enough for every *_scaled field. Use the field comment and denomination to choose base, quote, or asset scale.

Trading prices

Trading prices use ticks with a fixed 6-decimal scale. This is independent of the quote asset's quantity scale.

{
	"price_ticks": "50000000000"
}

Decode it as:

50000000000 / 10^6 = 50000.000000

Use this rule for fields such as price_ticks, avg_price_ticks, trigger_price_ticks, limit_price_ticks, activation_price_ticks, market-data OHLC prices, and heatmap fields such as mid_ticks.

Slippage and trailing distance tick fields use the same 1e-6 quote-unit tick space, but they are price deltas rather than absolute prices. For example, market_max_slippage_ticks, max_slippage_ticks, and trailing_distance_ticks are added to or subtracted from a reference price.

Price protection fields often appear as oneof alternatives. Send either the tick form, such as market_max_slippage_ticks, or the basis-point form, such as market_max_slippage_bps, not both.

Trading quantities

Trading order quantities use the pair's base asset scale.

To decode pair-specific quantities, fetch GetSpotConfigResponse and locate the pair in pairs by symbol_id or symbol. For BTC-USDT, if that PairConfig says:

{
	"symbol_id": 1,
	"symbol": "BTC-USDT",
	"base_quantity_scale": 8,
	"quote_quantity_scale": 6
}

Then this ConnectRPC payload:

{
	"qty_scaled": "100000"
}

Means:

100000 / 10^8 = 0.001 BTC

Use the base scale for order quantities, orderbook quantities, executed quantities, and base volume fields.

Order read quantities use the _scaled suffix too: fields such as orig_qty_scaled, cum_qty_scaled, and leaves_qty_scaled use the pair's base_quantity_scale.

Order placement has two explicit sizing alternatives. base_qty_scaled uses base_quantity_scale. max_quote_debit_scaled uses quote_quantity_scale because it is a hard all-in quote budget. Preview and create responses return resolved_base_qty_scaled using the base scale and can echo submitted_max_quote_debit_scaled using the quote scale. See Order Sizing for eligibility and acknowledgement semantics.

Use the quote scale for quote-denominated totals, quote volume, and quote-side fees. Use the asset quantity_scale for asset-scaled fields such as supply analytics. Internal transfers use amount_e18 instead.

quantity_display_decimals is display guidance only. Do not use it for protobuf encode or decode; use base_quantity_scale, quote_quantity_scale, or asset quantity_scale.

Fees and quote-side values

Fees and quote-side totals use the asset that the value is denominated in.

For trades, use the companion fee_asset field to choose the scale:

• If fee_asset is QUOTE or FEE_ASSET_UNSPECIFIED, decode fee_scaled with quote_quantity_scale.
• If fee_asset is BASE, decode fee_scaled with base_quantity_scale.
• Referral share fields follow the same asset-denomination rule as fee_scaled.

SELL fees are always quote-denominated. For BUY trades, fee_asset decides whether the fee is charged in quote (QUOTE) or deducted from received base (BASE). See Fee Assets for valid combinations.

Quote volume is also quote-denominated. Decode fields such as volume_24h_quote_scaled with the quote asset scale, not the price tick scale.

Ledger balances

Ledger balance fields use U128 integer values with 18 decimal places. This ledger scale is fixed and does not come from GetSpotConfigResponse quantity scales.

These fields are larger than regular 64-bit quantities because balances and movements must be represented without overflow across assets and accounts.

U128 is split into two 64-bit halves. Reconstruct the full integer before applying the decimal scale:

u128 = (hi << 64) | lo
decimal = u128 / 10^18

For a non-zero hi example:

hi = 1, lo = 0
u128 = 18446744073709551616
decimal = 18.446744073709551616

{
	"trading": {
		"hi": "0",
		"lo": "1500000000000000000"
	}
}

Decode it as:

(0 << 64 | 1500000000000000000) / 10^18 = 1.5

Use the ledger scale for balance fields such as trading, funding, reserved, and available.

U128 itself is only an unsigned integer container. Amount fields using U128 are 18-decimal when their field comment says so, but identifier fields are not decimals. For example, withdraw payload nonce is a raw unsigned 128-bit identifier and must not be divided by 10^18.

18-decimal amount_e18 fields

Any field named amount_e18 uses fixed 18-decimal scale. This includes ledger transfer rows, order transfer legs, chain lifecycle flows, and withdraw payloads.

{
	"amount_e18": {
		"hi": "0",
		"lo": "500000000000000000"
	}
}

This represents:

(0 << 64 | 500000000000000000) / 10^18 = 0.5

The _e18 suffix is intentional: decode it with 18 decimals, not with GetSpotConfigResponse asset scale.

Chart series and q fields

Fields ending in _q are compact quantity-like series values. They are not one universal scale.

Common examples:

When a field uses _q, check that field's API documentation. Do not infer the scale from another _q field.

Some _q series and delta fields are signed. Preserve the signedness from the generated protobuf type instead of assuming every compact series is unsigned.

Basis points

Basis point fields are plain integers, not decimal fixed-point fields. Divide by 100 only when rendering a percentage for humans.

1 bp = 0.01%
100 bps = 1%
250 bps = 2.5%

Use this rule for fields such as market_max_slippage_bps, trailing_distance_bps, and change_24h_bps.

Conversion cookbook

When sending a ConnectRPC request:

1. Fetch and cache GetSpotConfigResponse when the field uses pair or asset scale.
2. Find the field's denomination: base asset, quote asset, ledger amount, chain amount, price, chart value, or basis points.
3. Pick the scale from the registry above.
4. Parse the user decimal as an exact decimal string.
5. Reject values with more fractional digits than the scale supports.
6. Validate trading inputs against applicable constraints such as tick_size, step_size, minimum quantity, and minimum notional.
7. Send the resulting integer in the protobuf field.

When reading a ConnectRPC response:

1. Read the field suffix and field documentation.
2. Resolve the scale from GetSpotConfigResponse or from the fixed-scale registry.
3. Format the integer as a decimal string for display.
4. Keep the original integer for follow-up API calls when possible.

Example order input:

symbol: BTC-USDT
price: 50000.000000
qty: 0.001
base_quantity_scale: 8

price_ticks = 50000.000000 * 10^6 = 50000000000
qty_scaled = 0.001 * 10^8 = 100000

Common mistakes

• Do not use JavaScript Number for 64-bit scaled integers.
• Do not multiply or divide financial values with floating-point types.
• Do not decode a U128 from lo alone. Combine hi and lo first.
• Do not assume every amount with 18 decimals is a trading quantity.
• Do not apply 18-decimal scaling to non-amount U128 fields such as nonce.
• Do not decode price_ticks with quote asset scale.
• Do not decode fee_scaled without checking fee_asset.
• Do not treat _q as a single global scale or canonical money.
• Do not use quantity_display_decimals for protobuf encode/decode. It is display guidance only.
• Do not drop signedness from generated types; some compact series and deltas are signed.
• Do not mix decimal strings and scaled integers inside the same client path.
• Do not round silently when a user enters more fractional digits than the scale allows.

When in doubt, prefer the protobuf field comment and GetSpotConfigResponse over examples copied from another endpoint.