SDK Guide#
SDKs for building applications on the Seesaw binary prediction market protocol.
Seesaw ships two SDK families in three languages:
- Trust-based — convenience SDKs that use Seesaw's hosted indexer/API for discovery and aggregated reads, plus local instruction builders and PDA derivation. Fastest path to a working integration.
- Trustless — account-resolution SDKs that derive, discover, and validate every account directly from any standard Solana RPC node. No Seesaw-operated service is ever in the trust path. If Seesaw's entire infrastructure disappeared, you could still trade, cancel, redeem, and exit.
Both families produce instructions for the same on-chain program; neither one ever holds keys, signs, or submits — signing and sending are always your wallet/RPC stack's job.
SDK Family Matrix#
| Language | Trust-based | Trustless |
|---|---|---|
| TypeScript | @seesaw/core (packages/core) | @seesaw/trustless (packages/trustless) |
| Python | seesaw-sdk (packages/sdk-python) | seesaw-trustless (packages/trustless-python) |
| Rust | seesaw-sdk (packages/sdk-rust) | seesaw-trustless (packages/trustless-rust) |
The trust-based SDKs share golden test vectors (packages/test-vectors) so
instruction encoding is byte-identical across languages. The trustless SDKs
build on the trust-based encoders and add validated, fail-closed account
resolution. For the trustless deep dive (trust model, safeguards, all three
languages), see the Trustless SDK guide.
Kit v6, not web3.js.
@seesaw/coreand@seesaw/trustlessare built on Solana Kit v6 primitives (@solana/addresses,@solana/instructions,@solana/transactions,@solana/codecs, …). Addresses are KitAddressstrings, notPublicKeyobjects, and instruction builders return KitInstructionvalues. Legacy@solana/web3.jsis not a dependency of either package.
Which Should I Use?#
| If you… | Use |
|---|---|
| Are building a UI / bot and want market lists, positions, and fee config with one HTTP call | Trust-based (@seesaw/core API client) |
| Want WebSocket streams for live market / orderbook / position updates | Trust-based (client.streams) |
| Must not depend on Seesaw infrastructure (self-custody tooling, exits, audits) | Trustless (@seesaw/trustless) |
| Need every account validated (owner, discriminator, size, PDA re-derivation) before signing | Trustless |
| Want the cheapest read path and already run your own RPC node | Trustless |
| Just need instruction builders / PDA derivation / account decoders | Either — both use @seesaw/core's builders and codecs |
You can mix them: e.g., discover markets through the hosted API for speed, but resolve and validate the accounts of a live order trustlessly before signing.
New to Seesaw? Start with the Quickstart — install the package, list live markets, and read the order book in ~15 minutes.
In This Section#
- Quickstart — install, list markets, read the order book (15 min, no order placement)
- Installation — packages, dependencies, ESM/TypeScript setup, requirements
- Reading Data — PDAs, decoding, market/orderbook/position reads in both families, slippage estimation
- Building Transactions — place/cancel/redeem in both families, market creation, Kit signing flow
- Trustless SDK — trust model, safeguards, TS/Python/Rust deep guide
- Examples — complete copy-pasteable programs
- Referral and Creator Fees — resolver, lock wizard, creator dashboard
- Python SDK | Rust SDK | Widgets | AI Agents
Key Concepts#
PDAs (Program Derived Addresses)#
All Seesaw accounts are PDAs derived from deterministic seeds. The full seed table and derivation helpers are listed in Reading Data and the complete PDA reference is in Constants.
@seesaw/core exports a derivation helper for each PDA type (deriveConfigPda,
deriveMarketPda, deriveOrderbookPda, deriveVaultPda, derivePositionPda,
deriveYesMintPda, deriveNoMintPda, deriveYesEscrowPda,
deriveNoEscrowPda, deriveTraderLedgerPda, deriveAssetPda, plus the
referral PDAs).
Order Sides and Types#
enum OrderSide {
BuyYes = 0, // Buy YES shares (bullish)
SellYes = 1, // Sell YES shares
BuyNo = 2, // Buy NO shares (bearish)
SellNo = 3, // Sell NO shares
}
enum OrderType {
Limit = 0, // Match, then rest on the book
PostOnly = 1, // Maker-only; rejected or repriced if it would cross
ImmediateOrCancel = 2, // Match what's available, cancel the rest
}
All NO orders are mapped onto the single canonical YES book via the complement
price: BuyNo @ q → Ask @ (10000 − q), SellNo @ q → Bid @ (10000 − q).
Prices are basis points in [0, 10000]. See How the order book works.
Units#
Quantities are bigint in base units (settlement mint has 6 decimals).
Prices are number in basis points. These conventions match the on-chain
representation across all SDK functions.
Requirements (TypeScript)#
See Installation for the full setup guide. Quick summary:
- Node.js 18+ (the trustless RPC client uses global
fetch) - TypeScript ~5.7 recommended;
target≥ ES2020 (the SDK usesbigint) - Solana Kit v6 (
@solana/*v6 packages) for signing/sending — not@solana/web3.js