Formatting Prices and Sizes for Orders

When placing orders on Decibel, you need to convert decimal prices and sizes to chain units that match the market’s precision requirements. This guide explains how to use market configuration data from the v1/markets endpoint to properly format your order parameters.

Market Configuration

Each market returned from the v1/markets endpoint includes precision configuration:

{
  "asset_type": "perp",
  "lot_size": 1,
  "market_addr": "<string>",
  "market_name": "<string>",
  "max_leverage": 1,
  "max_open_interest": 123,
  "max_price": 123,
  "min_price": 1,
  "min_size": 1,
  "mode": "Open",
  "px_decimals": 6,
  "sz_decimals": 1,
  "tick_size": 1
}

Market Configuration Fields

px_decimals - The number of decimal places used for price precision. Prices are stored as integers with this many implied decimal places. Perp markets always use px_decimals = 6 (prices are in the collateral asset’s decimals): a price of 5.67 is stored as 5670000 (5.67 × 10^6). Spot markets use the quote asset’s decimals.
sz_decimals - The number of decimal places used for size precision. Order sizes are stored as integers with this many implied decimal places. This is per market (2–8 on mainnet perps). For APT/USD, sz_decimals = 5, so a size of 1.5 is stored as 150000 (1.5 × 10^5).
tick_size - The minimum price increment in chain units. Prices must be multiples of this value. For APT/USD, tick_size = 100 with px_decimals = 6, so the minimum price increment is $0.0001 (100 / 10^6).
lot_size - The minimum size increment in chain units. Order sizes must be multiples of this value. For APT/USD, lot_size = 10000 with sz_decimals = 5, so the minimum size increment is 0.1 APT (10000 / 10^5).
min_size - The minimum order size in chain units. Orders smaller than this will be rejected. For APT/USD, min_size = 100000 with sz_decimals = 5, so the minimum order size is 1 APT (100000 / 10^5).
min_price / max_price - The price band the market currently accepts, in chain units. Orders priced outside it abort with EPRICE_TOO_SMALL / EPRICE_TOO_LARGE.
mode - The market state. Only Open accepts every order; ReduceOnly, AllowlistOnly, Halt and Delisting restrict or refuse placement.

Conversion Functions

Convert Decimal Amount to Chain Units

/**
 * Converts a decimal amount to chain units (e.g., USDC).
 * For USDC, this means multiplying by 10^6.
 * @param amount - The decimal amount to convert
 * @param decimal - The number of decimal places for the token (default is 6 for USDC).
 * @returns The amount in chain units
 */
export function amountToChainUnits(amount: number, decimal = 6): number {
  return Math.floor(amount * 10 ** decimal);
}

def amount_to_chain_units(amount: float, decimal: int = 6) -> int:
    """
    Converts a decimal amount to chain units (e.g., USDC).
    For USDC, this means multiplying by 10^6.

    Args:
        amount: The decimal amount to convert
        decimal: The number of decimal places for the token (default is 6 for USDC)

    Returns:
        The amount in chain units
    """
    return int(amount * (10 ** decimal))

Convert Chain Units to Decimal Amount

/**
 * Converts chain units to decimal amount (e.g., USDC).
 * For USDC, this means dividing by 10^6.
 * @param chainUnits - The amount in chain units
 * @param decimal - The number of decimal places for the token (default is 6 for USDC).
 * @returns The decimal amount
 */
export function chainUnitsToAmount(chainUnits: number, decimal = 6): number {
  return chainUnits / 10 ** decimal;
}

def chain_units_to_amount(chain_units: int, decimal: int = 6) -> float:
    """
    Converts chain units to decimal amount (e.g., USDC).
    For USDC, this means dividing by 10^6.

    Args:
        chain_units: The amount in chain units
        decimal: The number of decimal places for the token (default is 6 for USDC)

    Returns:
        The decimal amount
    """
    return chain_units / (10 ** decimal)

Price Formatting

Round Price to Valid Tick Size

Prices must be rounded to the nearest valid tick size. Use this function to ensure your price is valid:

/**
 * Rounds a price to the nearest valid tick size
 * @param price - The decimal price to round
 * @param market - The market configuration object
 * @returns The rounded price
 */
