Skip to content

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).

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 none
const 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 summary

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

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.

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.

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.

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.