A market maker rests firm quotes in the enclave: a pair, a side, a size and a price, until an expiry. Each Crossing, after traders’ orders cross at the mid, the Residual that is left takes the quotes priced better than its route, best price first, and only the rest goes out as a swap. A quote meets nothing but the Residual, and no one sees it before the batch is sealed, so no faster reader picks it off.
Place a quote#
const { items } = await privium.api.markets({ q: 'SOL', quote: 'USDC' })
const pair = items[0].pair
const { countdown } = await privium.api.home()
const expirySlot = BigInt(countdown.currentSlot) + 9_000n
await privium.quote({ pair, side: 'sell', size: '2', price: '150.20', expirySlot })
privium.quote reads the market, signs a quote Intent with the account’s auth key, seals it to the enclave and submits it to intake, as every Intent goes (Intent kinds). A sell quote sells base into a buy Residual; a buy quote buys base from a sell Residual. The price is the pair’s quote per base, and the quote always fills at exactly that price. Both assets of the pair must be admitted, or the call throws ASSET_NOT_ADMITTED before anything is sent.
Intake answers with a QuoteResult: resting once the enclave holds it, or rejected with its reason.
reason |
The enclave found |
|---|---|
unfunded |
The account’s unreserved balance does not cover the quote’s reservation. |
below-minimum |
The size is under one denomination unit of the base. |
policy-frozen, policy-instrument, policy-limit |
The account’s policy refuses it, as it would an order. A buy quote counts toward the position limit. |
A resting quote is reserved at its own price, as a limit order is (Reservation): a buy quote holds its size times its price plus the fee rate φ in the quote asset, a sell quote holds its size in the base. A trade key with the trade scope places quotes for its account (Privium inside a terminal or bot).
| Parameter | Type | Meaning |
|---|---|---|
pair |
string |
The market's pair id, baseMint_quoteMint, as the market list returns it; both assets must be admitted. |
side |
'buy' | 'sell' |
buy to buy base from a sell Residual, sell to sell base into a buy Residual. |
size |
string |
A decimal size in whole base tokens. |
price |
string |
A decimal price, quote per base; the quote fills at exactly this price. |
expirySlot |
bigint |
The slot after which the quote no longer fills; required. |
| Code | Stage | Message |
|---|---|---|
VALIDATION_ERROR |
validation | Enter a nonnegative decimal amount. |
VALIDATION_ERROR |
validation | Amount has more precision than this asset. |
VALIDATION_ERROR |
validation | Enter a decimal price at the admitted pair precision. |
BAD_LIMIT |
validation | The price is not a multiple of the admitted pair precision. |
ASSET_NOT_ADMITTED |
validation | Quotes need both assets admitted. |
VALIDATION_ERROR |
validation | A quote needs a positive size and price. |
PROGRAM_UNAVAILABLE |
read | The enclave quote has not been indexed yet. Retry when its attestation is available. |
CONFIGURATION_REQUIRED |
read | The API changed its Pool program. Reconnect explicitly. |
DECRYPTION_FAILED |
read | This envelope cannot be opened by this account. |
INTAKE_UNAVAILABLE |
send | The account registration is sealed and the intake is unreachable. |
How a quote fills#
Each Crossing runs in order: every pair crosses its traders’ orders at the mid, each token crosses its SOL and USDC pairs as one book, and what is left on each pair is its Residual. Before the Residual routes, the Coprocessor takes Jupiter’s quote for routing it whole, and the quote step fills from resting quotes:
- It takes the opposing quotes, sell quotes for a buy Residual and buy quotes for a sell Residual, whose price beats the route’s quote for the whole Residual and lies inside the bound the Residual’s orders allow, the mid × (1 ± bound).
- Best price first: the lowest sell price for a buy Residual, the highest buy price for a sell Residual.
- Quotes at one price share what is left of the Residual pro rata by their remaining size, split by largest remainder with the Crossing’s seed, as every pro rata split in the Crossing.
- Each quote fills at its own price. The Residual’s orders take the quoted part in proportion to their share of the Residual and pay its quoted total in the same proportion.
- Only what quotes did not fill routes, quoted again and swapped from the Pool’s vault. A Residual quotes fill whole sends no swap.
Every quoted fill pays φ on both sides, as a crossed fill does, and settles inside the Ledger: the vaults’ totals do not move, and the chain sees only a smaller Residual swap, or none. A quote’s fill folds into its account’s fill as its quoted part (OrderResult), and a quote keeps resting with what it has left until it fills, expires or is cancelled. A quote whose remaining size falls under one denomination unit of the base leaves the book.
In the engine’s own worked case, SOL is at $150. Buyers want 3 SOL and sellers 1, so 1 SOL crosses at the mid and the Residual is a buy of 2 SOL, which the route quotes 40 bps over the mid, $150.60. Four sell quotes rest: 0.5 SOL at $150.20, 1 SOL each from two makers at $150.40, and 1 SOL at $150.70.
| Quote | Fills | At |
|---|---|---|
| 0.5 SOL at $150.20 | 0.5 SOL, whole | $75.10 |
| 1 SOL at $150.40 | 0.75 SOL, its pro rata half of the 1.5 left | $112.80 |
| 1 SOL at $150.40 | 0.75 SOL | $112.80 |
| 1 SOL at $150.70 | nothing: worse than the route |
The buyers pay $300.70 for the 2 SOL, $1.20 less than the route’s $301.20, and nothing routes. Each side pays φ on its part: $0.0751 for the first quote.
List and cancel#
const quotes = await privium.quotes()
for (const q of quotes) if (q.state === 'resting') await privium.cancel(BigInt(q.nonce))
privium.quotes() lists the account’s resting quotes from the enclave’s status for the account, each with the size it has left. privium.cancel(nonce) takes a quote out as it takes out an order, and its reservation is freed at once; the answer is the quote in state cancelled. A quote past its expirySlot no longer fills and leaves the book.
| Code | Stage | Message |
|---|---|---|
PROGRAM_UNAVAILABLE |
read | The enclave quote has not been indexed yet. Retry when its attestation is available. |
CONFIGURATION_REQUIRED |
read | The API changed its Pool program. Reconnect explicitly. |
DECRYPTION_FAILED |
read | This envelope cannot be opened by this account. |
INTAKE_UNAVAILABLE |
send | The account registration is sealed and the intake is unreachable. |
INTAKE_UNAVAILABLE |
read | The account status intake is unreachable. |
UPSTREAM_UNAVAILABLE |
read | The enclave returned no account status. |
QuoteResult#
| Field | Type | Meaning |
|---|---|---|
kind |
"quote" |
quote. |
id |
string |
The quote's id, its Intent hash. |
nonce |
U64 |
The quote's nonce; cancel takes it. |
base |
integer |
The base asset's Registry index. |
quote |
integer |
The quote asset's Registry index. |
side |
"buy", "sell" |
buy or sell: the side the quote takes against a Residual. |
size |
U64 |
The size still open, in the base's base units. |
price |
U64 |
The quote's price in the pair's price units, the same units as an order's limit. |
expirySlot |
U64 |
The slot after which the quote no longer fills. |
state |
"resting", "cancelled", "rejected" |
resting while it can fill; cancelled once a cancel took it out; rejected when intake refused it. |
reason |
"unfunded", "below-minimum", "policy-frozen", "policy-instrument", "policy-limit" or null |
On a rejected quote: unfunded, below-minimum, or a policy reason; null otherwise. |
What the chain and Pool show#
A quote Intent seals to the same 4,096-byte class as every extended Intent, and quotes live in the enclave’s sealed state, so nothing on chain shows a quote or which accounts make them. Each Commit’s diff reports the Crossing’s quoted notional and what quotes saved against the route, beside its crossed and routed notional; a diff with quoted fills is PVD2 (Diff). Pool shows them per Crossing and since launch (GET /v1/pool).