Prices, sizes, and units

Every numeric field in the API that represents money or quantity is a decimal string. This is the load-bearing contract — get it right and everything downstream works.

Why strings

Floating-point arithmetic loses precision for large notionals. Decimal strings preserve the exact representation. Parse with whatever fixed-precision type your language offers:

Language	Library
Rust	rust_decimal::Decimal
Go	shopspring/decimal
TypeScript	bignumber.js or decimal.js

The SDKs hand back the string verbatim — they do not parse for you, because picking the precision strategy is your decision.

Conventions on the wire

Field	Example	Meaning
price	"155.14"	Quote per base, human-readable
size	"10.0"	Base token units (e.g. SOL)
volume	"42.137"	Same convention as size
open / high / low / close	"154.97"	Same as price
best_bid / best_ask / mid	strings	Optional, omitted on empty side

You will never see on the wire:

• Atom counts (raw on-chain integer base units).
• Lot multiples.
• Oracle units.

The SDK's quoting layer converts the human values you pass to the on-chain integer forms exactly once, at the point of building the instruction. The integer forms are documented in How Sweetspot works for completeness — most integrators never have to think about them.

Pricing helpers (Rust)

For when you need the conversion outside a queue_* call:

use superis::pricing::{human_to_oracle, oracle_to_human, human_size_to_lots};

let market = config.pairs.iter().find(|p| p.base_name == "SOL").unwrap();

let oracle = human_to_oracle(155.14, market);  // → 155_140
let back = oracle_to_human(oracle, market);    // → 155.14
let lots = human_size_to_lots(10.0, market);   // → 10_000

Edge cases (saturate, NaN, negative) are documented in the function-level docs.

Timestamps

• timestamp_us — Unix microseconds since epoch. Used on Trade, Candle, every event.
• slot — Solana slot number. Useful for cross-referencing on-chain data.
• from_sec / to_sec (request) — Unix seconds. Values ≥ 10¹¹ are auto-converted from milliseconds (with a Warning header).
• server_time_us, started_at_us — Unix microseconds.

Enums on the wire

Connect-JSON serializes enums by their proto variant name:

Field	Examples
source	"SOURCE_LIVE", "SOURCE_HISTORICAL"
interval	"INTERVAL_5M", "INTERVAL_1H", "INTERVAL_1D"
side	"SIDE_BUY", "SIDE_SELL"
state	"HEALTH_STATE_HEALTHY", "HEALTH_STATE_DEGRADED"

Binary protobuf clients see integer variant numbers. The SDKs all expose the typed enum, so you don't have to hardcode either form.