• Reading the docs…
Start trading

SDK

Privium inside a terminal or bot

A trade key lets a terminal or bot trade an account without its wallet: the account issues the key with a scope, a notional cap per Crossing and an expiry, and the terminal connects with it. The key places and cancels orders and reads balances and fills; it moves no money out. A terminal that names its own integrator id is paid a fee on every fill it places, inside the Ledger, in the same Commit as the fill.

Issue a trade key#

issue.ts
const issued = await privium.keys.trade({ maxPerCrossingUsd: '5000', scope: ['trade', 'cancel'] })
console.log(issued.key, issued.expirySlot)

privium.keys.trade runs on the account’s own instance, the one connected with its wallet. In order, it:

  1. Registers the account with the enclave if this is its first Intent.
  2. Draws a fresh Ed25519 key seed and a fresh X25519 reply seed in the caller’s process.
  3. Sets the expiry: expirySlot, or 30 days past the current slot when absent, counted in slots at the slot time the API reports (slotTimeMs in Countdown): 12,960,000 slots at 200 ms.
  4. Signs a delegate Intent with the account’s auth key, carrying the key, its reply key, its scope bits, its cap in micro-USD (u64 max for no cap) and its expiry, seals it to the enclave and submits it to intake (Intent kinds).
  5. Builds the view: the balance key of every admitted asset, which opens current balances and no history entry.
  6. Encodes the trade key and the view and returns both with the key’s public half.

The trade key and the view are shown once and never stored by the SDK. Whoever holds both trades the account within the key’s scope. An account holds four trade keys at most. All of a key’s limits are kept and enforced by the enclave, inside the account’s own record.

Input Meaning
scope ['trade', 'cancel'] when absent; ['cancel'] for a key that only cancels.
maxPerCrossingUsd A decimal USD amount: the most notional the key’s trades may reach for one Crossing. Absent, no cap.
expirySlot The last slot the key is accepted at.

TradeKeyIssue#

Field Type Meaning
tradeKey string The trade key, a base64url string beginning PTK1: the account's auth key, the key's seed and its reply seed. Shown once; whoever holds it trades the account within its scope.
view string The view, a base64url string beginning PTV1: the balance keys of the admitted assets, which open current balances and no history.
key string The trade key's public key, as TradeKey.key lists it and keys.revoke takes it.
expirySlot bigint The last slot the key is accepted at.
submission Submission The delegate Intent's submission.

Connect with a trade key#

terminal.ts
import { Privium } from '@privium/sdk'

const bot = await Privium.connect({
  apiUrl: 'https://api.privium.io',
  tradeKey: process.env.PRIVIUM_TRADE_KEY!,
  view: process.env.PRIVIUM_TRADE_VIEW!,
})
const { items } = await bot.api.markets({ q: 'SOL', quote: 'USDC' })
const order = await bot.trade({ pair: items[0].pair, side: 'buy', size: '0.5' })

Privium.connect with tradeKey and view in place of wallet asks for no signature. It decodes both strings, checks they belong to the same account and that the view names this Pool’s program (MALFORMED_BUNDLE otherwise), and connects as that key: every Intent it sends names the account’s auth key and is signed with the trade key, and every reply is sealed to the key’s reply key. bot.isTradeKey is true.

A trade-key instance runs trade, cancel, openOrders, watchFills and readBalances. The enclave accepts its Intents only within the key’s scope, until its expiry and, for trades, while the notional at the limit of the key’s orders for the Crossing they wait for, valued at the latest mid in USD, stays within its cap. Everything else is the owner’s: exit, deposit, disclose, receipt, readHistory, recoverBalancesFromHistory, the Escape and the keys calls throw OUT_OF_SCOPE in the caller’s process before anything is sealed, and intake refuses the same with OUT_OF_SCOPE (Errors).

Revoke and list#

revoke.ts
const keys = await privium.keys.list()
for (const key of keys) if (key.state === 'active') await privium.keys.revoke(key.key)

privium.keys.list reads the account’s status from the enclave and returns its trade keys. privium.keys.revoke takes a key’s public half and signs a revoke Intent with the account’s auth key: from that Intent on, the enclave refuses the key’s Intents with SIGNATURE_INVALID, and its spending for the current Crossing is dropped. A key the account does not hold is refused with OUT_OF_SCOPE. Both are owner only.

TradeKey#

Field Type Meaning
kind "trade-key" trade-key.
state "active", "revoked" active, or revoked on the answer to a revoke.
key Address The trade key's public key, the one its Intents are signed with.
scope "trade", "cancel"[] What the key may send: trade, cancel, or both. Every key also reads the account's status.
maxPerCrossingUsd U64 or null The most notional the key's trades may reach for one Crossing, in micro-USD; null for no cap.
expirySlot U64 The last slot the key is accepted at.

Integrator fees#

integrator.ts
import { Privium } from '@privium/sdk'

const bot = await Privium.connect({
  apiUrl: 'https://api.privium.io',
  tradeKey: process.env.PRIVIUM_TRADE_KEY!,
  view: process.env.PRIVIUM_TRADE_VIEW!,
  integrator: { id: process.env.PRIVIUM_INTEGRATOR_ID!, bps: 20 },
})

A terminal is paid on the trades it places by naming its integrator id and a rate in integrator. Its integrator id is privium.integratorId on its own Privium account: the first 20 bytes of SHA256(privium/integrator/v1 || its auth public key), as base58. Every trade the instance places carries the id and the rate inside its signed bytes. The enclave accepts a rate up to 100 bps (BAD_LIMIT above it) and an id that resolves to a registered account (ACCOUNT_REQUIRED otherwise).

At settlement each fill pays ⌊quote notional⋅bps/10,000⌋\lfloor \text{quote notional} \cdot \text{bps} / 10{,}000 \rfloor in the quote asset beside the protocol fee: the trader’s balance is debited and the integrator’s credited in the same Commit, inside the Ledger, so nothing reaches the chain per integrator. A buy reserves for both fees, x⋅ℓ⋅(1+φ+bps/10,000)x \cdot \ell \cdot (1 + \varphi + \text{bps}/10{,}000). The trader’s order result carries integratorFee, its history a fee entry described protocol and integrator fee whose amount is both, and the integrator’s history one integrator-fee entry per asset per Crossing (HistoryEntry). Either side states its total in a Receipt with the integratorFeesPaid or integratorFeesReceived claim (receipt).

Integrator#

Field Type Meaning
id string The integrator's id, integratorId on its own account.
bps number The rate in basis points, 0 to 100, charged on each fill's quote notional.