privium.trade places a market or limit order in one call: it reads the market, sets the limit, builds the Intent, signs it with the account’s auth key, seals it to the enclave and submits it to intake. No wallet prompt, and no transaction of the account’s lands on chain.
The market's pair id, baseMint_quoteMint, as the market list returns it.
side
'buy' | 'sell'
buy or sell the base asset.
size
string
A decimal amount in whole tokens of the base, or of the quote when sizeIn is quote.
sizeIn
'base' | 'quote' (optional)
base, the default, or quote. A quote size becomes the largest base size it funds at the limit, with the fee for a buy.
limit
string (optional)
A decimal limit price, quote per base. Absent, the order is a market order.
expirySlot
bigint (optional)
The slot the order expires at. Absent, the market's current slot plus ⌈60,000 / slotTimeMs⌉ slots, about one minute.
maxSlippageBps
number (optional)
A market order's maximum slippage in basis points, a whole number from beta0Bps to 1,000; 300 when absent. The protective limit sits this far from the mid, and a route bound wider than it throws ABOVE_MAX_SLIPPAGE. A limit order ignores it.
Reads the market with GET /v1/markets/{pair}. A market whose trading is escape throws ESCAPE_ACTIVE. A market that is not open, or whose base or quote has no Registry index, gets an admission request (POST /v1/markets/{pair}/admit) and the call throws ASSET_NOT_ADMITTED.
Requires the market’s feeBps to be set, as integer basis points, for a buy or a sell.
Sets the limit. A limit order converts limit exactly at the pair’s priceExponent, and needs no mid: it rests while the mid is stale. A market order needs a mid that is present, not stale, no older than the config’s maxPriceAgeMs and within the confidence bound κ, takes it at the pair’s priceExponent with any finer digits dropped, reads the market again with its exact size and side, and checks that size’s route bound: it must match the size and side, be at least β₀ and stay below 10,000 bps (BAD_LIMIT), and be no wider than maxSlippageBps (ABOVE_MAX_SLIPPAGE). It then sets the protective limit from the mid and maxSlippageBps, as Market and limit gives it. maxSlippageBps defaults to DEFAULT_MAX_SLIPPAGE_BPS, 300, and must be a whole number from the config’s beta0Bps to 1,000 (BAD_LIMIT).
Sets the size. A quote size (sizeIn: 'quote') becomes the largest base size whose cost at the limit, with the fee for a buy, fits it. A quote-sized market order quotes the route bound again for that base size, and a buy whose reservation at the new limit exceeds the budget throws BAD_LIMIT.
Registers the account with the enclave before the instance’s first Intent (The one signature).
Builds the 73-byte trade Intent with a fresh nonce and the expiry, signs it with the auth key, pads it to 160 bytes and seals it with HPKE to the active enclave key, read again from GET /v1/config just before (Intent).
Submits it with POST /v1/intake and opens the replies; an envelope that does not open throws DECRYPTION_FAILED, and each order result goes through the instance’s order tracking.
The enclave's replies from intake's answer, decrypted and checked against the enclave's signing key; an order result the instance already holds in that state or a later one is left out.
Sends the same sealed bytes again and resolves to this submission, updated.
An unreachable intake does not throw. When intake answers INTAKE_UNAVAILABLE, or fetch fails at the network, the submission comes back unsent with its sealed bytes, and retry() sends exactly those bytes again: identical bytes are answered once, with the same ticket and the same replies. An Intent intake refuses throws with the refusal’s own code and leaves nothing to retry (Refusals).
results holds the order’s first OrderResult, from intake’s answer, unless the instance already holds that state or a later one for the order (Order tracking). An order the enclave accepts but cannot fund is answered as rejected with its reason, not thrown.
Intake answers with the order’s first state: waiting for Crossing k, or rejected with the reason below-minimum when its size is under one denomination unit of the base, the base asset’s denominationUnit (Asset), or unfunded when the unreserved balance does not cover its reservation. From then on each Crossing the order takes part in sends it one more state, on watchFills:
State
When
filled
It fills, and what remains is under one denomination unit of the base: that remainder finishes and its reservation is released.
partly-filled
It fills in part and at least one unit remains, which keeps resting. It keeps this state at each later Crossing that gives it no new fill.
resting
Nothing of it has filled and it takes no fill at this Crossing: its limit is not met, or the pair has no valid mid.
expired
Its expiry slot is before the Crossing’s cutoff. It leaves the book and its reservation is released.
rejected
unfunded: the balance no longer covers its reservation at this Crossing.
A filled or partly filled state carries the crossed part, the routed part and the fee. A market order runs the same way under its protective limit (Market and limit). Without expirySlot, an order of either kind expires about one minute after it is placed.
A decimal price, quote per base, to the integer count of 10exponent quote whole tokens per base whole token that Intents carry. A price written with more decimal places than the unit carries must still be a whole number of units.
What an order holds of its funding balance while it is open: its base size for a sell, and for a buy its size times its limit times (1 + fee rate), in quote units rounded up. A sell reads only its size. For a buy, a fee rate of null or outside 0 to 10,000 throws a plain Error, CONFIGURATION_REQUIRED, and decimals or an exponent out of range throw Invalid asset scale.