SDK
@sagitta/sdk is the one TypeScript package every Sagitta client runs on: sagitta.broker itself, the API,
the keeper and the agent CLIs. It is built on @solana/kit, and it needs
no browser, Node or Bun API, so the same code runs everywhere.
It never holds a key and never sends anything. Reads take an RPC client you create; builders hand back instructions and an unsigned message for your own wallet to sign.
The package lives in Sagitta’s repository at packages/sdk and is not on npm. Without it, POST /api/arena builds the
same transactions over HTTPS (see The trading API), and the programs take the same
instructions from any client of their IDLs (see Exit without the site).
Programs come from you
Section titled “Programs come from you”The SDK names no program of its own. You pass a deployment: core’s program id and each version’s market program.
A deployment record from packages/config fits as it is, or readDeployment builds one from core’s id alone, reading
every version’s market program from core’s own records, which is what the CLIs trust.
import { createSolanaRpc } from "@solana/kit";import { DEPLOYMENT } from "@sagitta/config";import { programsOf, readMarket, readReferral, tx } from "@sagitta/sdk";
const rpc = createSolanaRpc(rpcUrl);const p = programsOf(DEPLOYMENT); // core and the newest market program
const view = await readMarket(rpc, p, market);const binding = await readReferral(rpc, p, market, signer.address); // null when there is noneconst buy = await tx.commitMint(p, view, { trader: signer, side: 0, gross: 50_000_000n, binding }); // 0.05 SOL on UP// buy holds the instructions, an unsigned v0 message with the signer as fee payer, and a plain-words summaryClients
Section titled “Clients”Each program’s IDL is a set of Codama nodes kept beside the program and pinned to its code by a drift test. The SDK
carries the clients generated from them, coreClient and marketClient: every account, instruction, address
derivation, type and error of each program. Every address the SDK derives comes from those clients, so its seeds are
the programs’ own.
Reads use getMultipleAccounts, 100 accounts a call. Solana’s RPC can’t answer at a fixed past slot, so a read of more
than 100 accounts isn’t one snapshot: each part asks for the newest slot seen so far or later, and the read returns its
newest and oldest slot, equal when it was one snapshot. An account that doesn’t decode as it should throws
AccountShapeError, and a market must sit at its own address.
| Function | What it returns |
|---|---|
readMarket, readMarkets |
A market’s kind, source, status, version, both pots, supplies and NAVs, each side’s epoch and mint, the queue, the escrow, owed and burn totals, and its copied settings |
readTickets, readQueue |
Tickets and where each stands: waiting, due, or settled with what it owes |
readHoldings |
An owner’s tokens on both sides, older epochs included, with what each converts to now |
readWallets, readReferral |
Market wallets’ balances, and a recipient’s referral binding |
readEpochs |
Closed epochs’ records: what each still converts |
readRing, readingAt, stockReadingAt |
A source’s reading ring, and a target’s reading in it by core’s own rules: ready, lost or pending |
readGate, readConfig, readRecords, readVersions, readDeployment |
Core’s mint gate for a market, its settings, its market records and its versions |
Quotes
Section titled “Quotes”The quoting functions compute a buy, a cash-out, a conversion or an exit locally from a market view, so a board can quote every market without a call per quote. They run the same settlement arithmetic as the programs: a shared set of test vectors pins the TypeScript to the Rust kernel bit for bit.
A quote is what a ticket would get at the market’s state now. The ticket fills at the first reading after its commit, whose move can still change the result; see Delayed NAV.
Transactions
Section titled “Transactions”Every builder lives under tx and returns the instructions, an unsigned v0 message with the signer as fee payer, and a
summary in plain words: the action, one line of text for a confirm dialog, the market, side, amount and epoch, the
deposits it may open (each returned to the signer), the rent it may spend that the burn vault takes at close, every
account it writes and why, and its fee. Every message leaves room for a compute-unit limit and price, which
withComputeBudget adds.
| Who | Builders |
|---|---|
| Traders | commitMint, commitRedeem, convert, deliver, claim, donate, openWallet, withdraw, closeWallet, closeReferral |
| Keepers | execute, poke, retire, retireIdle, quarantineHead, prepareEpoch, collectFees, sweep, closeEpoch, closeMarket |
| Listers | createRing, then createMarket once the ring holds a reading at most 600 slots old |
execute and poke carry as many of the given tickets as fit, with the wallets they credit; the rest wait for the next
call. convert takes the epoch to convert to, the current one by default; planConvert splits a catch-up many epochs
long into converts that each fit one transaction, and joinTxs puts the last of them in one transaction with the
commitRedeem that cashes it out. wireMessage adds a blockhash and compiles the message for a wallet;
readWireMessage reads one back.
The account guard
Section titled “The account guard”Every builder runs the account guard on its own instructions, and it fails closed:
- every account a transaction writes must be an address the builder derived, the signer’s own account or token account, or an account the ticket names (its payer, its owed account and that account’s token account);
- the only programs called are core, the market program, the associated token program and the compute-budget program;
- the signer is the only signer;
- the compute budget is at most one limit and one price, and the priority fee stays within a cap the caller gives.
A recipient other than the signer is instruction data the guard never sees, so the payee check covers it: the
builders refuse every address the market and core derive around the commit, the platform’s programs and sysvars, and
the signer’s own market wallet, referral binding and token accounts; and, from the recipient’s account, a program or an
account core, the market program, a token program, the loader or the sysvar owner owns. Such a payee could never sign
to collect. A refusal throws PayeeRefused, naming the argument, the address and what it is.
A message someone else built is checked with checkWireMessage(message, expected, { payer, maxPriorityFeeLamports })
before your wallet signs it: the fee payer is your own wallet and the only signer, the lifetime is a blockhash, the
compute budget is one limit and one price, the priority fee is within your own cap, and every other instruction matches
your own build of the same request. It returns the fee from the message’s own bytes, for the confirm dialog.
Errors and events
Section titled “Errors and events”errorKeyOf turns anything a send throws into one key: a program error’s name, such as BelowMinimum, attributed to
the program that failed, or one of five send failures (UserRejected, WalletUnsupported, BlockhashExpired,
InsufficientFunds, Unknown). Core’s errors start at 6000 and the market program’s at 7000. events.ts decodes every
event of both programs from a transaction’s inner instructions, including the readings in ReadingsPosted, which
GET /api/readings serves, and the operations in a scheduled timelock batch.