export function roundToValidPrice(price: number, market: PerpMarket): number {
  if (price === 0) {
    return 0;
  }

// Convert to chain units
const denormalizedPrice = price \* 10 \*\* market.px_decimals;

// Round to nearest multiple of tickSize
const roundedPrice =
Math.round(denormalizedPrice / market.tick_size) \* market.tick_size;

// Convert back to decimal
const normalizedPrice = Math.round(roundedPrice) / 10 \*\* market.px_decimals;

return normalizedPrice;
}

def round_to_valid_price(price: float, market: dict) -> float:
    """
    Rounds a price to the nearest valid tick size.

    Args:
        price: The decimal price to round
        market: The market configuration object with px_decimals and tick_size

    Returns:
        The rounded price
    """
    if price == 0:
        return 0.0

    # Convert to chain units
    denormalized_price = price * (10 ** market["px_decimals"])

    # Round to nearest multiple of tick_size
    rounded_price = round(denormalized_price / market["tick_size"]) * market["tick_size"]

    # Convert back to decimal
    normalized_price = round(rounded_price) / (10 ** market["px_decimals"])

    return normalized_price

Size Formatting

Round Size to Valid Lot Size

Order sizes must be rounded to the nearest valid lot size and meet the minimum size requirement:

/**
 * Rounds an order size to the nearest valid lot size
 * @param orderSize - The decimal order size to round
 * @param market - The market configuration object
 * @returns The rounded order size
 */
export function roundToValidOrderSize(
  orderSize: number,
  market: PerpMarket
): number {
  if (orderSize === 0) {
    return 0;
  }

const normalizedMinSize = market.min_size / 10 \*\* market.sz_decimals;

// Ensure size meets minimum requirement
if (orderSize < normalizedMinSize) {
return normalizedMinSize;
}

// Convert to chain units
const denormalizedOrderSize = orderSize \* 10 \*\* market.sz_decimals;

// Round to nearest multiple of lotSize
const roundedOrderSize =
Math.round(denormalizedOrderSize / market.lot_size) \* market.lot_size;

// Convert back to decimal
const normalizedOrderSize =
Math.round(roundedOrderSize) / 10 \*\* market.sz_decimals;

return normalizedOrderSize;
}

def round_to_valid_order_size(order_size: float, market: dict) -> float:
    """
    Rounds an order size to the nearest valid lot size.

    Args:
        order_size: The decimal order size to round
        market: The market configuration object with sz_decimals, lot_size, and min_size

    Returns:
        The rounded order size
    """
    if order_size == 0:
        return 0.0

    normalized_min_size = market["min_size"] / (10 ** market["sz_decimals"])

    # Ensure size meets minimum requirement
    if order_size < normalized_min_size:
        return normalized_min_size

    # Convert to chain units
    denormalized_order_size = order_size * (10 ** market["sz_decimals"])

    # Round to nearest multiple of lot_size
    rounded_order_size = round(denormalized_order_size / market["lot_size"]) * market["lot_size"]

    # Convert back to decimal
    normalized_order_size = round(rounded_order_size) / (10 ** market["sz_decimals"])

    return normalized_order_size

Complete Example

Here’s a complete example of formatting prices and sizes for placing an order:

// Fetch market data from v1/markets endpoint
const market = {
  market_addr: "0x456...def",
  market_name: "APT/USD",
  px_decimals: 6,
  sz_decimals: 5,
  tick_size: 100, // $0.0001 (100 / 10^6)
  lot_size: 10000, // 0.1 APT (10000 / 10^5)
  min_size: 100000, // 1 APT (100000 / 10^5)
};

// User wants to place an order at $5.67894 with size 1.234
const userPrice = 5.67894;
const userSize = 1.234;

// Step 1: Round price to valid tick size
const roundedPrice = roundToValidPrice(userPrice, market);
// Result: 5.6789 (rounded to nearest 0.0001)

// Step 2: Round size to valid lot size and check minimum
const roundedSize = roundToValidOrderSize(userSize, market);
// Result: 1.2 (rounded to nearest 0.1 APT, meets minimum of 1 APT)

// Step 3: Convert to chain units for the transaction
const chainPrice = amountToChainUnits(roundedPrice, market.px_decimals);
// Result: 5678900 (5.6789 × 10^6)

const chainSize = amountToChainUnits(roundedSize, market.sz_decimals);
// Result: 120000 (1.2 × 10^5)

