Amounts and decimals

The API never sends money as a floating point number. SUI amounts are integers of MIST, sent as decimal strings, so no precision is lost in JSON.

MIST

1 SUI is 1,000,000,000 MIST (10^9). Every field whose name ends in Mist is a MIST amount as a decimal string.

• The string holds digits only: no decimal point, no exponent, no separators. Profit and loss fields can start with -.
• null means unknown or not applicable, for example floorMist on a collection with no listings or topOfferMist with no offers. It is not zero.
• Request bodies take MIST strings too. POST /quotes/offer answers 400 bad_request if priceMist is not an integer string.

Every JSON object response also carries a units object that states this, so a client can check it without reading the docs:

"units": { "amount": "MIST", "decimals": 9, "symbol": "SUI" }

Other numbers in responses are plain JSON numbers: counts (sales, owners, supply, listedCount), percentages (fields ending in Pct, already multiplied by 100, so 14.61 is 14.61%), basis points (royaltyBps) and ranks.

Price and all-in price

A listing carries both the venue's price and what a buyer actually pays:

{
  "venue": "tradeport",
  "source": "tradeport/simple",
  "priceMist": "63000000000",
  "allInMist": "68040000000",
  "feeMist": "1890000000",
  "commissionMist": "0"
}

Here the price is 63 SUI, the venue fee is 1.89 SUI (3%) and the creator royalty is 3.15 SUI (5%), so the buyer pays 68.04 SUI.

Use allInMist to compare listings across venues. Floors (floorMist), sort=price_asc and sort=price_desc, and the minMist and maxMist filters all use the all-in price. Listing objects also carry an extra object with venue-specific fields; do not rely on its contents.

For offers, netMist on the offer book is what a seller receives. Bidders pay fees and royalty on top, so netMist equals the offer price on every venue.

USD values

USD values are JSON numbers, not strings, and are approximate. Use them for display only.

To show a MIST amount in USD, convert it to SUI exactly and multiply by suiUsd at display time.

Other coins

Marketplace prices are in SUI. Notifications can carry amounts in other coins, so their amount object states its own decimals:

{
  "raw": "2500000000",
  "decimals": 9,
  "symbol": "SUI",
  "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
  "usd": 2.28
}

raw is an integer string in the coin's smallest unit. Divide by 10 to the power of decimals to get whole coins. usd is null when no price is known.

Converting safely

Parse MIST strings as big integers or decimals. A JavaScript Number loses precision above 2^53 (about 9,007,199 SUI), which market caps and volumes can exceed.

# jq parses numbers as doubles; keep amounts as strings and convert with bc.
curl -s "https://rare.market/api/v1/collections/popkins" \
  | jq -r '.stats.floorMist' \
  | xargs -I{} echo "scale=9; {} / 1000000000" | bc

Sum, compare and subtract in MIST as integers. Convert to SUI or USD only to display.

Times

Times are ISO-8601 strings in UTC with milliseconds, for example "2026-10-26T23:19:47.085Z". Parse them with new Date(...) in JavaScript or datetime.fromisoformat(...) in Python 3.11 and later.

Two exceptions:

• checkpoint in GET /status is a Sui checkpoint number, not a time.
• Notifications carry cpTs (checkpoint time) and sentAt as Unix times in milliseconds.