Prices, sizes, and units

There are two number systems to know about:

• On the wire (the gRPC APIs), Decimal fields express prices, sizes, balances and USD amounts as decimal strings in human units.
• On-chain, everything is an integer on the contract's grid — sizes in lots, prices in ticks — or a fixed-point number.

Use on-chain units when you build instructions, decode accounts or reconcile against the chain.

Decimal strings on the wire

Market, account and fill money fields in flint.margin.user.v1 and flint.margin.maker.v1 use Decimal { value } wrapping a string such as "155.14". Parse it with a fixed-precision type, never a float:

The server converts these Decimal fields using the contract grid and mint decimals. Raw quoting state is an exception: GetQuotingState.payload_json contains grid integers, including ticks and lots. Transaction bytes, account bytes and fields explicitly named in lamports or other raw units also require their documented on-chain units.

Sign conventions

The contract grid

Each perp fixes two scales at listing, and every on-chain size and price lives on them:

1 lot  = 10^(−lot_scale) units of the underlying
1 tick = tick_size atoms of the PnL currency
price  = ticks per lot

A price on-chain is therefore "how many ticks one lot costs". The human forms follow directly:

lot_size     = 10^(−lot_scale)                                base units
price_step   = tick_size / 10^(settlement decimals) / lot_size     settlement per base unit

quantity     = lots  × lot_size
price        = ticks × price_step
fill value   = lots  × ticks × tick_size                      settlement atoms

PerpMarketService.ListPerpMarkets returns lot_size and tick_size already in human form: its tick_size is the price_step above (the price increment per base unit), not the raw on-chain atom count. min_order_quantity is one lot.

Illustrative grids that settle in USDC (6 decimals). Read the current grid from ListPerpMarkets before building a transaction:

So "buy 2.5 SOL with a worst price of $150.25" on SOL-USDC-PERP is lots = 2,500, limit = 150,250.

Converting a limit price

Round a limit toward the side that protects you: a buy limit down, a sell limit up, so the on-chain price is never worse than the one you meant.

import BigNumber from "bignumber.js";
 
const priceStep = new BigNumber(market.tickSize!.value);   // from ListPerpMarkets
const lotSize = new BigNumber(market.lotSize!.value);
 
const lots = new BigNumber("2.5").div(lotSize);             // must be a whole number
const raw = new BigNumber("150.25").div(priceStep);
const limit = side === "buy"
  ? raw.integerValue(BigNumber.ROUND_FLOOR)
  : raw.integerValue(BigNumber.ROUND_CEIL);

use rust_decimal::Decimal;
use std::str::FromStr;
 
let price_step = Decimal::from_str(&market.tick_size.unwrap().value)?;
let lot_size = Decimal::from_str(&market.lot_size.unwrap().value)?;
 
let lots = Decimal::from_str("2.5")? / lot_size;           // must be a whole number
let raw = Decimal::from_str("150.25")? / price_step;
let limit = if is_buy { raw.floor() } else { raw.ceil() };

Reject a size that is not a whole number of lots rather than rounding it silently.

Grid limits

A listing is only accepted if one lot is a whole number of the underlying's atoms and the oracle can resolve one lot's price to within half a tick.

On-chain number formats

Fee rates quoted in basis points are stored truncated, so a quoted whole-tick fee lands exactly and any other one is at most one tick under the quoted rate. Every value the program derives rounds in the protocol's favour: margins and fees up, collateral and rebates down.

Identifiers

Trader accounts are PDAs seeded by ["trader_account", trader_id]; contract, quoting and cache accounts are PDAs of the program too. See On-chain clients for derivation helpers.

Time

Every live response carries a DataProvenance: the commitment it was read at, the slot, and when the server observed it. Treat it as an observation, not proof of finality.

Enums on the wire

On-chain, an order's side is a Direction — Long or Short — the way the taker wants to end up positioned. Its PerpOrderKind is Gtc, Gtd, Ioc or Fok. Price, expiry and post-only options belong to the selected kind; see On-chain clients. A resting order's side is a MakerSide, Buy or Sell.

SDK values vs on-chain values

Convert exactly once, at the boundary where you build the instruction, with the grid from ListPerpMarkets. See TypeScript, Rust and On-chain clients.