// Step 4: Build and submit transaction
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: `${PACKAGE}::dex_accounts_entry::place_order_to_subaccount`,
typeArguments: [],
functionArguments: [
"0x123...abc", // subaccountAddr
market.market_addr, // marketAddr
chainPrice, // price in chain units
chainSize, // size in chain units
true, // isBuy
0, // timeInForce
false, // isReduceOnly
null, // clientOrderId
null, // stopPrice
null, // tpTriggerPrice
null, // tpLimitPrice
null, // slTriggerPrice
null, // slLimitPrice
null, // builderAddress
null, // builderFees
],
},
});

# Fetch market data from v1/markets endpoint
market = {
    "market_addr": "0x456...def",
    "market_name": "APT/USD",
    "px_decimals": 6,
    "sz_decimals": 5,
    "tick_size": 100,  # $0.0001 (100 / 10^6)
    "lot_size": 10000,  # 0.1 APT (10000 / 10^5)
    "min_size": 100000,  # 1 APT (100000 / 10^5)
}

# User wants to place an order at $5.67894 with size 1.234
user_price = 5.67894
user_size = 1.234

# Step 1: Round price to valid tick size
rounded_price = round_to_valid_price(user_price, market)
# Result: 5.6789 (rounded to nearest 0.0001)

# Step 2: Round size to valid lot size and check minimum
rounded_size = round_to_valid_order_size(user_size, market)
# Result: 1.2 (rounded to nearest 0.1 APT, meets minimum of 1 APT)

# Step 3: Convert to chain units for the transaction
chain_price = amount_to_chain_units(rounded_price, market["px_decimals"])
# Result: 5678900 (5.6789 × 10^6)

chain_size = amount_to_chain_units(rounded_size, market["sz_decimals"])
# Result: 120000 (1.2 × 10^5)

# Step 4: Build and submit transaction
from aptos_sdk.client import RestClient
from aptos_sdk.account import Account

PACKAGE = "0x50ead22afd6ffd9769e3b3d6e0e64a2a350d68e8b102c4e72e33d0b8cfdfdb06"
rest_client = RestClient("https://api.mainnet.aptoslabs.com/v1")

transaction = rest_client.build_transaction(
    sender=account.address(),
    payload={
        "function": f"{PACKAGE}::dex_accounts_entry::place_order_to_subaccount",
        "type_arguments": [],
        "function_arguments": [
            "0x123...abc",  # subaccountAddr
            market["market_addr"],  # marketAddr
            chain_price,  # price in chain units
            chain_size,  # size in chain units
            True,  # isBuy
            0,  # timeInForce
            False,  # isReduceOnly
            None,  # clientOrderId
            None,  # stopPrice
            None,  # tpTriggerPrice
            None,  # tpLimitPrice
            None,  # slTriggerPrice
            None,  # slLimitPrice
            None,  # builderAddress
            None,  # builderFees
        ],
    },
)

Understanding the Values

Example Market Configuration

Let’s say a market has the following configuration:

{
  "market_name": "APT/USD",
  "px_decimals": 6,
  "sz_decimals": 5,
  "tick_size": 100,
  "lot_size": 10000,
  "min_size": 100000
}

What this means:

Price Precision: Prices have 6 decimal places. A price of 5.67 is stored as 5670000 chain units.
Size Precision: Sizes have 5 decimal places on this market. A size of 1.5 is stored as 150000 chain units.
Tick Size: The minimum price increment is $0.0001 (100 / 10^6). Valid prices are: 5.0000, 5.0001, 5.0002, etc. Invalid: 5.00005.
Lot Size: The minimum size increment is 0.1 APT (10000 / 10^5). Valid sizes are: 1.0, 1.1, 1.2, etc. Invalid: 1.05.
Min Size: The minimum order size is 1 APT (100000 / 10^5). Orders smaller than 1 APT will be rejected.

Market-Specific Values

For the actual min_size, lot_size, and tick_size values for each live market, see Market Parameters.

Common Pitfalls

Not rounding prices: Prices must be multiples of tick_size. Always use roundToValidPrice() before converting to chain units.
Not rounding sizes: Sizes must be multiples of lot_size. Always use roundToValidOrderSize() before converting to chain units.
Forgetting minimum size: Orders below min_size will be rejected. The rounding function handles this automatically.
Using wrong decimals: Always use px_decimals for prices and sz_decimals for sizes when calling amountToChainUnits().

Quick Start

Guides

TypeScript SDK

CLI

On-Chain: Reference

On-Chain: Account Management

On-Chain: Order Management

On-Chain: Position Management

On-Chain: Builder Fee

On-Chain: Vault Transactions

Formatting Prices and Sizes for Orders